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

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