docs: rephrase and clarify the git status --short format
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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
brian m. carlson committed
Jan 10, 2021 at 19:04 UTC
4eb56b56e7cb35ec1ff152f3b6e6c4533d48cbdd
1 file changed
+20
-8
Documentation/git-status.txt
+20
-8
@@ -184,11 +184,26 @@ characters, that field will be quoted in the manner of a C string
184
literal: surrounded by ASCII double quote (34) characters, and with
185
interior special characters backslash-escaped.
186
187
-For paths with merge conflicts, `X` and `Y` show the modification
188
-states of each side of the merge. For paths that do not have merge
189
-conflicts, `X` shows the status of the index, and `Y` shows the status
190
-of the work tree. For untracked paths, `XY` are `??`. Other status
191
-codes can be interpreted as follows:
187
+There are three different types of states that are shown using this format, and
188
+each one uses the `XY` syntax differently:
189
+
190
+* When a merge is occurring and the merge was successful, or outside of a merge
191
+ situation, `X` shows the status of the index and `Y` shows the status of the
192
+ working tree.
193
+* When a merge conflict has occurred and has not yet been resolved, `X` and `Y`
194
+ show the state introduced by each head of the merge, relative to the common
195
+ ancestor. These paths are said to be _unmerged_.
196
+* When a path is untracked, `X` and `Y` are always the same, since they are
197
+ unknown to the index. `??` is used for untracked paths. Ignored files are
198
+ not listed unless `--ignored` is used; if it is, ignored files are indicated
199
+ by `!!`.
200
+
201
+Note that the term _merge_ here also includes rebases using the default
202
+`--merge` strategy, cherry-picks, and anything else using the merge machinery.
203
+
204
+In the following table, these three classes are shown in separate sections, and
205
+these characters are used for `X` and `Y` fields for the first two sections that
206
+show tracked paths:
207
208
* ' ' = unmodified
209
* 'M' = modified
@@ -198,9 +213,6 @@ codes can be interpreted as follows:
213
* 'C' = copied
214
* 'U' = updated but unmerged
215
201
-Ignored files are not listed, unless `--ignored` option is in effect,
202
-in which case `XY` are `!!`.
203
-
216
....
217
X Y Meaning
218
-------------------------------------------------