Re: [PATCH v2 7/8] status: update git-status.txt for --porcelain=v2

["Jakub Narębski" <jnareb@gmail.com>]

W dniu 2016-07-25 o 21:25, Jeff Hostetler pisze:

> +Porcelain Format Version 2
> +~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Version 2 format adds more detailed information about the state of
> +the worktree and the changed items.

I think it should be "and changed items", but I am not a native speaker.

> +If `--branch` is given, a header line showing branch tracking information
> +is printed.  This line begins with "### branch: ".  Fields are separated
> +by a single space.
> +
> +    Field                    Meaning
> +    --------------------------------------------------------
> +    <sha> | (initial)        Current commit
> +    <branch> | (detached)    Current branch
> +    <upstream>               Upstream branch, if set
> +    +<ahead>                 Ahead count, if upstream present
> +    -<behind>                Behind count, if upstream present
> +    --------------------------------------------------------
> +
> +A series of lines are then displayed for the tracked entries.
> +Ordinary changed entries have the following format; the first
> +character is a 'c' to distinguish them from unmerged entries.

It would be nice (though not necessary) to have an example, either
here or at the end.

> +
> +    c <xy> <sub> <mH> <mI> <mW> <hH> <hI> R<nr> <path>[\t<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 ".".
> +    <m*>        The 6 character octal file modes for head, index,
> +                and worktree.

I think it might be more readable to be explicit: "for HEAD (<mH>),
index (<mI>), and worktree (<mW>)."

> +    <h*>        The head and index SHA1 values.
> +    R<nr>       The rename percentage score.

I assume this would be C<nr> copy detection heuristics percentage
score in case of copy detection, and B<br> break percentage score
in case of breaking change into addition and deletion of file.
Or am I confused?


> +    <path>      The current pathname. It is C-Quoted if it contains
> +                special control characters.

I assume that "\t" tab character between <path> and <pathSrc> is here
to be able to not C-Quote sane filenames with internal whitespace,
isn't it?

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

I assume that "C-Quoted if necessary" is the same as "C-Quoted if
it contains special control characters"; also: '"' quote character,
'\' backlash escape character and "\t" horizontal tab are not control
characters per se., but still need C-Quoting.  The rules are the same
as for the rest of Git, e.g. for `git diff`, isn't it?

> +    --------------------------------------------------------
> +
> +Unmerged entries have the following format; the first character is
> +a "u" to distinguish from ordinary changed entries.
> +
> +    u <xy> <sub> <m1> <m2> <m3> <h1> <h2> <h3> <path>
> +
> +    Field       Meaning
> +    --------------------------------------------------------
> +    <xy>        A 2 character field describing the conflict type
> +                as described in the short format.
> +    <sub>       A 4 character field describing the submodule state
> +                as described above.
> +    <m*>        The 6 character octal file modes for the stage 1,
> +                stage 2, stage 3, and worktree.

Errr... the pattern has only _3_ character octal modes, <m1> <m2> <m3>.
A question: what happens during octopus merge?

> +                For regular entries, these are the head, index, and
> +                worktree modes; the fourth is zero.

This is remnant of the previous version of "v2" format, isn't it?

> +    <h*>        The stage 1, stage 2, and stage 3 SHA1 values.
> +    <path>      The current pathname. It is C-Quoted if necessary.
> +    --------------------------------------------------------
> +
> +A series of lines are then displayed for untracked and ignored entries.
> +
> +    <x> <path>
> +
> +Where <x> is "?" for untracked entries and "!" for ignored entries.

I assume that here also <path> is C-Quoted if necessary.

> +
> +When the `-z` option is given, a NUL (zero) byte follows each pathname;
> +serving as both a separator and line termination. No pathname quoting
> +or backslash escaping is performed. All fields are output in the same
> +order.
> +
>  CONFIGURATION
>  -------------
>  
>