Re: [PATCH v4 7/8] git-status.txt: describe --porcelain=v2 format

[Jeff Hostetler <git@jeffhostetler.com>]

On 08/05/2016 01:50 PM, Junio C Hamano wrote:
> Jeff Hostetler <git@jeffhostetler.com> writes:
>
>> +Porcelain Format Version 2
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +Version 2 format adds more detailed information about the state of
>> +the worktree and changed items.  Version 2 also defines an extensible
>> +set of easy to parse optional headers.
>> +
>> +Header lines start with "#" and are added in response to specific
>> +command line arguments.  Parsers should ignore headers they
>> +don't recognize.
>> +
>> +### Branch Headers
>> +
>> +If `--branch` is given, a series of header lines are printed with
>> +information about the current branch.
>> +
>> +    Line                                     Notes
>> +    ------------------------------------------------------------
>> +    # branch.oid <commit> | (initial)        Current commit.
>> +    # branch.head <branch> | (detached)      Current branch.
>
> In an earlier review I made a noise about "branch.head", but reading
> this together with others in a context, "branch.head" is good and I
> do not see a need to bikeshed it into "branch.name".

right.


>> +    # branch.upstream <upstream_branch>      If upstream is set.
>> +    # branch.ab +<ahead> -<behind>           If upstream is set and
>> +                                             the commit is present.
>> +    ------------------------------------------------------------
>> +
>> +### Changed Tracked Entries
>> +
>> +Following the headers, a series of lines are printed for tracked
>> +entries.  One of three different line formats may be used to describe
>> +an entry depending on the type of change.  Tracked entries are printed
>> +in an undefined order; parsers should allow for a mixture of the 3
>> +line types in any order.
>> +
>> +Ordinary changed entries have the following format:
>> +
>> +    1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>
>> +
>> +Renamed or copied entries have the following format:
>> +
>> +    2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><nr> <path><sep><pathSrc>
>> +
>> +    Field       Meaning
>> +    --------------------------------------------------------
>> +    <XY>        A 2 character field containing the staged and
>> +                unstaged XY values described in the short format,
>> +                with unchanged indicated by a "." rather than
>> +                a space.
>> +    <sub>       A 4 character field describing the submodule state.
>> +                "N..." when the entry is not a submodule.
>> +                "S<c><m><u>" when the entry is a submodule.
>> +                <c> is "C" if the commit changed; otherwise ".".
>> +                <m> is "M" if it has tracked changes; otherwise ".".
>> +                <u> is "U" if there are untracked changes; otherwise ".".
>> +    <mH>        The 6 character octal file mode in the HEAD.
>
> We do want "octal" to be spelled out, but I doubt that we want to
> guarantee to the reading scripts that this will always be 6
> characters.

good point. "octal" is sufficient.


>> +    <mI>        The octal file mode in the index.
>> +    <mW>        The octal file mode in the worktree.
>> +    <hH>        The SHA1 value in the HEAD.
>> +    <hI>        The SHA1 value in the index.
>
> Please avoid inventing a word "SHA1 value" that does not appear in
> Documentation/glossary-content.txt; s/SHA1 value/object name/g.
> This comment applies to the desciption for "U" lines below, too.

ok.


>> +    <X><nr>     The rename or copied percentage score. For example "R100"
>> +                or "C75".
>
> Documentation/diff-format.txt seems to call this differently.
>
> 	The rename or copy "score" number, e.g. "R100", "C75".
>
> perhaps?

right, this is the same score.


>> +    <path>      The current pathname.
>
> Unless you are talking about "2" line, saying "current" is somewhat
> weird.  I _think_ <path> is the name in the index and in the working
> tree, as opposed to the original path in the HEAD, but the
> distinction does not matter for "1" or "U" lines.

Right.  The index path, since we only report renames for
head-vs-index.


> As this table is meant to be shared between "1" and "2", perhaps
>
> 	<path>     The pathname.  In a renamed/copied entry, this
> 		   is the path in the index and in the working tree.
> 	<origPath> The pathname in the commit at HEAD.  This is only
>                     present in a renamed/copied entry, and tells
>                     where the renamed/copied contents came from.
>
> or something like that may clarify it a bit better.  Then in the
> table for "U" lines, we can just say "The pathname".
>
>> +    <sep>       When the `-z` option is used, the 2 pathnames are separated
>> +                with a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09)
>> +                byte separates them.
>> +    <pathSrc>   The original path. This is only present when the entry
>> +                has been renamed or copied.
>
> If it is explained as "the original path", wouldn't it be easier to
> read if it were called "<origPath>" instead of "<pathSrc>"?

yes.


>> +When the `-z` option is given, pathnames are printed as is and
>> +without any quoting and lines are terminated with a NUL (ASCII 0x00)
>> +byte.
>> +
>> +Otherwise, all pathnames will be "C-quoted" if they contain any tab,
>> +linefeed, double quote, or backslash characters. In C-quoting, these
>> +characters will be replaced with the corresponding C-style escape
>> +sequences and the resulting pathname will be double quoted.
>
> Looks good.
>
> I think I saw "C-Quoted" elsewhere (perhaps in a in-code comment),
> which should be spelled consistently i.e. "C-quoted".

Right.

Thanks,
Jeff