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