Merge branch 'jt/namespaced-ls-refs-fix'
[git/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 The mode parameter is used to specify the handling of untracked files.
63 It is optional: it defaults to 'all', and if specified, it must be
64 stuck to the option (e.g. `-uno`, but not `-u no`).
65 +
66 The possible options are:
67 +
68 - 'no' - Show no untracked files.
69 - 'normal' - Shows untracked files and directories.
70 - 'all' - Also shows individual files in untracked directories.
71 +
72 When `-u` option is not used, untracked files and directories are
73 shown (i.e. the same as specifying `normal`), to help you avoid
74 forgetting to add newly created files. Because it takes extra work
75 to find untracked files in the filesystem, this mode may take some
76 time in a large working tree.
77 Consider enabling untracked cache and split index if supported (see
78 `git update-index --untracked-cache` and `git update-index
79 --split-index`), Otherwise you can use `no` to have `git status`
80 return more quickly without showing untracked files.
81 +
82 The default can be changed using the status.showUntrackedFiles
83 configuration variable documented in linkgit:git-config[1].
84
85 --ignore-submodules[=<when>]::
86 Ignore changes to submodules when looking for changes. <when> can be
87 either "none", "untracked", "dirty" or "all", which is the default.
88 Using "none" will consider the submodule modified when it either contains
89 untracked or modified files or its HEAD differs from the commit recorded
90 in the superproject and can be used to override any settings of the
91 'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When
92 "untracked" is used submodules are not considered dirty when they only
93 contain untracked content (but they are still scanned for modified
94 content). Using "dirty" ignores all changes to the work tree of submodules,
95 only changes to the commits stored in the superproject are shown (this was
96 the behavior before 1.7.0). Using "all" hides all changes to submodules
97 (and suppresses the output of submodule summaries when the config option
98 `status.submoduleSummary` is set).
99
100 --ignored[=<mode>]::
101 Show ignored files as well.
102 +
103 The mode parameter is used to specify the handling of ignored files.
104 It is optional: it defaults to 'traditional'.
105 +
106 The possible options are:
107 +
108 - 'traditional' - Shows ignored files and directories, unless
109 --untracked-files=all is specified, in which case
110 individual files in ignored directories are
111 displayed.
112 - 'no' - Show no ignored files.
113 - 'matching' - Shows ignored files and directories matching an
114 ignore pattern.
115 +
116 When 'matching' mode is specified, paths that explicitly match an
117 ignored pattern are shown. If a directory matches an ignore pattern,
118 then it is shown, but not paths contained in the ignored directory. If
119 a directory does not match an ignore pattern, but all contents are
120 ignored, then the directory is not shown, but all contents are shown.
121
122 -z::
123 Terminate entries with NUL, instead of LF. This implies
124 the `--porcelain=v1` output format if no other format is given.
125
126 --column[=<options>]::
127 --no-column::
128 Display untracked files in columns. See configuration variable
129 column.status for option syntax.`--column` and `--no-column`
130 without options are equivalent to 'always' and 'never'
131 respectively.
132
133 --ahead-behind::
134 --no-ahead-behind::
135 Display or do not display detailed ahead/behind counts for the
136 branch relative to its upstream branch. Defaults to true.
137
138 --renames::
139 --no-renames::
140 Turn on/off rename detection regardless of user configuration.
141 See also linkgit:git-diff[1] `--no-renames`.
142
143 --find-renames[=<n>]::
144 Turn on rename detection, optionally setting the similarity
145 threshold.
146 See also linkgit:git-diff[1] `--find-renames`.
147
148 <pathspec>...::
149 See the 'pathspec' entry in linkgit:gitglossary[7].
150
151 OUTPUT
152 ------
153 The output from this command is designed to be used as a commit
154 template comment.
155 The default, long format, is designed to be human readable,
156 verbose and descriptive. Its contents and format are subject to change
157 at any time.
158
159 The paths mentioned in the output, unlike many other Git commands, are
160 made relative to the current directory if you are working in a
161 subdirectory (this is on purpose, to help cutting and pasting). See
162 the status.relativePaths config option below.
163
164 Short Format
165 ~~~~~~~~~~~~
166
167 In the short-format, the status of each path is shown as one of these
168 forms
169
170 XY PATH
171 XY ORIG_PATH -> PATH
172
173 where `ORIG_PATH` is where the renamed/copied contents came
174 from. `ORIG_PATH` is only shown when the entry is renamed or
175 copied. The `XY` is a two-letter status code.
176
177 The fields (including the `->`) are separated from each other by a
178 single space. If a filename contains whitespace or other nonprintable
179 characters, that field will be quoted in the manner of a C string
180 literal: surrounded by ASCII double quote (34) characters, and with
181 interior special characters backslash-escaped.
182
183 For paths with merge conflicts, `X` and `Y` show the modification
184 states of each side of the merge. For paths that do not have merge
185 conflicts, `X` shows the status of the index, and `Y` shows the status
186 of the work tree. For untracked paths, `XY` are `??`. Other status
187 codes can be interpreted as follows:
188
189 * ' ' = unmodified
190 * 'M' = modified
191 * 'A' = added
192 * 'D' = deleted
193 * 'R' = renamed
194 * 'C' = copied
195 * 'U' = updated but unmerged
196
197 Ignored files are not listed, unless `--ignored` option is in effect,
198 in which case `XY` are `!!`.
199
200 ....
201 X Y Meaning
202 -------------------------------------------------
203 [AMD] not updated
204 M [ MD] updated in index
205 A [ MD] added to index
206 D deleted from index
207 R [ MD] renamed in index
208 C [ MD] copied in index
209 [MARC] index and work tree matches
210 [ MARC] M work tree changed since index
211 [ MARC] D deleted in work tree
212 [ D] R renamed in work tree
213 [ D] C copied in work tree
214 -------------------------------------------------
215 D D unmerged, both deleted
216 A U unmerged, added by us
217 U D unmerged, deleted by them
218 U A unmerged, added by them
219 D U unmerged, deleted by us
220 A A unmerged, both added
221 U U unmerged, both modified
222 -------------------------------------------------
223 ? ? untracked
224 ! ! ignored
225 -------------------------------------------------
226 ....
227
228 Submodules have more state and instead report
229 M the submodule has a different HEAD than
230 recorded in the index
231 m the submodule has modified content
232 ? the submodule has untracked files
233 since modified content or untracked files in a submodule cannot be added
234 via `git add` in the superproject to prepare a commit.
235
236 'm' and '?' are applied recursively. For example if a nested submodule
237 in a submodule contains an untracked file, this is reported as '?' as well.
238
239 If -b is used the short-format status is preceded by a line
240
241 ## branchname tracking info
242
243 Porcelain Format Version 1
244 ~~~~~~~~~~~~~~~~~~~~~~~~~~
245
246 Version 1 porcelain format is similar to the short format, but is guaranteed
247 not to change in a backwards-incompatible way between Git versions or
248 based on user configuration. This makes it ideal for parsing by scripts.
249 The description of the short format above also describes the porcelain
250 format, with a few exceptions:
251
252 1. The user's color.status configuration is not respected; color will
253 always be off.
254
255 2. The user's status.relativePaths configuration is not respected; paths
256 shown will always be relative to the repository root.
257
258 There is also an alternate -z format recommended for machine parsing. In
259 that format, the status field is the same, but some other things
260 change. First, the '\->' is omitted from rename entries and the field
261 order is reversed (e.g 'from \-> to' becomes 'to from'). Second, a NUL
262 (ASCII 0) follows each filename, replacing space as a field separator
263 and the terminating newline (but a space still separates the status
264 field from the first filename). Third, filenames containing special
265 characters are not specially formatted; no quoting or
266 backslash-escaping is performed.
267
268 Any submodule changes are reported as modified `M` instead of `m` or single `?`.
269
270 Porcelain Format Version 2
271 ~~~~~~~~~~~~~~~~~~~~~~~~~~
272
273 Version 2 format adds more detailed information about the state of
274 the worktree and changed items. Version 2 also defines an extensible
275 set of easy to parse optional headers.
276
277 Header lines start with "#" and are added in response to specific
278 command line arguments. Parsers should ignore headers they
279 don't recognize.
280
281 ### Branch Headers
282
283 If `--branch` is given, a series of header lines are printed with
284 information about the current branch.
285
286 ....
287 Line Notes
288 ------------------------------------------------------------
289 # branch.oid <commit> | (initial) Current commit.
290 # branch.head <branch> | (detached) Current branch.
291 # branch.upstream <upstream_branch> If upstream is set.
292 # branch.ab +<ahead> -<behind> If upstream is set and
293 the commit is present.
294 ------------------------------------------------------------
295 ....
296
297 ### Changed Tracked Entries
298
299 Following the headers, a series of lines are printed for tracked
300 entries. One of three different line formats may be used to describe
301 an entry depending on the type of change. Tracked entries are printed
302 in an undefined order; parsers should allow for a mixture of the 3
303 line types in any order.
304
305 Ordinary changed entries have the following format:
306
307 1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>
308
309 Renamed or copied entries have the following format:
310
311 2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path><sep><origPath>
312
313 ....
314 Field Meaning
315 --------------------------------------------------------
316 <XY> A 2 character field containing the staged and
317 unstaged XY values described in the short format,
318 with unchanged indicated by a "." rather than
319 a space.
320 <sub> A 4 character field describing the submodule state.
321 "N..." when the entry is not a submodule.
322 "S<c><m><u>" when the entry is a submodule.
323 <c> is "C" if the commit changed; otherwise ".".
324 <m> is "M" if it has tracked changes; otherwise ".".
325 <u> is "U" if there are untracked changes; otherwise ".".
326 <mH> The octal file mode in HEAD.
327 <mI> The octal file mode in the index.
328 <mW> The octal file mode in the worktree.
329 <hH> The object name in HEAD.
330 <hI> The object name in the index.
331 <X><score> The rename or copy score (denoting the percentage
332 of similarity between the source and target of the
333 move or copy). For example "R100" or "C75".
334 <path> The pathname. In a renamed/copied entry, this
335 is the target path.
336 <sep> When the `-z` option is used, the 2 pathnames are separated
337 with a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09)
338 byte separates them.
339 <origPath> The pathname in the commit at HEAD or in the index.
340 This is only present in a renamed/copied entry, and
341 tells where the renamed/copied contents came from.
342 --------------------------------------------------------
343 ....
344
345 Unmerged entries have the following format; the first character is
346 a "u" to distinguish from ordinary changed entries.
347
348 u <xy> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>
349
350 ....
351 Field Meaning
352 --------------------------------------------------------
353 <XY> A 2 character field describing the conflict type
354 as described in the short format.
355 <sub> A 4 character field describing the submodule state
356 as described above.
357 <m1> The octal file mode in stage 1.
358 <m2> The octal file mode in stage 2.
359 <m3> The octal file mode in stage 3.
360 <mW> The octal file mode in the worktree.
361 <h1> The object name in stage 1.
362 <h2> The object name in stage 2.
363 <h3> The object name in stage 3.
364 <path> The pathname.
365 --------------------------------------------------------
366 ....
367
368 ### Other Items
369
370 Following the tracked entries (and if requested), a series of
371 lines will be printed for untracked and then ignored items
372 found in the worktree.
373
374 Untracked items have the following format:
375
376 ? <path>
377
378 Ignored items have the following format:
379
380 ! <path>
381
382 ### Pathname Format Notes and -z
383
384 When the `-z` option is given, pathnames are printed as is and
385 without any quoting and lines are terminated with a NUL (ASCII 0x00)
386 byte.
387
388 Without the `-z` option, pathnames with "unusual" characters are
389 quoted as explained for the configuration variable `core.quotePath`
390 (see linkgit:git-config[1]).
391
392
393 CONFIGURATION
394 -------------
395
396 The command honors `color.status` (or `status.color` -- they
397 mean the same thing and the latter is kept for backward
398 compatibility) and `color.status.<slot>` configuration variables
399 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 (identical
406 to -1 or an unlimited number), the submodule summary will be enabled for
407 the long format and a summary of commits for modified submodules will be
408 shown (see --summary-limit option of linkgit:git-submodule[1]). Please note
409 that the summary output from the status command will be suppressed for all
410 submodules when `diff.ignoreSubmodules` is set to 'all' or only for those
411 submodules where `submodule.<name>.ignore=all`. To also view the summary for
412 ignored submodules you can either use the --ignore-submodules=dirty command
413 line option or the 'git submodule summary' command, which shows a similar
414 output but does not honor these settings.
415
416 BACKGROUND REFRESH
417 ------------------
418
419 By default, `git status` will automatically refresh the index, updating
420 the cached stat information from the working tree and writing out the
421 result. Writing out the updated index is an optimization that isn't
422 strictly necessary (`status` computes the values for itself, but writing
423 them out is just to save subsequent programs from repeating our
424 computation). When `status` is run in the background, the lock held
425 during the write may conflict with other simultaneous processes, causing
426 them to fail. Scripts running `status` in the background should consider
427 using `git --no-optional-locks status` (see linkgit:git[1] for details).
428
429 SEE ALSO
430 --------
431 linkgit:gitignore[5]
432
433 GIT
434 ---
435 Part of the linkgit:git[1] suite