diff options
Diffstat (limited to 'Documentation/git-status.txt')
| -rw-r--r-- | Documentation/git-status.txt | 305 |
1 files changed, 202 insertions, 103 deletions
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index c4467ffb98..a051b1e8f3 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -9,7 +9,7 @@ git-status - Show the working tree status SYNOPSIS -------- [verse] -'git status' [<options>...] [--] [<pathspec>...] +'git status' [<options>] [--] [<pathspec>...] DESCRIPTION ----------- @@ -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,24 +102,26 @@ 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 specifed, in which case + --untracked-files=all is specified, in which case individual files in ignored directories are displayed. - '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,48 +184,65 @@ 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 +* 'T' = file type changed (regular file, symbolic link or submodule) * 'A' = added * 'D' = deleted * 'R' = renamed -* 'C' = copied +* 'C' = copied (if config option status.renames is set to "copies") * 'U' = updated but unmerged -Ignored files are not listed, unless `--ignored` option is in effect, -in which case `XY` are `!!`. - - X Y Meaning - ------------------------------------------------- - [AMD] not updated - M [ MD] updated in index - A [ MD] added to index - D deleted from index - R [ MD] renamed in index - C [ MD] copied in index - [MARC] index and work tree matches - [ MARC] M work tree changed since index - [ MARC] D deleted in work tree - [ D] R renamed in work tree - [ D] C copied in work tree - ------------------------------------------------- - D D unmerged, both deleted - A U unmerged, added by us - U D unmerged, deleted by them - U A unmerged, added by them - D U unmerged, deleted by us - A A unmerged, both added - U U unmerged, both modified - ------------------------------------------------- - ? ? untracked - ! ! ignored - ------------------------------------------------- +.... +X Y Meaning +------------------------------------------------- + [AMD] not updated +M [ MTD] updated in index +T [ MTD] type changed in index +A [ MTD] added to index +D deleted from index +R [ MTD] renamed in index +C [ MTD] copied in index +[MTARC] index and work tree matches +[ MTARC] M work tree changed since index +[ MTARC] T type changed in work tree since index +[ MTARC] D deleted in work tree + R renamed in work tree + C copied in work tree +------------------------------------------------- +D D unmerged, both deleted +A U unmerged, added by us +U D unmerged, deleted by them +U A unmerged, added by them +D U unmerged, deleted by us +A A unmerged, both added +U U unmerged, both modified +------------------------------------------------- +? ? untracked +! ! ignored +------------------------------------------------- +.... Submodules have more state and instead report M the submodule has a different HEAD than @@ -276,21 +297,33 @@ Header lines start with "#" and are added in response to specific command line arguments. Parsers should ignore headers they don't recognize. -### Branch Headers +Branch Headers +^^^^^^^^^^^^^^ If `--branch` is given, a series of header lines are printed with information about the current branch. - Line Notes - ------------------------------------------------------------ - # branch.oid <commit> | (initial) Current commit. - # branch.head <branch> | (detached) Current branch. - # branch.upstream <upstream_branch> If upstream is set. - # branch.ab +<ahead> -<behind> If upstream is set and - the commit is present. - ------------------------------------------------------------ +.... +Line Notes +------------------------------------------------------------ +# branch.oid <commit> | (initial) Current commit. +# branch.head <branch> | (detached) Current branch. +# branch.upstream <upstream_branch> If upstream is set. +# branch.ab +<ahead> -<behind> If upstream is set and + the commit is present. +------------------------------------------------------------ +.... + +Stash Information +^^^^^^^^^^^^^^^^^ + +If `--show-stash` is given, one line is printed showing the number of stash +entries if non-zero: -### Changed Tracked Entries + # stash <N> + +Changed Tracked Entries +^^^^^^^^^^^^^^^^^^^^^^^ Following the headers, a series of lines are printed for tracked entries. One of three different line formats may be used to describe @@ -306,58 +339,63 @@ Renamed or copied entries have the following format: 2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path><sep><origPath> - Field Meaning - -------------------------------------------------------- - <XY> A 2 character field containing the staged and - unstaged XY values described in the short format, - with unchanged indicated by a "." rather than - a space. - <sub> A 4 character field describing the submodule state. - "N..." when the entry is not a submodule. - "S<c><m><u>" when the entry is a submodule. - <c> is "C" if the commit changed; otherwise ".". - <m> is "M" if it has tracked changes; otherwise ".". - <u> is "U" if there are untracked changes; otherwise ".". - <mH> The octal file mode in HEAD. - <mI> The octal file mode in the index. - <mW> The octal file mode in the worktree. - <hH> The object name in HEAD. - <hI> The object name in the index. - <X><score> The rename or copy score (denoting the percentage - of similarity between the source and target of the - move or copy). For example "R100" or "C75". - <path> The pathname. In a renamed/copied entry, this - is the target path. - <sep> When the `-z` option is used, the 2 pathnames are separated - with a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09) - byte separates them. - <origPath> The pathname in the commit at HEAD or in the index. - This is only present in a renamed/copied entry, and - tells where the renamed/copied contents came from. - -------------------------------------------------------- +.... +Field Meaning +-------------------------------------------------------- +<XY> A 2 character field containing the staged and + unstaged XY values described in the short format, + with unchanged indicated by a "." rather than + a space. +<sub> A 4 character field describing the submodule state. + "N..." when the entry is not a submodule. + "S<c><m><u>" when the entry is a submodule. + <c> is "C" if the commit changed; otherwise ".". + <m> is "M" if it has tracked changes; otherwise ".". + <u> is "U" if there are untracked changes; otherwise ".". +<mH> The octal file mode in HEAD. +<mI> The octal file mode in the index. +<mW> The octal file mode in the worktree. +<hH> The object name in HEAD. +<hI> The object name in the index. +<X><score> The rename or copy score (denoting the percentage + of similarity between the source and target of the + move or copy). For example "R100" or "C75". +<path> The pathname. In a renamed/copied entry, this + is the target path. +<sep> When the `-z` option is used, the 2 pathnames are separated + with a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09) + byte separates them. +<origPath> The pathname in the commit at HEAD or in the index. + This is only present in a renamed/copied entry, and + tells where the renamed/copied contents came from. +-------------------------------------------------------- +.... Unmerged entries have the following format; the first character is a "u" to distinguish from ordinary changed entries. - u <xy> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path> - - Field Meaning - -------------------------------------------------------- - <XY> A 2 character field describing the conflict type - as described in the short format. - <sub> A 4 character field describing the submodule state - as described above. - <m1> The octal file mode in stage 1. - <m2> The octal file mode in stage 2. - <m3> The octal file mode in stage 3. - <mW> The octal file mode in the worktree. - <h1> The object name in stage 1. - <h2> The object name in stage 2. - <h3> The object name in stage 3. - <path> The pathname. - -------------------------------------------------------- - -### Other Items + u <XY> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path> + +.... +Field Meaning +-------------------------------------------------------- +<XY> A 2 character field describing the conflict type + as described in the short format. +<sub> A 4 character field describing the submodule state + as described above. +<m1> The octal file mode in stage 1. +<m2> The octal file mode in stage 2. +<m3> The octal file mode in stage 3. +<mW> The octal file mode in the worktree. +<h1> The object name in stage 1. +<h2> The object name in stage 2. +<h3> The object name in stage 3. +<path> The pathname. +-------------------------------------------------------- +.... + +Other Items +^^^^^^^^^^^ Following the tracked entries (and if requested), a series of lines will be printed for untracked and then ignored items @@ -371,7 +409,8 @@ Ignored items have the following format: ! <path> -### Pathname Format Notes and -z +Pathname Format Notes and -z +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When the `-z` option is given, pathnames are printed as is and without any quoting and lines are terminated with a NUL (ASCII 0x00) @@ -418,6 +457,66 @@ during the write may conflict with other simultaneous processes, causing them to fail. Scripts running `status` in the background should consider using `git --no-optional-locks status` (see linkgit:git[1] for details). +UNTRACKED FILES AND PERFORMANCE +------------------------------- + +`git status` can be very slow in large worktrees if/when it +needs to search for untracked files and directories. There are +many configuration options available to speed this up by either +avoiding the work or making use of cached results from previous +Git commands. There is no single optimum set of settings right +for everyone. We'll list a summary of the relevant options to help +you, but before going into the list, you may want to run `git status` +again, because your configuration may already be caching `git status` +results, so it could be faster on subsequent runs. + +* The `--untracked-files=no` flag or the + `status.showUntrackedfiles=false` config (see above for both): + indicate that `git status` should not report untracked + files. This is the fastest option. `git status` will not list + the untracked files, so you need to be careful to remember if + you create any new files and manually `git add` them. + +* `advice.statusUoption=false` (see linkgit:git-config[1]): + setting this variable to `false` disables the warning message + given when enumerating untracked files takes more than 2 + seconds. In a large project, it may take longer and the user + may have already accepted the trade off (e.g. using "-uno" may + not be an acceptable option for the user), in which case, there + is no point issuing the warning message, and in such a case, + disabling the warning may be the best. + +* `core.untrackedCache=true` (see linkgit:git-update-index[1]): + enable the untracked cache feature and only search directories + that have been modified since the previous `git status` command. + Git remembers the set of untracked files within each directory + and assumes that if a directory has not been modified, then + the set of untracked files within has not changed. This is much + faster than enumerating the contents of every directory, but still + not without cost, because Git still has to search for the set of + modified directories. The untracked cache is stored in the + `.git/index` file. The reduced cost of searching for untracked + files is offset slightly by the increased size of the index and + the cost of keeping it up-to-date. That reduced search time is + usually worth the additional size. + +* `core.untrackedCache=true` and `core.fsmonitor=true` or + `core.fsmonitor=<hook_command_pathname>` (see + linkgit:git-update-index[1]): enable both the untracked cache + and FSMonitor features and only search directories that have + been modified since the previous `git status` command. This + is faster than using just the untracked cache alone because + Git can also avoid searching for modified directories. Git + only has to enumerate the exact set of directories that have + changed recently. While the FSMonitor feature can be enabled + without the untracked cache, the benefits are greatly reduced + in that case. + +Note that after you turn on the untracked cache and/or FSMonitor +features it may take a few `git status` commands for the various +caches to warm up before you see improved command times. This is +normal. + SEE ALSO -------- linkgit:gitignore[5] |