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

[Junio C Hamano <gitster@pobox.com>]

Jasper Mayone <me@jaspermayone.com> writes:

> 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.

Is this the only item that can emit an arbitrary sequence of bytes
(other than NUL in the middle)?  %(contents:body) can have multiple
lines for obvious reasons but we do not talk about quoting at all.

I am not saying I do not want to see this added.  I am wondering if
there is a more central place we can describe the choices fully
(including "use --shell or %00") and sprinkle short pointers from
%(worktreepath) and other places.

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

OK.  When a user wants to clean it up, for-each-ref would not be the
tool to use ("git worktree list" is), so this may be good enough.
If somebody has specific needs, they can add %(worktreepath:all) or
something to fill the gap.

Assuming that we will leave the "shouldn't we have a single quoting
help that is referred to from places?" question out, this step looks
good to me.

> +	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