6 git-status - Show the working tree status
12 'git status' [<options>] [--] [<pathspec>...]
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
29 Give the output in the short-format.
33 Show the branch and tracking info even in short-format.
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
44 The version parameter is used to specify the format version.
45 This is optional and defaults to the original version 'v1' format.
48 Give the output in the long-format. This is the default.
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`).
59 --untracked-files[=<mode>]::
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).
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
115 - 'no' - Show no ignored files.
116 - 'matching' - Shows ignored files and directories matching an
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.
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>]::
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'
139 Display or do not display detailed ahead/behind counts for the
140 branch relative to its upstream branch. Defaults to true.
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
150 See also linkgit:git-diff[1] `--find-renames`.
153 See the 'pathspec' entry in linkgit:gitglossary[7].
157 The output from this command is designed to be used as a commit
159 The default, long format, is designed to be human readable,
160 verbose and descriptive. Its contents and format are subject to change
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.
171 In the short-format, the status of each path is shown as one of these
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
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
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
210 * 'T' = file type changed (regular file, symbolic link or submodule)
214 * 'C' = copied (if config option status.renames is set to "copies")
215 * 'U' = updated but unmerged
219 -------------------------------------------------
221 M [ MTD] updated in index
222 T [ MTD] type changed in index
223 A [ MTD] added to 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 -------------------------------------------------
244 -------------------------------------------------
247 Submodules have more state and instead report
249 M the submodule has a different HEAD than
250 recorded in the index
251 m the submodule has modified content
252 ? the submodule has untracked files
254 This is since modified content or untracked files in a submodule cannot be added
255 via `git add` in the superproject to prepare a commit.
257 'm' and '?' are applied recursively. For example if a nested submodule
258 in a submodule contains an untracked file, this is reported as '?' as well.
260 If -b is used the short-format status is preceded by a line
262 ## branchname tracking info
264 Porcelain Format Version 1
265 ~~~~~~~~~~~~~~~~~~~~~~~~~~
267 Version 1 porcelain format is similar to the short format, but is guaranteed
268 not to change in a backwards-incompatible way between Git versions or
269 based on user configuration. This makes it ideal for parsing by scripts.
270 The description of the short format above also describes the porcelain
271 format, with a few exceptions:
273 1. The user's color.status configuration is not respected; color will
276 2. The user's status.relativePaths configuration is not respected; paths
277 shown will always be relative to the repository root.
279 There is also an alternate -z format recommended for machine parsing. In
280 that format, the status field is the same, but some other things
281 change. First, the '\->' is omitted from rename entries and the field
282 order is reversed (e.g 'from \-> to' becomes 'to from'). Second, a NUL
283 (ASCII 0) follows each filename, replacing space as a field separator
284 and the terminating newline (but a space still separates the status
285 field from the first filename). Third, filenames containing special
286 characters are not specially formatted; no quoting or
287 backslash-escaping is performed.
289 Any submodule changes are reported as modified `M` instead of `m` or single `?`.
291 Porcelain Format Version 2
292 ~~~~~~~~~~~~~~~~~~~~~~~~~~
294 Version 2 format adds more detailed information about the state of
295 the worktree and changed items. Version 2 also defines an extensible
296 set of easy to parse optional headers.
298 Header lines start with "#" and are added in response to specific
299 command line arguments. Parsers should ignore headers they
305 If `--branch` is given, a series of header lines are printed with
306 information about the current branch.
310 ------------------------------------------------------------
311 # branch.oid <commit> | (initial) Current commit.
312 # branch.head <branch> | (detached) Current branch.
313 # branch.upstream <upstream_branch> If upstream is set.
314 # branch.ab +<ahead> -<behind> If upstream is set and
315 the commit is present.
316 ------------------------------------------------------------
322 If `--show-stash` is given, one line is printed showing the number of stash
327 Changed Tracked Entries
328 ^^^^^^^^^^^^^^^^^^^^^^^
330 Following the headers, a series of lines are printed for tracked
331 entries. One of three different line formats may be used to describe
332 an entry depending on the type of change. Tracked entries are printed
333 in an undefined order; parsers should allow for a mixture of the 3
334 line types in any order.
336 Ordinary changed entries have the following format:
338 1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>
340 Renamed or copied entries have the following format:
342 2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path><sep><origPath>
346 --------------------------------------------------------
347 <XY> A 2 character field containing the staged and
348 unstaged XY values described in the short format,
349 with unchanged indicated by a "." rather than
351 <sub> A 4 character field describing the submodule state.
352 "N..." when the entry is not a submodule.
353 "S<c><m><u>" when the entry is a submodule.
354 <c> is "C" if the commit changed; otherwise ".".
355 <m> is "M" if it has tracked changes; otherwise ".".
356 <u> is "U" if there are untracked changes; otherwise ".".
357 <mH> The octal file mode in HEAD.
358 <mI> The octal file mode in the index.
359 <mW> The octal file mode in the worktree.
360 <hH> The object name in HEAD.
361 <hI> The object name in the index.
362 <X><score> The rename or copy score (denoting the percentage
363 of similarity between the source and target of the
364 move or copy). For example "R100" or "C75".
365 <path> The pathname. In a renamed/copied entry, this
367 <sep> When the `-z` option is used, the 2 pathnames are separated
368 with a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09)
370 <origPath> The pathname in the commit at HEAD or in the index.
371 This is only present in a renamed/copied entry, and
372 tells where the renamed/copied contents came from.
373 --------------------------------------------------------
376 Unmerged entries have the following format; the first character is
377 a "u" to distinguish from ordinary changed entries.
379 u <XY> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>
383 --------------------------------------------------------
384 <XY> A 2 character field describing the conflict type
385 as described in the short format.
386 <sub> A 4 character field describing the submodule state
388 <m1> The octal file mode in stage 1.
389 <m2> The octal file mode in stage 2.
390 <m3> The octal file mode in stage 3.
391 <mW> The octal file mode in the worktree.
392 <h1> The object name in stage 1.
393 <h2> The object name in stage 2.
394 <h3> The object name in stage 3.
396 --------------------------------------------------------
402 Following the tracked entries (and if requested), a series of
403 lines will be printed for untracked and then ignored items
404 found in the worktree.
406 Untracked items have the following format:
410 Ignored items have the following format:
414 Pathname Format Notes and -z
415 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
417 When the `-z` option is given, pathnames are printed as is and
418 without any quoting and lines are terminated with a NUL (ASCII 0x00)
421 Without the `-z` option, pathnames with "unusual" characters are
422 quoted as explained for the configuration variable `core.quotePath`
423 (see linkgit:git-config[1]).
429 The command honors `color.status` (or `status.color` -- they
430 mean the same thing and the latter is kept for backward
431 compatibility) and `color.status.<slot>` configuration variables
432 to colorize its output.
434 If the config variable `status.relativePaths` is set to false, then all
435 paths shown are relative to the repository root, not to the current
438 If `status.submoduleSummary` is set to a non zero number or true (identical
439 to -1 or an unlimited number), the submodule summary will be enabled for
440 the long format and a summary of commits for modified submodules will be
441 shown (see --summary-limit option of linkgit:git-submodule[1]). Please note
442 that the summary output from the status command will be suppressed for all
443 submodules when `diff.ignoreSubmodules` is set to 'all' or only for those
444 submodules where `submodule.<name>.ignore=all`. To also view the summary for
445 ignored submodules you can either use the --ignore-submodules=dirty command
446 line option or the 'git submodule summary' command, which shows a similar
447 output but does not honor these settings.
452 By default, `git status` will automatically refresh the index, updating
453 the cached stat information from the working tree and writing out the
454 result. Writing out the updated index is an optimization that isn't
455 strictly necessary (`status` computes the values for itself, but writing
456 them out is just to save subsequent programs from repeating our
457 computation). When `status` is run in the background, the lock held
458 during the write may conflict with other simultaneous processes, causing
459 them to fail. Scripts running `status` in the background should consider
460 using `git --no-optional-locks status` (see linkgit:git[1] for details).
462 UNTRACKED FILES AND PERFORMANCE
463 -------------------------------
465 `git status` can be very slow in large worktrees if/when it
466 needs to search for untracked files and directories. There are
467 many configuration options available to speed this up by either
468 avoiding the work or making use of cached results from previous
469 Git commands. There is no single optimum set of settings right
470 for everyone. We'll list a summary of the relevant options to help
471 you, but before going into the list, you may want to run `git status`
472 again, because your configuration may already be caching `git status`
473 results, so it could be faster on subsequent runs.
475 * The `--untracked-files=no` flag or the
476 `status.showUntrackedfiles=false` config (see above for both):
477 indicate that `git status` should not report untracked
478 files. This is the fastest option. `git status` will not list
479 the untracked files, so you need to be careful to remember if
480 you create any new files and manually `git add` them.
482 * `advice.statusUoption=false` (see linkgit:git-config[1]):
483 setting this variable to `false` disables the warning message
484 given when enumerating untracked files takes more than 2
485 seconds. In a large project, it may take longer and the user
486 may have already accepted the trade off (e.g. using "-uno" may
487 not be an acceptable option for the user), in which case, there
488 is no point issuing the warning message, and in such a case,
489 disabling the warning may be the best.
491 * `core.untrackedCache=true` (see linkgit:git-update-index[1]):
492 enable the untracked cache feature and only search directories
493 that have been modified since the previous `git status` command.
494 Git remembers the set of untracked files within each directory
495 and assumes that if a directory has not been modified, then
496 the set of untracked files within has not changed. This is much
497 faster than enumerating the contents of every directory, but still
498 not without cost, because Git still has to search for the set of
499 modified directories. The untracked cache is stored in the
500 `.git/index` file. The reduced cost of searching for untracked
501 files is offset slightly by the increased size of the index and
502 the cost of keeping it up-to-date. That reduced search time is
503 usually worth the additional size.
505 * `core.untrackedCache=true` and `core.fsmonitor=true` or
506 `core.fsmonitor=<hook_command_pathname>` (see
507 linkgit:git-update-index[1]): enable both the untracked cache
508 and FSMonitor features and only search directories that have
509 been modified since the previous `git status` command. This
510 is faster than using just the untracked cache alone because
511 Git can also avoid searching for modified directories. Git
512 only has to enumerate the exact set of directories that have
513 changed recently. While the FSMonitor feature can be enabled
514 without the untracked cache, the benefits are greatly reduced
517 Note that after you turn on the untracked cache and/or FSMonitor
518 features it may take a few `git status` commands for the various
519 caches to warm up before you see improved command times. This is
528 Part of the linkgit:git[1] suite