| Message ID | 20210110190448.779754-1-sandals@crustytoothpaste.net (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | 4eb56b56e7cb35ec1ff152f3b6e6c4533d48cbdd |
| Headers | show |
| Series | [v2] docs: rephrase and clarify the git status --short format | expand |
"brian m. carlson" <sandals@crustytoothpaste.net> 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 <sandals@crustytoothpaste.net> > --- > 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" <sandals@crustytoothpaste.net> writes: > > > 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. > > +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. > > +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.
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 7731b45f07..c0764e850a 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -184,11 +184,26 @@ characters, that field will be quoted in the manner of a C string literal: surrounded by ASCII double quote (34) characters, and with interior special characters backslash-escaped. -For paths with merge conflicts, `X` and `Y` show the modification -states of each side of the merge. For paths that do not have merge -conflicts, `X` shows the status of the index, and `Y` shows the status -of the work tree. For untracked paths, `XY` are `??`. Other status -codes can be interpreted as follows: +There are three different types of states that are shown using this format, and +each one uses the `XY` syntax differently: + +* When a merge is occurring and the merge was successful, or outside of a merge + situation, `X` shows the status of the index and `Y` shows the status of the + working tree. +* When a merge conflict has occurred and has not yet been resolved, `X` and `Y` + show the state introduced by each head of the merge, relative to the common + ancestor. These paths are said to be _unmerged_. +* When a path is untracked, `X` and `Y` are always the same, since they are + unknown to the index. `??` is used for untracked paths. Ignored files are + not listed unless `--ignored` is used; if it is, ignored files are indicated + by `!!`. + +Note that the term _merge_ here also includes rebases using the default +`--merge` strategy, cherry-picks, and anything else using the merge machinery. + +In the following table, these three classes are shown in separate sections, and +these characters are used for `X` and `Y` fields for the first two sections that +show tracked paths: * ' ' = unmodified * 'M' = modified @@ -198,9 +213,6 @@ codes can be interpreted as follows: * 'C' = copied * 'U' = updated but unmerged -Ignored files are not listed, unless `--ignored` option is in effect, -in which case `XY` are `!!`. - .... X Y Meaning -------------------------------------------------
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 <sandals@crustytoothpaste.net> --- 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. Documentation/git-status.txt | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-)