[1/6] doc: clarify boundaries of 'git worktree list --porcelain'
diff mbox series

Message ID 20181022204546.20354-2-asheiduk@gmail.com
State New
Headers show
Series
  • various fixes for docs
Related show

Commit Message

Andreas Heiduk Oct. 22, 2018, 8:45 p.m. UTC
Defined delimiters for 'git worktree list --porcelain' make the format
easier to parse in scripts. For example

	sed -n '/^worktree ID$/,/^$/p'

extracts only the information for the worktree 'ID'.

The format did not changed since [1], only the guaranty is added.

[1] bb9c03b82a (worktree: add 'list' command, 2015-10-08)

Signed-off-by: Andreas Heiduk <asheiduk@gmail.com>
---
 Documentation/git-worktree.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

Comments

Eric Sunshine Oct. 22, 2018, 9:14 p.m. UTC | #1
On Mon, Oct 22, 2018 at 4:46 PM Andreas Heiduk <asheiduk@gmail.com> wrote:
> diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
> @@ -270,8 +270,8 @@ Porcelain Format
>  The porcelain format has a line per attribute.  Attributes are listed with a
>  label and value separated by a single space.  Boolean attributes (like 'bare'
>  and 'detached') are listed as a label only, and are only present if and only
> -if the value is true.  An empty line indicates the end of a worktree.  For
> -example:
> +if the value is true.  The first attribute of a worktree is always `worktree`,
> +an empty line indicates the end of the record.  For example:

When I suggested the --porcelain option for "git worktree list" and
provided an example of its proposed output, the idea all along was
that the "worktree" line itself would indicate start-of-stanza. A
blank line between records is superfluous and unnecessary.
Unfortunately, by the time the implementation was posted with blank
line as stanza separator, I was not around to contest it, and it ended
up in a release, after which point it was too late to change it.

So, the tl;dr is that this documentation update agrees with the
original intention as I envisioned it (although I wouldn't be sad to
see the mention of "blank line" dropped altogether, but that's perhaps
a separate battle).

Patch
diff mbox series

diff --git a/Documentation/git-worktree.txt b/Documentation/git-worktree.txt
index e2ee9fc21b..73520434f6 100644
--- a/Documentation/git-worktree.txt
+++ b/Documentation/git-worktree.txt
@@ -270,8 +270,8 @@  Porcelain Format
 The porcelain format has a line per attribute.  Attributes are listed with a
 label and value separated by a single space.  Boolean attributes (like 'bare'
 and 'detached') are listed as a label only, and are only present if and only
-if the value is true.  An empty line indicates the end of a worktree.  For
-example:
+if the value is true.  The first attribute of a worktree is always `worktree`,
+an empty line indicates the end of the record.  For example:
 
 ------------
 $ git worktree list --porcelain