reftable/basics: improve `binsearch()` test
[alt-git.git] / Documentation / git-status.txt
blobb0f36fabfb391c10582a6f0feb63fa596e693ddc
1 git-status(1)
2 =============
4 NAME
5 ----
6 git-status - Show the working tree status
9 SYNOPSIS
10 --------
11 [verse]
12 'git status' [<options>] [--] [<pathspec>...]
14 DESCRIPTION
15 -----------
16 Displays paths that have differences between the index file and the
17 current HEAD commit, paths that have differences between the working
18 tree and the index file, and paths in the working tree that are not
19 tracked by Git (and are not ignored by linkgit:gitignore[5]). The first
20 are what you _would_ commit by running `git commit`; the second and
21 third are what you _could_ commit by running 'git add' before running
22 `git commit`.
24 OPTIONS
25 -------
27 -s::
28 --short::
29         Give the output in the short-format.
31 -b::
32 --branch::
33         Show the branch and tracking info even in short-format.
35 --show-stash::
36         Show the number of entries currently stashed away.
38 --porcelain[=<version>]::
39         Give the output in an easy-to-parse format for scripts.
40         This is similar to the short output, but will remain stable
41         across Git versions and regardless of user configuration. See
42         below for details.
44 The version parameter is used to specify the format version.
45 This is optional and defaults to the original version 'v1' format.
47 --long::
48         Give the output in the long-format. This is the default.
50 -v::
51 --verbose::
52         In addition to the names of files that have been changed, also
53         show the textual changes that are staged to be committed
54         (i.e., like the output of `git diff --cached`). If `-v` is specified
55         twice, then also show the changes in the working tree that
56         have not yet been staged (i.e., like the output of `git diff`).
58 -u[<mode>]::
59 --untracked-files[=<mode>]::
60         Show untracked files.
63 The mode parameter is used to specify the handling of untracked files.
64 It is optional: it defaults to 'all', and if specified, it must be
65 stuck to the option (e.g. `-uno`, but not `-u no`).
67 The possible options are:
69         - 'no'     - Show no untracked files.
70         - 'normal' - Shows untracked files and directories.
71         - 'all'    - Also shows individual files in untracked directories.
73 When `-u` option is not used, untracked files and directories are
74 shown (i.e. the same as specifying `normal`), to help you avoid
75 forgetting to add newly created files.  Because it takes extra work
76 to find untracked files in the filesystem, this mode may take some
77 time in a large working tree.
78 Consider enabling untracked cache and split index if supported (see
79 `git update-index --untracked-cache` and `git update-index
80 --split-index`), Otherwise you can use `no` to have `git status`
81 return more quickly without showing untracked files.
83 The default can be changed using the status.showUntrackedFiles
84 configuration variable documented in linkgit:git-config[1].
87 --ignore-submodules[=<when>]::
88         Ignore changes to submodules when looking for changes. <when> can be
89         either "none", "untracked", "dirty" or "all", which is the default.
90         Using "none" will consider the submodule modified when it either contains
91         untracked or modified files or its HEAD differs from the commit recorded
92         in the superproject and can be used to override any settings of the
93         'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When
94         "untracked" is used submodules are not considered dirty when they only
95         contain untracked content (but they are still scanned for modified
96         content). Using "dirty" ignores all changes to the work tree of submodules,
97         only changes to the commits stored in the superproject are shown (this was
98         the behavior before 1.7.0). Using "all" hides all changes to submodules
99         (and suppresses the output of submodule summaries when the config option
100         `status.submoduleSummary` is set).
102 --ignored[=<mode>]::
103         Show ignored files as well.
106 The mode parameter is used to specify the handling of ignored files.
107 It is optional: it defaults to 'traditional'.
109 The possible options are:
111         - 'traditional' - Shows ignored files and directories, unless
112                           --untracked-files=all is specified, in which case
113                           individual files in ignored directories are
114                           displayed.
115         - 'no'          - Show no ignored files.
116         - 'matching'    - Shows ignored files and directories matching an
117                           ignore pattern.
119 When 'matching' mode is specified, paths that explicitly match an
120 ignored pattern are shown. If a directory matches an ignore pattern,
121 then it is shown, but not paths contained in the ignored directory. If
122 a directory does not match an ignore pattern, but all contents are
123 ignored, then the directory is not shown, but all contents are shown.
126 -z::
127         Terminate entries with NUL, instead of LF.  This implies
128         the `--porcelain=v1` output format if no other format is given.
130 --column[=<options>]::
131 --no-column::
132         Display untracked files in columns. See configuration variable
133         `column.status` for option syntax. `--column` and `--no-column`
134         without options are equivalent to 'always' and 'never'
135         respectively.
137 --ahead-behind::
138 --no-ahead-behind::
139         Display or do not display detailed ahead/behind counts for the
140         branch relative to its upstream branch.  Defaults to true.
142 --renames::
143 --no-renames::
144         Turn on/off rename detection regardless of user configuration.
145         See also linkgit:git-diff[1] `--no-renames`.
147 --find-renames[=<n>]::
148         Turn on rename detection, optionally setting the similarity
149         threshold.
150         See also linkgit:git-diff[1] `--find-renames`.
152 <pathspec>...::
153         See the 'pathspec' entry in linkgit:gitglossary[7].
155 OUTPUT
156 ------
157 The output from this command is designed to be used as a commit
158 template comment.
159 The default, long format, is designed to be human readable,
160 verbose and descriptive.  Its contents and format are subject to change
161 at any time.
163 The paths mentioned in the output, unlike many other Git commands, are
164 made relative to the current directory if you are working in a
165 subdirectory (this is on purpose, to help cutting and pasting). See
166 the status.relativePaths config option below.
168 Short Format
169 ~~~~~~~~~~~~
171 In the short-format, the status of each path is shown as one of these
172 forms
174         XY PATH
175         XY ORIG_PATH -> PATH
177 where `ORIG_PATH` is where the renamed/copied contents came
178 from. `ORIG_PATH` is only shown when the entry is renamed or
179 copied. The `XY` is a two-letter status code.
181 The fields (including the `->`) are separated from each other by a
182 single space. If a filename contains whitespace or other nonprintable
183 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.
187 There are three different types of states that are shown using this format, and
188 each one uses the `XY` syntax differently:
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 `!!`.
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.
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:
208 * ' ' = unmodified
209 * 'M' = modified
210 * 'T' = file type changed (regular file, symbolic link or submodule)
211 * 'A' = added
212 * 'D' = deleted
213 * 'R' = renamed
214 * 'C' = copied (if config option status.renames is set to "copies")
215 * 'U' = updated but unmerged
217 ....
218 X          Y     Meaning
219 -------------------------------------------------
220          [AMD]   not updated
221 M        [ MTD]  updated in index
222 T        [ MTD]  type changed in index
223 A        [ MTD]  added to index
224 D                deleted from index
225 R        [ MTD]  renamed in index
226 C        [ MTD]  copied in index
227 [MTARC]          index and work tree matches
228 [ MTARC]    M    work tree changed since index
229 [ MTARC]    T    type changed in work tree since index
230 [ MTARC]    D    deleted in work tree
231             R    renamed in work tree
232             C    copied in work tree
233 -------------------------------------------------
234 D           D    unmerged, both deleted
235 A           U    unmerged, added by us
236 U           D    unmerged, deleted by them
237 U           A    unmerged, added by them
238 D           U    unmerged, deleted by us
239 A           A    unmerged, both added
240 U           U    unmerged, both modified
241 -------------------------------------------------
242 ?           ?    untracked
243 !           !    ignored
244 -------------------------------------------------
245 ....
247 Submodules have more state and instead report
249 * 'M' = the submodule has a different HEAD than recorded in the index
250 * 'm' = the submodule has modified content
251 * '?' = the submodule has untracked files
253 This is since modified content or untracked files in a submodule cannot be added
254 via `git add` in the superproject to prepare a commit.
256 'm' and '?' are applied recursively. For example if a nested submodule
257 in a submodule contains an untracked file, this is reported as '?' as well.
259 If -b is used the short-format status is preceded by a line
261     ## branchname tracking info
263 Porcelain Format Version 1
264 ~~~~~~~~~~~~~~~~~~~~~~~~~~
266 Version 1 porcelain format is similar to the short format, but is guaranteed
267 not to change in a backwards-incompatible way between Git versions or
268 based on user configuration. This makes it ideal for parsing by scripts.
269 The description of the short format above also describes the porcelain
270 format, with a few exceptions:
272 1. The user's color.status configuration is not respected; color will
273    always be off.
275 2. The user's status.relativePaths configuration is not respected; paths
276    shown will always be relative to the repository root.
278 There is also an alternate -z format recommended for machine parsing. In
279 that format, the status field is the same, but some other things
280 change.  First, the '\->' is omitted from rename entries and the field
281 order is reversed (e.g 'from \-> to' becomes 'to from'). Second, a NUL
282 (ASCII 0) follows each filename, replacing space as a field separator
283 and the terminating newline (but a space still separates the status
284 field from the first filename).  Third, filenames containing special
285 characters are not specially formatted; no quoting or
286 backslash-escaping is performed.
288 Any submodule changes are reported as modified `M` instead of `m` or single `?`.
290 Porcelain Format Version 2
291 ~~~~~~~~~~~~~~~~~~~~~~~~~~
293 Version 2 format adds more detailed information about the state of
294 the worktree and changed items.  Version 2 also defines an extensible
295 set of easy to parse optional headers.
297 Header lines start with "#" and are added in response to specific
298 command line arguments.  Parsers should ignore headers they
299 don't recognize.
301 Branch Headers
302 ^^^^^^^^^^^^^^
304 If `--branch` is given, a series of header lines are printed with
305 information about the current branch.
307 ....
308 Line                                     Notes
309 ------------------------------------------------------------
310 # branch.oid <commit> | (initial)        Current commit.
311 # branch.head <branch> | (detached)      Current branch.
312 # branch.upstream <upstream-branch>      If upstream is set.
313 # branch.ab +<ahead> -<behind>           If upstream is set and
314                                          the commit is present.
315 ------------------------------------------------------------
316 ....
318 Stash Information
319 ^^^^^^^^^^^^^^^^^
321 If `--show-stash` is given, one line is printed showing the number of stash
322 entries if non-zero:
324     # stash <N>
326 Changed Tracked Entries
327 ^^^^^^^^^^^^^^^^^^^^^^^
329 Following the headers, a series of lines are printed for tracked
330 entries.  One of three different line formats may be used to describe
331 an entry depending on the type of change.  Tracked entries are printed
332 in an undefined order; parsers should allow for a mixture of the 3
333 line types in any order.
335 Ordinary changed entries have the following format:
337     1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>
339 Renamed or copied entries have the following format:
341     2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path><sep><origPath>
343 ....
344 Field       Meaning
345 --------------------------------------------------------
346 <XY>        A 2 character field containing the staged and
347             unstaged XY values described in the short format,
348             with unchanged indicated by a "." rather than
349             a space.
350 <sub>       A 4 character field describing the submodule state.
351             "N..." when the entry is not a submodule.
352             "S<c><m><u>" when the entry is a submodule.
353             <c> is "C" if the commit changed; otherwise ".".
354             <m> is "M" if it has tracked changes; otherwise ".".
355             <u> is "U" if there are untracked changes; otherwise ".".
356 <mH>        The octal file mode in HEAD.
357 <mI>        The octal file mode in the index.
358 <mW>        The octal file mode in the worktree.
359 <hH>        The object name in HEAD.
360 <hI>        The object name in the index.
361 <X><score>  The rename or copy score (denoting the percentage
362             of similarity between the source and target of the
363             move or copy). For example "R100" or "C75".
364 <path>      The pathname.  In a renamed/copied entry, this
365             is the target path.
366 <sep>       When the `-z` option is used, the 2 pathnames are separated
367             with a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09)
368             byte separates them.
369 <origPath>  The pathname in the commit at HEAD or in the index.
370             This is only present in a renamed/copied entry, and
371             tells where the renamed/copied contents came from.
372 --------------------------------------------------------
373 ....
375 Unmerged entries have the following format; the first character is
376 a "u" to distinguish from ordinary changed entries.
378     u <XY> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>
380 ....
381 Field       Meaning
382 --------------------------------------------------------
383 <XY>        A 2 character field describing the conflict type
384             as described in the short format.
385 <sub>       A 4 character field describing the submodule state
386             as described above.
387 <m1>        The octal file mode in stage 1.
388 <m2>        The octal file mode in stage 2.
389 <m3>        The octal file mode in stage 3.
390 <mW>        The octal file mode in the worktree.
391 <h1>        The object name in stage 1.
392 <h2>        The object name in stage 2.
393 <h3>        The object name in stage 3.
394 <path>      The pathname.
395 --------------------------------------------------------
396 ....
398 Other Items
399 ^^^^^^^^^^^
401 Following the tracked entries (and if requested), a series of
402 lines will be printed for untracked and then ignored items
403 found in the worktree.
405 Untracked items have the following format:
407     ? <path>
409 Ignored items have the following format:
411     ! <path>
413 Pathname Format Notes and -z
414 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
416 When the `-z` option is given, pathnames are printed as is and
417 without any quoting and lines are terminated with a NUL (ASCII 0x00)
418 byte.
420 Without the `-z` option, pathnames with "unusual" characters are
421 quoted as explained for the configuration variable `core.quotePath`
422 (see linkgit:git-config[1]).
425 CONFIGURATION
426 -------------
428 The command honors `color.status` (or `status.color` -- they
429 mean the same thing and the latter is kept for backward
430 compatibility) and `color.status.<slot>` configuration variables
431 to colorize its output.
433 If the config variable `status.relativePaths` is set to false, then all
434 paths shown are relative to the repository root, not to the current
435 directory.
437 If `status.submoduleSummary` is set to a non zero number or true (identical
438 to -1 or an unlimited number), the submodule summary will be enabled for
439 the long format and a summary of commits for modified submodules will be
440 shown (see --summary-limit option of linkgit:git-submodule[1]). Please note
441 that the summary output from the status command will be suppressed for all
442 submodules when `diff.ignoreSubmodules` is set to 'all' or only for those
443 submodules where `submodule.<name>.ignore=all`. To also view the summary for
444 ignored submodules you can either use the --ignore-submodules=dirty command
445 line option or the 'git submodule summary' command, which shows a similar
446 output but does not honor these settings.
448 BACKGROUND REFRESH
449 ------------------
451 By default, `git status` will automatically refresh the index, updating
452 the cached stat information from the working tree and writing out the
453 result. Writing out the updated index is an optimization that isn't
454 strictly necessary (`status` computes the values for itself, but writing
455 them out is just to save subsequent programs from repeating our
456 computation). When `status` is run in the background, the lock held
457 during the write may conflict with other simultaneous processes, causing
458 them to fail. Scripts running `status` in the background should consider
459 using `git --no-optional-locks status` (see linkgit:git[1] for details).
461 UNTRACKED FILES AND PERFORMANCE
462 -------------------------------
464 `git status` can be very slow in large worktrees if/when it
465 needs to search for untracked files and directories. There are
466 many configuration options available to speed this up by either
467 avoiding the work or making use of cached results from previous
468 Git commands. There is no single optimum set of settings right
469 for everyone. We'll list a summary of the relevant options to help
470 you, but before going into the list, you may want to run `git status`
471 again, because your configuration may already be caching `git status`
472 results, so it could be faster on subsequent runs.
474 * The `--untracked-files=no` flag or the
475         `status.showUntrackedFiles=no` config (see above for both):
476         indicate that `git status` should not report untracked
477         files. This is the fastest option. `git status` will not list
478         the untracked files, so you need to be careful to remember if
479         you create any new files and manually `git add` them.
481 * `advice.statusUoption=false` (see linkgit:git-config[1]):
482         setting this variable to `false` disables the warning message
483         given when enumerating untracked files takes more than 2
484         seconds.  In a large project, it may take longer and the user
485         may have already accepted the trade off (e.g. using "-uno" may
486         not be an acceptable option for the user), in which case, there
487         is no point issuing the warning message, and in such a case,
488         disabling the warning may be the best.
490 * `core.untrackedCache=true` (see linkgit:git-update-index[1]):
491         enable the untracked cache feature and only search directories
492         that have been modified since the previous `git status` command.
493         Git remembers the set of untracked files within each directory
494         and assumes that if a directory has not been modified, then
495         the set of untracked files within has not changed.  This is much
496         faster than enumerating the contents of every directory, but still
497         not without cost, because Git still has to search for the set of
498         modified directories. The untracked cache is stored in the
499         `.git/index` file. The reduced cost of searching for untracked
500         files is offset slightly by the increased size of the index and
501         the cost of keeping it up-to-date. That reduced search time is
502         usually worth the additional size.
504 * `core.untrackedCache=true` and `core.fsmonitor=true` or
505         `core.fsmonitor=<hook-command-pathname>` (see
506         linkgit:git-update-index[1]): enable both the untracked cache
507         and FSMonitor features and only search directories that have
508         been modified since the previous `git status` command.  This
509         is faster than using just the untracked cache alone because
510         Git can also avoid searching for modified directories.  Git
511         only has to enumerate the exact set of directories that have
512         changed recently. While the FSMonitor feature can be enabled
513         without the untracked cache, the benefits are greatly reduced
514         in that case.
516 Note that after you turn on the untracked cache and/or FSMonitor
517 features it may take a few `git status` commands for the various
518 caches to warm up before you see improved command times.  This is
519 normal.
521 SEE ALSO
522 --------
523 linkgit:gitignore[5]
527 Part of the linkgit:git[1] suite