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