1GIT-STATUS(1)                     Git Manual                     GIT-STATUS(1)
2
3
4

NAME

6       git-status - Show the working tree status
7

SYNOPSIS

9       git status [<options>] [--] [<pathspec>...]
10

DESCRIPTION

12       Displays paths that have differences between the index file and the
13       current HEAD commit, paths that have differences between the working
14       tree and the index file, and paths in the working tree that are not
15       tracked by Git (and are not ignored by gitignore(5)). The first are
16       what you would commit by running git commit; the second and third are
17       what you could commit by running git add before running git commit.
18

OPTIONS

20       -s, --short
21           Give the output in the short-format.
22
23       -b, --branch
24           Show the branch and tracking info even in short-format.
25
26       --show-stash
27           Show the number of entries currently stashed away.
28
29       --porcelain[=<version>]
30           Give the output in an easy-to-parse format for scripts. This is
31           similar to the short output, but will remain stable across Git
32           versions and regardless of user configuration. See below for
33           details.
34
35           The version parameter is used to specify the format version. This
36           is optional and defaults to the original version v1 format.
37
38       --long
39           Give the output in the long-format. This is the default.
40
41       -v, --verbose
42           In addition to the names of files that have been changed, also show
43           the textual changes that are staged to be committed (i.e., like the
44           output of git diff --cached). If -v is specified twice, then also
45           show the changes in the working tree that have not yet been staged
46           (i.e., like the output of git diff).
47
48       -u[<mode>], --untracked-files[=<mode>]
49           Show untracked files.
50
51           The mode parameter is used to specify the handling of untracked
52           files. It is optional: it defaults to all, and if specified, it
53           must be stuck to the option (e.g.  -uno, but not -u no).
54
55           The possible options are:
56
57no - Show no untracked files.
58
59normal - Shows untracked files and directories.
60
61all - Also shows individual files in untracked directories.
62
63           When -u option is not used, untracked files and directories are
64           shown (i.e. the same as specifying normal), to help you avoid
65           forgetting to add newly created files. Because it takes extra work
66           to find untracked files in the filesystem, this mode may take some
67           time in a large working tree. Consider enabling untracked cache and
68           split index if supported (see git update-index --untracked-cache
69           and git update-index --split-index), Otherwise you can use no to
70           have git status return more quickly without showing untracked
71           files.
72
73           The default can be changed using the status.showUntrackedFiles
74           configuration variable documented in git-config(1).
75
76       --ignore-submodules[=<when>]
77           Ignore changes to submodules when looking for changes. <when> can
78           be either "none", "untracked", "dirty" or "all", which is the
79           default. Using "none" will consider the submodule modified when it
80           either contains untracked or modified files or its HEAD differs
81           from the commit recorded in the superproject and can be used to
82           override any settings of the ignore option in git-config(1) or
83           gitmodules(5). When "untracked" is used submodules are not
84           considered dirty when they only contain untracked content (but they
85           are still scanned for modified content). Using "dirty" ignores all
86           changes to the work tree of submodules, only changes to the commits
87           stored in the superproject are shown (this was the behavior before
88           1.7.0). Using "all" hides all changes to submodules (and suppresses
89           the output of submodule summaries when the config option
90           status.submoduleSummary is set).
91
92       --ignored[=<mode>]
93           Show ignored files as well.
94
95           The mode parameter is used to specify the handling of ignored
96           files. It is optional: it defaults to traditional.
97
98           The possible options are:
99
100traditional - Shows ignored files and directories, unless
101               --untracked-files=all is specified, in which case individual
102               files in ignored directories are displayed.
103
104no - Show no ignored files.
105
106matching - Shows ignored files and directories matching an
107               ignore pattern.
108
109           When matching mode is specified, paths that explicitly match an
110           ignored pattern are shown. If a directory matches an ignore
111           pattern, then it is shown, but not paths contained in the ignored
112           directory. If a directory does not match an ignore pattern, but all
113           contents are ignored, then the directory is not shown, but all
114           contents are shown.
115
116       -z
117           Terminate entries with NUL, instead of LF. This implies the
118           --porcelain=v1 output format if no other format is given.
119
120       --column[=<options>], --no-column
121           Display untracked files in columns. See configuration variable
122           column.status for option syntax.  --column and --no-column without
123           options are equivalent to always and never respectively.
124
125       --ahead-behind, --no-ahead-behind
126           Display or do not display detailed ahead/behind counts for the
127           branch relative to its upstream branch. Defaults to true.
128
129       --renames, --no-renames
130           Turn on/off rename detection regardless of user configuration. See
131           also git-diff(1) --no-renames.
132
133       --find-renames[=<n>]
134           Turn on rename detection, optionally setting the similarity
135           threshold. See also git-diff(1) --find-renames.
136
137       <pathspec>...
138           See the pathspec entry in gitglossary(7).
139

OUTPUT

141       The output from this command is designed to be used as a commit
142       template comment. The default, long format, is designed to be human
143       readable, verbose and descriptive. Its contents and format are subject
144       to change at any time.
145
146       The paths mentioned in the output, unlike many other Git commands, are
147       made relative to the current directory if you are working in a
148       subdirectory (this is on purpose, to help cutting and pasting). See the
149       status.relativePaths config option below.
150
151   Short Format
152       In the short-format, the status of each path is shown as one of these
153       forms
154
155           XY PATH
156           XY ORIG_PATH -> PATH
157
158       where ORIG_PATH is where the renamed/copied contents came from.
159       ORIG_PATH is only shown when the entry is renamed or copied. The XY is
160       a two-letter status code.
161
162       The fields (including the ->) are separated from each other by a single
163       space. If a filename contains whitespace or other nonprintable
164       characters, that field will be quoted in the manner of a C string
165       literal: surrounded by ASCII double quote (34) characters, and with
166       interior special characters backslash-escaped.
167
168       There are three different types of states that are shown using this
169       format, and each one uses the XY syntax differently:
170
171       •   When a merge is occurring and the merge was successful, or outside
172           of a merge situation, X shows the status of the index and Y shows
173           the status of the working tree.
174
175       •   When a merge conflict has occurred and has not yet been resolved, X
176           and Y show the state introduced by each head of the merge, relative
177           to the common ancestor. These paths are said to be unmerged.
178
179       •   When a path is untracked, X and Y are always the same, since they
180           are unknown to the index.  ??  is used for untracked paths. Ignored
181           files are not listed unless --ignored is used; if it is, ignored
182           files are indicated by !!.
183
184       Note that the term merge here also includes rebases using the default
185       --merge strategy, cherry-picks, and anything else using the merge
186       machinery.
187
188       In the following table, these three classes are shown in separate
189       sections, and these characters are used for X and Y fields for the
190       first two sections that show tracked paths:
191
192       •   ' ' = unmodified
193
194M = modified
195
196T = file type changed (regular file, symbolic link or submodule)
197
198A = added
199
200D = deleted
201
202R = renamed
203
204C = copied (if config option status.renames is set to "copies")
205
206U = updated but unmerged
207
208           X          Y     Meaning
209           -------------------------------------------------
210                    [AMD]   not updated
211           M        [ MTD]  updated in index
212           T        [ MTD]  type changed in index
213           A        [ MTD]  added to index
214           D                deleted from index
215           R        [ MTD]  renamed in index
216           C        [ MTD]  copied in index
217           [MTARC]          index and work tree matches
218           [ MTARC]    M    work tree changed since index
219           [ MTARC]    T    type changed in work tree since index
220           [ MTARC]    D    deleted in work tree
221                       R    renamed in work tree
222                       C    copied in work tree
223           -------------------------------------------------
224           D           D    unmerged, both deleted
225           A           U    unmerged, added by us
226           U           D    unmerged, deleted by them
227           U           A    unmerged, added by them
228           D           U    unmerged, deleted by us
229           A           A    unmerged, both added
230           U           U    unmerged, both modified
231           -------------------------------------------------
232           ?           ?    untracked
233           !           !    ignored
234           -------------------------------------------------
235
236       Submodules have more state and instead report
237
238M = the submodule has a different HEAD than recorded in the index
239
240m = the submodule has modified content
241
242?  = the submodule has untracked files
243
244       This is since modified content or untracked files in a submodule cannot
245       be added via git add in the superproject to prepare a commit.
246
247       m and ? are applied recursively. For example if a nested submodule in a
248       submodule contains an untracked file, this is reported as ? as well.
249
250       If -b is used the short-format status is preceded by a line
251
252           ## branchname tracking info
253
254   Porcelain Format Version 1
255       Version 1 porcelain format is similar to the short format, but is
256       guaranteed not to change in a backwards-incompatible way between Git
257       versions or based on user configuration. This makes it ideal for
258       parsing by scripts. The description of the short format above also
259       describes the porcelain format, with a few exceptions:
260
261        1. The user’s color.status configuration is not respected; color will
262           always be off.
263
264        2. The user’s status.relativePaths configuration is not respected;
265           paths shown will always be relative to the repository root.
266
267       There is also an alternate -z format recommended for machine parsing.
268       In that format, the status field is the same, but some other things
269       change. First, the -> is omitted from rename entries and the field
270       order is reversed (e.g from -> to becomes to from). Second, a NUL
271       (ASCII 0) follows each filename, replacing space as a field separator
272       and the terminating newline (but a space still separates the status
273       field from the first filename). Third, filenames containing special
274       characters are not specially formatted; no quoting or
275       backslash-escaping is performed.
276
277       Any submodule changes are reported as modified M instead of m or single
278       ?.
279
280   Porcelain Format Version 2
281       Version 2 format adds more detailed information about the state of the
282       worktree and changed items. Version 2 also defines an extensible set of
283       easy to parse optional headers.
284
285       Header lines start with "#" and are added in response to specific
286       command line arguments. Parsers should ignore headers they don’t
287       recognize.
288
289       Branch Headers
290           If --branch is given, a series of header lines are printed with
291           information about the current branch.
292
293               Line                                     Notes
294               ------------------------------------------------------------
295               # branch.oid <commit> | (initial)        Current commit.
296               # branch.head <branch> | (detached)      Current branch.
297               # branch.upstream <upstream_branch>      If upstream is set.
298               # branch.ab +<ahead> -<behind>           If upstream is set and
299                                                        the commit is present.
300               ------------------------------------------------------------
301
302       Stash Information
303           If --show-stash is given, one line is printed showing the number of
304           stash entries if non-zero:
305
306               # stash <N>
307
308       Changed Tracked Entries
309           Following the headers, a series of lines are printed for tracked
310           entries. One of three different line formats may be used to
311           describe an entry depending on the type of change. Tracked entries
312           are printed in an undefined order; parsers should allow for a
313           mixture of the 3 line types in any order.
314
315           Ordinary changed entries have the following format:
316
317               1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>
318
319           Renamed or copied entries have the following format:
320
321               2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path><sep><origPath>
322
323               Field       Meaning
324               --------------------------------------------------------
325               <XY>        A 2 character field containing the staged and
326                           unstaged XY values described in the short format,
327                           with unchanged indicated by a "." rather than
328                           a space.
329               <sub>       A 4 character field describing the submodule state.
330                           "N..." when the entry is not a submodule.
331                           "S<c><m><u>" when the entry is a submodule.
332                           <c> is "C" if the commit changed; otherwise ".".
333                           <m> is "M" if it has tracked changes; otherwise ".".
334                           <u> is "U" if there are untracked changes; otherwise ".".
335               <mH>        The octal file mode in HEAD.
336               <mI>        The octal file mode in the index.
337               <mW>        The octal file mode in the worktree.
338               <hH>        The object name in HEAD.
339               <hI>        The object name in the index.
340               <X><score>  The rename or copy score (denoting the percentage
341                           of similarity between the source and target of the
342                           move or copy). For example "R100" or "C75".
343               <path>      The pathname.  In a renamed/copied entry, this
344                           is the target path.
345               <sep>       When the `-z` option is used, the 2 pathnames are separated
346                           with a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09)
347                           byte separates them.
348               <origPath>  The pathname in the commit at HEAD or in the index.
349                           This is only present in a renamed/copied entry, and
350                           tells where the renamed/copied contents came from.
351               --------------------------------------------------------
352
353           Unmerged entries have the following format; the first character is
354           a "u" to distinguish from ordinary changed entries.
355
356               u <XY> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>
357
358               Field       Meaning
359               --------------------------------------------------------
360               <XY>        A 2 character field describing the conflict type
361                           as described in the short format.
362               <sub>       A 4 character field describing the submodule state
363                           as described above.
364               <m1>        The octal file mode in stage 1.
365               <m2>        The octal file mode in stage 2.
366               <m3>        The octal file mode in stage 3.
367               <mW>        The octal file mode in the worktree.
368               <h1>        The object name in stage 1.
369               <h2>        The object name in stage 2.
370               <h3>        The object name in stage 3.
371               <path>      The pathname.
372               --------------------------------------------------------
373
374       Other Items
375           Following the tracked entries (and if requested), a series of lines
376           will be printed for untracked and then ignored items found in the
377           worktree.
378
379           Untracked items have the following format:
380
381               ? <path>
382
383           Ignored items have the following format:
384
385               ! <path>
386
387       Pathname Format Notes and -z
388           When the -z option is given, pathnames are printed as is and
389           without any quoting and lines are terminated with a NUL (ASCII
390           0x00) byte.
391
392           Without the -z option, pathnames with "unusual" characters are
393           quoted as explained for the configuration variable core.quotePath
394           (see git-config(1)).
395

CONFIGURATION

397       The command honors color.status (or status.color — they mean the same
398       thing and the latter is kept for backward compatibility) and
399       color.status.<slot> configuration variables to colorize its output.
400
401       If the config variable status.relativePaths is set to false, then all
402       paths shown are relative to the repository root, not to the current
403       directory.
404
405       If status.submoduleSummary is set to a non zero number or true
406       (identical to -1 or an unlimited number), the submodule summary will be
407       enabled for the long format and a summary of commits for modified
408       submodules will be shown (see --summary-limit option of git-
409       submodule(1)). Please note that the summary output from the status
410       command will be suppressed for all submodules when
411       diff.ignoreSubmodules is set to all or only for those submodules where
412       submodule.<name>.ignore=all. To also view the summary for ignored
413       submodules you can either use the --ignore-submodules=dirty command
414       line option or the git submodule summary command, which shows a similar
415       output but does not honor these settings.
416

BACKGROUND REFRESH

418       By default, git status will automatically refresh the index, updating
419       the cached stat information from the working tree and writing out the
420       result. Writing out the updated index is an optimization that isn’t
421       strictly necessary (status computes the values for itself, but writing
422       them out is just to save subsequent programs from repeating our
423       computation). When status is run in the background, the lock held
424       during the write may conflict with other simultaneous processes,
425       causing them to fail. Scripts running status in the background should
426       consider using git --no-optional-locks status (see git(1) for details).
427

UNTRACKED FILES AND PERFORMANCE

429       git status can be very slow in large worktrees if/when it needs to
430       search for untracked files and directories. There are many
431       configuration options available to speed this up by either avoiding the
432       work or making use of cached results from previous Git commands. There
433       is no single optimum set of settings right for everyone. We’ll list a
434       summary of the relevant options to help you, but before going into the
435       list, you may want to run git status again, because your configuration
436       may already be caching git status results, so it could be faster on
437       subsequent runs.
438
439       •   The --untracked-files=no flag or the
440           status.showUntrackedfiles=false config (see above for both):
441           indicate that git status should not report untracked files. This is
442           the fastest option.  git status will not list the untracked files,
443           so you need to be careful to remember if you create any new files
444           and manually git add them.
445
446advice.statusUoption=false (see git-config(1)): setting this
447           variable to false disables the warning message given when
448           enumerating untracked files takes more than 2 seconds. In a large
449           project, it may take longer and the user may have already accepted
450           the trade off (e.g. using "-uno" may not be an acceptable option
451           for the user), in which case, there is no point issuing the warning
452           message, and in such a case, disabling the warning may be the best.
453
454core.untrackedCache=true (see git-update-index(1)): enable the
455           untracked cache feature and only search directories that have been
456           modified since the previous git status command. Git remembers the
457           set of untracked files within each directory and assumes that if a
458           directory has not been modified, then the set of untracked files
459           within has not changed. This is much faster than enumerating the
460           contents of every directory, but still not without cost, because
461           Git still has to search for the set of modified directories. The
462           untracked cache is stored in the .git/index file. The reduced cost
463           of searching for untracked files is offset slightly by the
464           increased size of the index and the cost of keeping it up-to-date.
465           That reduced search time is usually worth the additional size.
466
467core.untrackedCache=true and core.fsmonitor=true or
468           core.fsmonitor=<hook_command_pathname> (see git-update-index(1)):
469           enable both the untracked cache and FSMonitor features and only
470           search directories that have been modified since the previous git
471           status command. This is faster than using just the untracked cache
472           alone because Git can also avoid searching for modified
473           directories. Git only has to enumerate the exact set of directories
474           that have changed recently. While the FSMonitor feature can be
475           enabled without the untracked cache, the benefits are greatly
476           reduced in that case.
477
478       Note that after you turn on the untracked cache and/or FSMonitor
479       features it may take a few git status commands for the various caches
480       to warm up before you see improved command times. This is normal.
481

SEE ALSO

483       gitignore(5)
484

GIT

486       Part of the git(1) suite
487
488
489
490Git 2.43.0                        11/20/2023                     GIT-STATUS(1)
Impressum