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

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

W dniu 26.07.2016 o 23:11, Jeff Hostetler pisze:

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

"If set and present" means "If upstream set and present", isn't it?
Well, it is a shortcut, and I think easy to understand.

> +    --------------------------------------------------------

This is a nice change, available because of lack of backward
compatibility with v1.  The porcelain v2 format branch-related
information could be enhanced without risk of breaking parsers,
or having new information put at the end even if it does not fit
there (like in previous iteration).

One thing that can serve as goal for the series is using the
question: would it make __git_ps1() from git-prompt.sh be able
to render fully decorated prompt with all bells and whistles,
and with all combinations of options.  Thus beside upstream
in the future we might want SVN upstream, and/or pushed-to
remote branch (and remote push upstream repository), etc.

But that's for the future (and it is possible for the future)...

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

Nice solution to avoid those all zeros / null-SHA1s

> +
> +    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 question: do unmerged entries always have only one single filename?
Or unmerged entries are always only about CONFLICT(contents), and no
other?

Would a note (or a link to other documentation) about octopus merges
be out of place here?

> +
> +A series of lines are then displayed for untracked and ignored entries.
> +
> +    <x> <path>
> +
> +Where <x> is "?" for untracked entries and "!" for ignored entries.

A question: are they displayed in that order, i.e. first all untracked,
then all ignored, or it is something one cannot rely about?

> +
> +In all 3 line formats, pathnames will be "C Quoted" if they contain

"C Quoted" or "C-Quoted"?  How it is described in other places of
the Git documentation?

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

Does it mean that

    2 [...] <cq-path>\t<cq-pathSrc>\n

line (including line terminator) is replaced with

    2 [...] <path>\0<pathSrc>\0

that is, it replaces a separator (TAB, "\t") and line termination (LF, "\n");
here spelled in full?

BTW. do we have name for "C-Quoted" paths?

> +
>  CONFIGURATION
>  -------------