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

From

JHJeff Hostetler <git@jeffhostetler.com>

Date

Jul 26, 2016, 21:11 UTC

Message-ID

<1469567483-58794-8-git-send-email-git@jeffhostetler.com>

In-Reply-To

<1469567483-58794-1-git-send-email-git@jeffhostetler.com>

From: Jeff Hostetler <jeffhost@microsoft.com>

Signed-off-by: Jeff Hostetler <jeffhost@microsoft.com>
Signed-off-by: Jeff Hostetler <git@jeffhostetler.com>
---
 Documentation/git-status.txt | 93 ++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 90 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 6b1454b..ed3590d 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -185,10 +185,10 @@ If -b is used the short-format status is preceded by a line
 
 ## branchname tracking info
 
-Porcelain Format
-~~~~~~~~~~~~~~~~
+Porcelain Format Version 1
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The porcelain format is similar to the short format, but is guaranteed
+Version 1 porcelain format is similar to the short format, but is guaranteed
 not to change in a backwards-incompatible way between Git versions or
 based on user configuration. This makes it ideal for parsing by scripts.
 The description of the short format above also describes the porcelain
@@ -210,6 +210,93 @@ field from the first filename).  Third, filenames containing special
 characters are not specially formatted; no quoting or
 backslash-escaping is performed.
 
+Porcelain Format Version 2
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Version 2 format adds more detailed information about the state of
+the worktree and changed items.
+
+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
+    # branch.upstream <upstream_branch>  If set
+    # branch.ab +<ahead> -<behind>       If set and present
+    --------------------------------------------------------
+
+A series of lines are then displayed for the tracked entries.
+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>\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 ".".
+    <mH>        The 6 character octal file mode in the HEAD.
+    <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.
+    <X><nr>     The rename or copied percentage score. For example "R100"
+                or "C75".
+    <path>      The current pathname.
+    <pathSrc>   The original path. This is only present when the entry
+                has been renamed or copied.
+    --------------------------------------------------------
+
+Unmerged entries have the following format; the first character is
+a "u" to distinguish from ordinary changed entries.
+
+    u <xy> <sub> <m1> <m2> <m3> <mW> <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.
+    <m1>        The octal file mode for stage 1.
+    <m2>        The octal file mode for stage 2.
+    <m3>        The octal file mode for stage 3.
+    <mW>        The octal file mode in the worktree.
+    <h1>        The SHA1 value for stage 1.
+    <h2>        The SHA1 value for stage 2.
+    <h3>        The SHA1 value for stage 3.
+    <path>      The current pathname.
+    --------------------------------------------------------
+
+A series of lines are then displayed for untracked and ignored entries.
+
+    <x> <path>
+
+Where <x> is "?" for untracked entries and "!" for ignored entries.
+
+In all 3 line formats, pathnames will be "C Quoted" if they contain
+any of the following characters: TAB, LF, double quotes, or backslashes.
+These characters will be replaced with \t, \n, \", and \\, respectively,
+and the pathname will be enclosed in double quotes.
+
+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
 -------------
 

-- 
2.8.0.rc4.17.gac42084.dirty