Re: [PATCH v1 5/6] Add porcelain V2 documentation to status manpage

[Junio C Hamano]

Jeff Hostetler  writes:

> +A series of lines are then displayed for the tracked entries.
> +
> + R 
> [\t]
> +
> +Field   Meaning
> +
> +The staged and unstaged values described earlier, with
> +unchanged indicated by a "." rather than a space.

Ahh, this is where these mysterious xy came from.  You just needed
two random consecutive letters, and they could have been ab, ij, or
jk.  I don't like any of them ;-)

Also I have trouble with the "staged and unstaged" here, especially
the latter, as the word implies the user did "git rm --cached" on
the path earlier, which is not the case.  You are saying what is in
the index and what is in the working tree.

Perhaps using iw instead of xy to make them in sync with the way
"git diff --mnemonic-prefix" denotes the contents in the index and
in the working tree?  Together with s/staged/in the index/ and
s/unstaged/in the working tree/, the result would become more
consistent with the rest of the system, I suspect.

> +The file modes for the entry.
> +For unmerged entries, these are the stage 1, 2, and 3,
> +and the worktree modes.
> +For regular entries, these are the head, index, and
> +worktree modes; the fourth is zero.
> +  The SHA1 values for the entry.
> +For unmerged entries, these are the stage 1,2, and 3 values.
> +For regular entries, these are the head and index values;
> +the third entry is zero.

To future-proof, we should use "object name" for what you call "SHA1
value" here, I would think.

> +R   The rename percentage score.

s/percentage score/score/.  Do you differentiate between renames and
copies?

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

Seeing "if necessary" makes me wonder if we want to define when it
is "necessary".
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v1 5/6] Add porcelain V2 documentation to status manpage

[Jakub Narębski]

On 20 July 2016 at 17:42, Jeff Hostetler  wrote:
> On 07/20/2016 11:29 AM, Jakub Narębski wrote:
>> W dniu 2016-07-20 o 00:10, Jeff Hostetler pisze:
>>
>>> +Porcelain Format Version 2
>>> +~~
>>> +
>>> +
>>> +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.
>>> +
>>> +FieldMeaning
>>> +
>>> + | (initial)Current commit
>>> + | (detached)Current branch
>>
>> I was wondering if all possible combinations are allowed.  It turns out
>> that for technical implementation reasons it is not possible to have
>> "(initial) (detached)".
>>
>> Just something I was wondering about, no need for any change...
>
> Right. I don't think that combination is possible.  Not sure how
> to document that succinctly.

I don't think it is something we need to document, at least not here.

-- 
Jakub Narębski
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v1 5/6] Add porcelain V2 documentation to status manpage

[Jeff Hostetler]

On 07/20/2016 11:29 AM, Jakub Narębski wrote:

W dniu 2016-07-20 o 00:10, Jeff Hostetler pisze:


+Porcelain Format Version 2
+~~
+
+
+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.
+
+FieldMeaning
+
+ | (initial)Current commit
+ | (detached)Current branch


I was wondering if all possible combinations are allowed.  It turns out
that for technical implementation reasons it is not possible to have
"(initial) (detached)".

Just something I was wondering about, no need for any change...



Right. I don't think that combination is possible.  Not sure how
to document that succinctly.

Jeff

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v1 5/6] Add porcelain V2 documentation to status manpage

[Jakub Narębski]

W dniu 2016-07-20 o 00:10, Jeff Hostetler pisze:

> +Porcelain Format Version 2
> +~~
> +
> +
> +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.
> +
> +FieldMeaning
> +
> + | (initial)Current commit
> + | (detached)Current branch

I was wondering if all possible combinations are allowed.  It turns out
that for technical implementation reasons it is not possible to have
"(initial) (detached)".

Just something I was wondering about, no need for any change...
-- 
Jakub Narębski
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v1 5/6] Add porcelain V2 documentation to status manpage

[Jeff Hostetler]

This commit updates the status manpage to include
information about porcelain format V2.

Signed-off-by: Jeff Hostetler 
---
 Documentation/git-status.txt | 62 +---
 1 file changed, 59 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index de97729..01c42c0 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,62 @@ 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
+~~
+
+
+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.
+
+FieldMeaning
+
+ | (initial)Current commit
+ | (detached)Current branch
+   Upstream branch, if set
++ Ahead count, if upstream present
+-Behind count, if upstream present
+
+
+A series of lines are then displayed for the tracked entries.
+
+ R 
[\t]
+
+Field   Meaning
+
+The staged and unstaged values described earlier, with
+unchanged indicated by a "." rather than a space.
+   The submodule state. "N" when the entry is not a submodule.
+"S[C][M][U]" when the entry is a submodule.
+"C" indicates the submodule commit has changed.
+"M" indicates the submodule has tracked changes.
+"U" indicates the submodule has untracked changes.
+The file modes for the entry.
+For unmerged entries, these are the stage 1, 2, and 3,
+and the worktree modes.
+For regular entries, these are the head, index, and
+worktree modes; the fourth is zero.
+  The SHA1 values for the entry.
+For unmerged entries, these are the stage 1,2, and 3 values.
+For regular entries, these are the head and index values;
+the third entry is zero.
+R   The rename percentage score.
+  The current pathname. It is C-Quoted if necessary.
+   The original path. This is only present for staged renames.
+It is C-Quoted if necessary.
+
+
+A series of lines are then displayed for untracked and ignored entries.
+
+ 
+
+Where  is "??" for untracked entries and "!!" for ignored entries.
+
+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

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html