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

[Jeff Hostetler]

On 08/02/2016 11:19 AM, Jakub Narębski wrote:

W dniu 01.08.2016 o 17:39, Jeff Hostetler pisze:

On 07/30/2016 01:22 PM, Jakub Narębski wrote:

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

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



Yes, I was hoping to be able to simplify and/or speed up
__git_ps1() with this data.  "Namespacing" the branch data
here.  And then later add the state data (in a merge,
in a rebase, and etc.) in a series of "# state.*" headers.
And so on, until we get everything that __git_ps1() needs.
However, to really make that work, we might want to add
a --no-scan (or minimial scan) option, to just return the
header data, since __git_ps1() doesn't care about the list
of changes.


But __git_ps1() with GIT_PS1_SHOWDIRTYSTATE would want to know
if there are unstaged and staged changes, and with
GIT_PS1_SHOWUNTRACKEDFILES it would want to know if there
are untracked (unknown) files, isn't it?

And GIT_PS1_SHOWSTASHSTATE would want to know if there is
something stashed, but I guess it is outside the remit of
git-status...

Also, __git_ps1() uses colors from git-status, so if it
is switched to use --porcelain=v2, then there should be an
option to turn the color on, isn't it?



All of these are good questions.  But __git_ps1() is outside my
scope right now.  All I was saying above is that by making
the branch details available here and, later, extending V2
output by adding other such headers to the output, we could
try to remove much of the business logic in __git_ps1() and
hopefully reduce it to just formatting and coloring the prompt
using the computed result from status.

But I've only skimmed __git_ps1() (and it's a little dense),
so I'd have to study it more before I could answer all of your
questions.

Thanks,
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 v3 7/8] status: update git-status.txt for --porcelain=v2

[Jakub Narębski]

W dniu 01.08.2016 o 17:39, Jeff Hostetler pisze:
> On 07/30/2016 01:22 PM, Jakub Narębski wrote:
>> W dniu 26.07.2016 o 23:11, Jeff Hostetler pisze:
>>
>> 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)...
>>
> 
> Yes, I was hoping to be able to simplify and/or speed up
> __git_ps1() with this data.  "Namespacing" the branch data
> here.  And then later add the state data (in a merge,
> in a rebase, and etc.) in a series of "# state.*" headers.
> And so on, until we get everything that __git_ps1() needs.
> However, to really make that work, we might want to add
> a --no-scan (or minimial scan) option, to just return the
> header data, since __git_ps1() doesn't care about the list
> of changes.

But __git_ps1() with GIT_PS1_SHOWDIRTYSTATE would want to know
if there are unstaged and staged changes, and with
GIT_PS1_SHOWUNTRACKEDFILES it would want to know if there
are untracked (unknown) files, isn't it?

And GIT_PS1_SHOWSTASHSTATE would want to know if there is
something stashed, but I guess it is outside the remit of
git-status...
 
Also, __git_ps1() uses colors from git-status, so if it
is switched to use --porcelain=v2, then there should be an
option to turn the color on, isn't it?

-- 
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 v3 7/8] status: update git-status.txt for --porcelain=v2

[Jeff Hostetler]

On 07/30/2016 01:22 PM, Jakub Narębski wrote:

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

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



Yes, I was hoping to be able to simplify and/or speed up
__git_ps1() with this data.  "Namespacing" the branch data
here.  And then later add the state data (in a merge,
in a rebase, and etc.) in a series of "# state.*" headers.
And so on, until we get everything that __git_ps1() needs.
However, to really make that work, we might want to add
a --no-scan (or minimial scan) option, to just return the
header data, since __git_ps1() doesn't care about the list
of changes.



+
+A series of lines are then displayed for the tracked entries.
+Ordinary changed entries have the following format:
+
+1
+
+Renamed or copied entries have the following format:
+
+2 \t


Nice solution to avoid those all zeros / null-SHA1s


Thanks.



+Unmerged entries have the following format; the first character is
+a "u" to distinguish from ordinary changed entries.
+
+u  
+
+Field   Meaning
+
+A 2 character field describing the conflict type
+as described in the short format.
+   A 4 character field describing the submodule state
+as described above.
+The octal file mode for stage 1.
+The octal file mode for stage 2.
+The octal file mode for stage 3.
+The octal file mode in the worktree.
+The SHA1 value for stage 1.
+The SHA1 value for stage 2.
+The SHA1 value for stage 3.
+  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?


As far as I could tell, unmerged rename conflicts appear with a single
filename.

When I did a divergent rename (in both branches), merge creates
a stage-1 "DD" entry,
a stage-2 "AU" entry, and
a stage-3 with a "UA" entry.
Status reports it as 3 rows.

When I did a rename in one branch and an edits in both, merge
creates: either a "DU" or "UD" conflict (depending on the direction
of the merge).

Given that the index is ordered and accessed by path (and there is
no pathname field in a cache entry to link it to a different one),
I have to say that this is true.



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


I put a note in the code about it reporting the last entry at each
stage that are present in the index, but I'm not sure about how much
we want to say here.

If octopus finds conflicts, the worktree will probably be in a
funky state anyway.




+
+A series of lines are then displayed for untracked and ignored entries.
+
+ 
+
+Where  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?


With the unique prefix character it shouldn't matter.  I do print
all the '?' lines first then all the '!' lines, so the manpage
could be clarified if we wanted. I was just trying to save another
paragraph in the manpage.




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



I was probably inconsistent, I think it should be "c-quoted" (with the
hypen) providing we like this term.

Each of the git-diff*.txt and diff-format.txt files talk about
this quoting scheme, but none give it an explicit name.



+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 [...] \t\n

line (including line terminator) is replaced with

 2 [...] \0\0

that is, it replaces a separator (TAB, "\t") and line 

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

[Jakub Narębski]

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  | (initial)Current commit
> +# branch.head  | (detached)  Current branch
> +# branch.upstream   If set
> +# branch.ab + -   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
> +
> +Renamed or copied entries have the following format:
> +
> +2 \t

Nice solution to avoid those all zeros / null-SHA1s

> +
> +Field   Meaning
> +
> +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.
> +   A 4 character field describing the submodule state.
> +"N..." when the entry is not a submodule.
> +"S" when the entry is a submodule.
> + is "C" if the commit changed; otherwise ".".
> + is "M" if it has tracked changes; otherwise ".".
> + is "U" if there are untracked changes; otherwise ".".
> +The 6 character octal file mode in the HEAD.
> +The octal file mode in the index.
> +The octal file mode in the worktree.
> +The SHA1 value in the HEAD.
> +The SHA1 value in the index.
> + The rename or copied percentage score. For example "R100"
> +or "C75".
> +  The current pathname.
> +   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  
> +
> +Field   Meaning
> +
> +A 2 character field describing the conflict type
> +as described in the short format.
> +   A 4 character field describing the submodule state
> +as described above.
> +The octal file mode for stage 1.
> +The octal file mode for stage 2.
> +The octal file mode for stage 3.
> +The octal file mode in the worktree.
> +The SHA1 value for stage 1.
> +The SHA1 value for stage 2.
> +The SHA1 value for stage 3.
> +  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.
> +
> + 
> +
> +Where  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 

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

[Jeff Hostetler]

From: Jeff Hostetler 

Update status manpage to include information about
porcelain v2 format.

Signed-off-by: Jeff Hostetler 
Signed-off-by: Jeff Hostetler 
---
 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  | (initial)Current commit
+# branch.head  | (detached)  Current branch
+# branch.upstream   If set
+# branch.ab + -   If set and present
+
+
+A series of lines are then displayed for the tracked entries.
+Ordinary changed entries have the following format:
+
+1
+
+Renamed or copied entries have the following format:
+
+2 \t
+
+Field   Meaning
+
+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.
+   A 4 character field describing the submodule state.
+"N..." when the entry is not a submodule.
+"S" when the entry is a submodule.
+ is "C" if the commit changed; otherwise ".".
+ is "M" if it has tracked changes; otherwise ".".
+ is "U" if there are untracked changes; otherwise ".".
+The 6 character octal file mode in the HEAD.
+The octal file mode in the index.
+The octal file mode in the worktree.
+The SHA1 value in the HEAD.
+The SHA1 value in the index.
+ The rename or copied percentage score. For example "R100"
+or "C75".
+  The current pathname.
+   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  
+
+Field   Meaning
+
+A 2 character field describing the conflict type
+as described in the short format.
+   A 4 character field describing the submodule state
+as described above.
+The octal file mode for stage 1.
+The octal file mode for stage 2.
+The octal file mode for stage 3.
+The octal file mode in the worktree.
+The SHA1 value for stage 1.
+The SHA1 value for stage 2.
+The SHA1 value for stage 3.
+  The current pathname.
+
+
+A series of lines are then displayed for untracked and ignored entries.
+
+ 
+
+Where  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

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message