Re: [PATCH v2] docs: rephrase and clarify the git status --short format

"brian m. carlson" [off-list ref] writes:

The table describing the porcelain format in git-status(1) is helpful,
but it's not completely clear what the three sections mean, even to
some contributors.  As a result, users are unable to find how to detect
common cases like merge conflicts programmatically.

Let's improve this situation by rephrasing to be more explicit about
what each of the sections in the table means, to tell users in plain
language which cases are occurring, and to describe what "unmerged"
means.

Signed-off-by: brian m. carlson <redacted>
---
This uses text from Junio's email, so his sign-off will be required
here.  I assume that won't be a problem, but I can send a v3 if it is.

Actually I find the text so vastly improved from "here is my
attempt" version in the discussion that, other than the paragraph
structure, there is nothing left that I can call my contribution.
I'll sign the resulting commit off anyway, though ;-)

+There are three different types of states that are shown using this format, and
+each one uses the `XY` syntax differently:
...
+
+Note that the term _merge_ here also includes rebases using the default
+`--merge` strategy, cherry-picks, and anything else using the merge machinery.

Even if rebase uses the good-old "format-patch | am -3" pipeline, it
would result in an index with entries at higher stages.  So I am not
sure if this "Note that" helps the reader.

+In the following table, these three classes are shown in separate sections, and

This iteration has improved the "Three different classes of paths
are shown" in the "here is my attempt" version to "Three different
types of states ..."; shouldn't we be doing the same here with
s/classes/types of states/?

+these characters are used for `X` and `Y` fields for the first two sections that
+show tracked paths:

Thanks.

On 2021-01-11 at 20:22:10, Junio C Hamano wrote:

"brian m. carlson" [off-list ref] writes:

quoted

This uses text from Junio's email, so his sign-off will be required
here.  I assume that won't be a problem, but I can send a v3 if it is.

Actually I find the text so vastly improved from "here is my
attempt" version in the discussion that, other than the paragraph
structure, there is nothing left that I can call my contribution.
I'll sign the resulting commit off anyway, though ;-)

Well, I did use some of your text verbatim, though, and the sign-off is
necessary.  Not that it's easily distinguishable in our history since
you're the maintainer, but I also like to be meticulous about sign-offs
because I think it makes sure that people get due credit for their
contributions.

quoted

+There are three different types of states that are shown using this format, and
+each one uses the `XY` syntax differently:
...
+
+Note that the term _merge_ here also includes rebases using the default
+`--merge` strategy, cherry-picks, and anything else using the merge machinery.

Even if rebase uses the good-old "format-patch | am -3" pipeline, it
would result in an index with entries at higher stages.  So I am not
sure if this "Note that" helps the reader.

I'll rephrase.

quoted

+In the following table, these three classes are shown in separate sections, and

This iteration has improved the "Three different classes of paths
are shown" in the "here is my attempt" version to "Three different
types of states ..."; shouldn't we be doing the same here with
s/classes/types of states/?

Can do.
-- 
brian m. carlson (he/him or they/them)
Houston, Texas, US