From 976001e47459973b5e72565f3047cc9d9e20241d Mon Sep 17 00:00:00 2001
From: Junegunn Choi <junegunn.c@gmail.com>
Date: Wed, 2 Jul 2025 22:26:56 +0900
Subject: [PATCH] Explain the need to escape placeholders in transform actions

---
 man/man1/fzf.1 | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/man/man1/fzf.1 b/man/man1/fzf.1
index 0cf9f242..0802127e 100644
--- a/man/man1/fzf.1
+++ b/man/man1/fzf.1
@@ -1938,6 +1938,17 @@ e.g.
                     echo "change\-header:Invalid selection"'
     \fR
 
+A common mistake when writing a \fBtransform\fR action is not escaping
+placeholder expressions when passing them back to fzf. In the following
+example, if you don't escape \fB{}\fR, fzf will immediately replace it with the
+single-quoted string of the current item. This causes single quotes to appear
+in the header and footer, and the script will break if any item contains
+double-quote characters.
+
+    \fBfzf \-\-bind 'focus:transform:[[ $FZF_ACTION =~ up ]] &&
+                echo "change\-header()+transform\-footer:echo \\{}" ||
+                echo "change\-footer()+transform\-header:echo \\{}"'\fR
+
 .SS TRANSFORM IN THE BACKGROUND
 
 Transform actions are synchronous, meaning fzf becomes unresponsive while the