Merge branch 'en/ort-perf-batch-9'

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

diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index d4e8f24f0c86a6998a6190d5c5bfa542c1ef0f4f..83f38e31981420e3fbbb52ab00407cca6c7fceab 100644 (file)
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -59,16 +59,17 @@ This is optional and defaults to the original version 'v1' format.
 --untracked-files[=<mode>]::
        Show untracked files.
 +
+--
 The mode parameter is used to specify the handling of untracked files.
 It is optional: it defaults to 'all', and if specified, it must be
 stuck to the option (e.g. `-uno`, but not `-u no`).
-+
+
 The possible options are:
-+
+
        - 'no'     - Show no untracked files.
        - 'normal' - Shows untracked files and directories.
        - 'all'    - Also shows individual files in untracked directories.
-+
+
 When `-u` option is not used, untracked files and directories are
 shown (i.e. the same as specifying `normal`), to help you avoid
 forgetting to add newly created files.  Because it takes extra work
@@ -78,9 +79,10 @@ Consider enabling untracked cache and split index if supported (see
 `git update-index --untracked-cache` and `git update-index
 --split-index`), Otherwise you can use `no` to have `git status`
 return more quickly without showing untracked files.
-+
+
 The default can be changed using the status.showUntrackedFiles
 configuration variable documented in linkgit:git-config[1].
+--
 
 --ignore-submodules[=<when>]::
        Ignore changes to submodules when looking for changes. <when> can be
@@ -100,11 +102,12 @@ configuration variable documented in linkgit:git-config[1].
 --ignored[=<mode>]::
        Show ignored files as well.
 +
+--
 The mode parameter is used to specify the handling of ignored files.
 It is optional: it defaults to 'traditional'.
-+
+
 The possible options are:
-+
+
        - 'traditional' - Shows ignored files and directories, unless
                          --untracked-files=all is specified, in which case
                          individual files in ignored directories are
@@ -112,12 +115,13 @@ The possible options are:
        - 'no'          - Show no ignored files.
        - 'matching'    - Shows ignored files and directories matching an
                          ignore pattern.
-+
+
 When 'matching' mode is specified, paths that explicitly match an
 ignored pattern are shown. If a directory matches an ignore pattern,
 then it is shown, but not paths contained in the ignored directory. If
 a directory does not match an ignore pattern, but all contents are
 ignored, then the directory is not shown, but all contents are shown.
+--
 
 -z::
        Terminate entries with NUL, instead of LF.  This implies
@@ -126,7 +130,7 @@ ignored, then the directory is not shown, but all contents are shown.
 --column[=<options>]::
 --no-column::
        Display untracked files in columns. See configuration variable
-       column.status for option syntax.`--column` and `--no-column`
+       `column.status` for option syntax. `--column` and `--no-column`
        without options are equivalent to 'always' and 'never'
        respectively.
 
@@ -180,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
@@ -194,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
 -------------------------------------------------