Re: [PATCH v1 5/6] Add porcelain V2 documentation to status manpage

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

Jeff Hostetler <jeffhost@microsoft.com> writes:

> +A series of lines are then displayed for the tracked entries.
> +
> +    <xy> <sub> <mA> <mB> <mC> <mD> <shaA> <shaB> <shaC> R<nr> <path>[\t<pathSrc>]
> +
> +    Field       Meaning
> +    --------------------------------------------------------
> +    <xy>        The staged and unstaged values described earlier, with
> +                unchanged indicated by a "." rather than a space.

Ahh, this is where these mysterious xy came from.  You just needed
two random consecutive letters, and they could have been ab, ij, or
jk.  I don't like any of them ;-)

Also I have trouble with the "staged and unstaged" here, especially
the latter, as the word implies the user did "git rm --cached" on
the path earlier, which is not the case.  You are saying what is in
the index and what is in the working tree.

Perhaps using iw instead of xy to make them in sync with the way
"git diff --mnemonic-prefix" denotes the contents in the index and
in the working tree?  Together with s/staged/in the index/ and
s/unstaged/in the working tree/, the result would become more
consistent with the rest of the system, I suspect.

> +    <m*>        The file modes for the entry.
> +                For unmerged entries, these are the stage 1, 2, and 3,
> +                and the worktree modes.
> +                For regular entries, these are the head, index, and
> +                worktree modes; the fourth is zero.
> +    <sha*>      The SHA1 values for the entry.
> +                For unmerged entries, these are the stage 1,2, and 3 values.
> +                For regular entries, these are the head and index values;
> +                the third entry is zero.

To future-proof, we should use "object name" for what you call "SHA1
value" here, I would think.

> +    R<nr>       The rename percentage score.

s/percentage score/score/.  Do you differentiate between renames and
copies?

> +    <path>      The current pathname. It is C-Quoted if necessary.
> +    <pathSrc>   The original path. This is only present for staged renames.
> +                It is C-Quoted if necessary.

Seeing "if necessary" makes me wonder if we want to define when it
is "necessary".