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

[Phillip Wood <phillip.wood123@gmail.com>]

Hi Jasper

Thanks for adding this, it looks good

Phillip

On 02/11/2026 18:29, Jasper Mayone wrote:
> 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