docs: rephrase and clarify the git status --short format

[thirdparty/git.git] / Documentation / git-status.txt

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 7731b45f078e92e01df48d47d9f9abf9d1d931c1..c0764e850a44adde9499c6e601dace9320116f38 100644 (file)
--- 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
 -------------------------------------------------