[PATCH v5 2/5] doc: for-each-ref: say how to read %(worktreepath) safely

[Jasper Mayone <me@jaspermayone.com>]

The path that %(worktreepath) gives can contain a newline, which
breaks a script that reads one record per line. Say how to avoid
that: use a quoting option, or end the atom with %00 and look for the
NUL before the LF that ends the record.

Also say that only one worktree is shown when a branch is checked out
in more than one worktree.

Suggested-by: Phillip Wood <phillip.wood123@gmail.com>
Signed-off-by: Jasper Mayone <me@jaspermayone.com>
---
 Documentation/git-for-each-ref.adoc | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-for-each-ref.adoc b/Documentation/git-for-each-ref.adoc
index a7b31e8aaf..9247737aa7 100644
--- a/Documentation/git-for-each-ref.adoc
+++ b/Documentation/git-for-each-ref.adoc
@@ -183,7 +183,12 @@ but if used together the last option is selected.
 `worktreepath`::
 	The absolute path to the worktree in which the ref is checked
 	out, if it is checked out in any linked worktree. Empty string
-	otherwise.
+	otherwise. If the ref is checked out in more than one worktree,
+	only one of them is shown. The path can contain a newline, so
+	use one of the quoting options such as `--shell`, or follow
+	`%(worktreepath)` with `%00` and parse the output by looking for
+	the `NUL` after the path and then for the `LF` that ends each
+	record.
 
 `ahead-behind:<commit-ish>`::
 	Two integers, separated by a space, demonstrating the number of
-- 
2.56.0