wt-status.c: handle worktree renames
[git/git.git] / Documentation / git-status.txt
CommitLineData
215a7ad1
JH
1git-status(1)
2=============
3f971fc4
JH
3
4NAME
5----
c3f0baac 6git-status - Show the working tree status
3f971fc4
JH
7
8
9SYNOPSIS
10--------
7791a1d9 11[verse]
9e4b7ab6 12'git status' [<options>...] [--] [<pathspec>...]
3f971fc4
JH
13
14DESCRIPTION
15-----------
2099bca9
JK
16Displays paths that have differences between the index file and the
17current HEAD commit, paths that have differences between the working
18tree and the index file, and paths in the working tree that are not
2de9b711 19tracked by Git (and are not ignored by linkgit:gitignore[5]). The first
2099bca9 20are what you _would_ commit by running `git commit`; the second and
0b444cdb 21third are what you _could_ commit by running 'git add' before running
2099bca9 22`git commit`.
3f971fc4 23
9e4b7ab6
JH
24OPTIONS
25-------
26
27-s::
28--short::
29 Give the output in the short-format.
30
46077fa5
MG
31-b::
32--branch::
33 Show the branch and tracking info even in short-format.
34
c4f596b9 35--porcelain[=<version>]::
fc17df03
JK
36 Give the output in an easy-to-parse format for scripts.
37 This is similar to the short output, but will remain stable
2de9b711 38 across Git versions and regardless of user configuration. See
fc17df03 39 below for details.
c4f596b9
JH
40+
41The version parameter is used to specify the format version.
42This is optional and defaults to the original version 'v1' format.
6f157871 43
f3f47a1e
JK
44--long::
45 Give the output in the long-format. This is the default.
46
9c589d97
MH
47-v::
48--verbose::
49 In addition to the names of files that have been changed, also
50 show the textual changes that are staged to be committed
51 (i.e., like the output of `git diff --cached`). If `-v` is specified
52 twice, then also show the changes in the working tree that
53 have not yet been staged (i.e., like the output of `git diff`).
54
9e4b7ab6
JH
55-u[<mode>]::
56--untracked-files[=<mode>]::
4cc62606 57 Show untracked files.
9e4b7ab6 58+
2b594bf9
MM
59The mode parameter is used to specify the handling of untracked files.
60It is optional: it defaults to 'all', and if specified, it must be
61stuck to the option (e.g. `-uno`, but not `-u no`).
4cc62606
CB
62+
63The possible options are:
9e4b7ab6 64+
5823eb2b
JH
65 - 'no' - Show no untracked files.
66 - 'normal' - Shows untracked files and directories.
9e4b7ab6 67 - 'all' - Also shows individual files in untracked directories.
9e4b7ab6 68+
5823eb2b
JH
69When `-u` option is not used, untracked files and directories are
70shown (i.e. the same as specifying `normal`), to help you avoid
71forgetting to add newly created files. Because it takes extra work
72to find untracked files in the filesystem, this mode may take some
aeb6f8b3
NTND
73time in a large working tree.
74Consider enabling untracked cache and split index if supported (see
75`git update-index --untracked-cache` and `git update-index
76--split-index`), Otherwise you can use `no` to have `git status`
5823eb2b
JH
77return more quickly without showing untracked files.
78+
4cc62606
CB
79The default can be changed using the status.showUntrackedFiles
80configuration variable documented in linkgit:git-config[1].
9e4b7ab6 81
46a958b3
JL
82--ignore-submodules[=<when>]::
83 Ignore changes to submodules when looking for changes. <when> can be
aee9c7d6
JL
84 either "none", "untracked", "dirty" or "all", which is the default.
85 Using "none" will consider the submodule modified when it either contains
86 untracked or modified files or its HEAD differs from the commit recorded
87 in the superproject and can be used to override any settings of the
302ad7a9 88 'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When
46a958b3
JL
89 "untracked" is used submodules are not considered dirty when they only
90 contain untracked content (but they are still scanned for modified
91 content). Using "dirty" ignores all changes to the work tree of submodules,
92 only changes to the commits stored in the superproject are shown (this was
93 the behavior before 1.7.0). Using "all" hides all changes to submodules
94 (and suppresses the output of submodule summaries when the config option
da0005b8 95 `status.submoduleSummary` is set).
46a958b3 96
150b493a
JH
97--ignored::
98 Show ignored files as well.
99
9e4b7ab6 100-z::
6f157871 101 Terminate entries with NUL, instead of LF. This implies
c4f596b9 102 the `--porcelain=v1` output format if no other format is given.
2099bca9 103
323d0530
NTND
104--column[=<options>]::
105--no-column::
106 Display untracked files in columns. See configuration variable
107 column.status for option syntax.`--column` and `--no-column`
108 without options are equivalent to 'always' and 'never'
109 respectively.
110
3f971fc4
JH
111
112OUTPUT
113------
114The output from this command is designed to be used as a commit
22d55aee 115template comment.
9e4b7ab6 116The default, long format, is designed to be human readable,
043b5cd9
JK
117verbose and descriptive. Its contents and format are subject to change
118at any time.
3f971fc4 119
2de9b711 120The paths mentioned in the output, unlike many other Git commands, are
2099bca9 121made relative to the current directory if you are working in a
46f721c8
JK
122subdirectory (this is on purpose, to help cutting and pasting). See
123the status.relativePaths config option below.
c7860507 124
fc17df03
JK
125Short Format
126~~~~~~~~~~~~
127
176ea747
NTND
128In the short-format, the status of each path is shown as one of these
129forms
9e4b7ab6 130
176ea747
NTND
131 XY PATH
132 XY ORIG_PATH -> PATH
9e4b7ab6 133
176ea747
NTND
134where `ORIG_PATH` is where the renamed/copied contents came
135from. `ORIG_PATH` is only shown when the entry is renamed or
136copied. The `XY` is a two-letter status code.
e92e9cd3 137
6cf378f0 138The fields (including the `->`) are separated from each other by a
e92e9cd3
ER
139single space. If a filename contains whitespace or other nonprintable
140characters, that field will be quoted in the manner of a C string
141literal: surrounded by ASCII double quote (34) characters, and with
142interior special characters backslash-escaped.
143
7c45cee6 144For paths with merge conflicts, `X` and `Y` show the modification
e92e9cd3
ER
145states of each side of the merge. For paths that do not have merge
146conflicts, `X` shows the status of the index, and `Y` shows the status
147of the work tree. For untracked paths, `XY` are `??`. Other status
148codes can be interpreted as follows:
149
150* ' ' = unmodified
151* 'M' = modified
152* 'A' = added
153* 'D' = deleted
154* 'R' = renamed
155* 'C' = copied
156* 'U' = updated but unmerged
157
50cebdad
JH
158Ignored files are not listed, unless `--ignored` option is in effect,
159in which case `XY` are `!!`.
9e4b7ab6
JH
160
161 X Y Meaning
162 -------------------------------------------------
163 [MD] not updated
164 M [ MD] updated in index
165 A [ MD] added to index
e92e9cd3 166 D [ M] deleted from index
9e4b7ab6
JH
167 R [ MD] renamed in index
168 C [ MD] copied in index
169 [MARC] index and work tree matches
170 [ MARC] M work tree changed since index
171 [ MARC] D deleted in work tree
176ea747
NTND
172 [ D] R renamed in work tree
173 [ D] C copied in work tree
9e4b7ab6
JH
174 -------------------------------------------------
175 D D unmerged, both deleted
176 A U unmerged, added by us
177 U D unmerged, deleted by them
178 U A unmerged, added by them
179 D U unmerged, deleted by us
180 A A unmerged, both added
181 U U unmerged, both modified
182 -------------------------------------------------
183 ? ? untracked
150b493a 184 ! ! ignored
9e4b7ab6
JH
185 -------------------------------------------------
186
dd6962dd
SB
187Submodules have more state and instead report
188 M the submodule has a different HEAD than
189 recorded in the index
190 m the submodule has modified content
191 ? the submodule has untracked files
192since modified content or untracked files in a submodule cannot be added
193via `git add` in the superproject to prepare a commit.
194
40069d6e
SB
195'm' and '?' are applied recursively. For example if a nested submodule
196in a submodule contains an untracked file, this is reported as '?' as well.
dd6962dd 197
46077fa5
MG
198If -b is used the short-format status is preceded by a line
199
1cd828dd 200 ## branchname tracking info
46077fa5 201
1cd828dd
JH
202Porcelain Format Version 1
203~~~~~~~~~~~~~~~~~~~~~~~~~~
fc17df03 204
1cd828dd 205Version 1 porcelain format is similar to the short format, but is guaranteed
2de9b711 206not to change in a backwards-incompatible way between Git versions or
fc17df03
JK
207based on user configuration. This makes it ideal for parsing by scripts.
208The description of the short format above also describes the porcelain
209format, with a few exceptions:
210
2111. The user's color.status configuration is not respected; color will
212 always be off.
213
2142. The user's status.relativePaths configuration is not respected; paths
215 shown will always be relative to the repository root.
216
217There is also an alternate -z format recommended for machine parsing. In
e92e9cd3 218that format, the status field is the same, but some other things
715e716a
JK
219change. First, the '\->' is omitted from rename entries and the field
220order is reversed (e.g 'from \-> to' becomes 'to from'). Second, a NUL
e92e9cd3
ER
221(ASCII 0) follows each filename, replacing space as a field separator
222and the terminating newline (but a space still separates the status
223field from the first filename). Third, filenames containing special
224characters are not specially formatted; no quoting or
d4a6bf1f 225backslash-escaping is performed.
3f971fc4 226
dd6962dd
SB
227Any submodule changes are reported as modified `M` instead of `m` or single `?`.
228
1cd828dd
JH
229Porcelain Format Version 2
230~~~~~~~~~~~~~~~~~~~~~~~~~~
231
232Version 2 format adds more detailed information about the state of
233the worktree and changed items. Version 2 also defines an extensible
234set of easy to parse optional headers.
235
236Header lines start with "#" and are added in response to specific
237command line arguments. Parsers should ignore headers they
238don't recognize.
239
240### Branch Headers
241
242If `--branch` is given, a series of header lines are printed with
243information about the current branch.
244
245 Line Notes
246 ------------------------------------------------------------
247 # branch.oid <commit> | (initial) Current commit.
248 # branch.head <branch> | (detached) Current branch.
249 # branch.upstream <upstream_branch> If upstream is set.
250 # branch.ab +<ahead> -<behind> If upstream is set and
251 the commit is present.
252 ------------------------------------------------------------
253
254### Changed Tracked Entries
255
256Following the headers, a series of lines are printed for tracked
257entries. One of three different line formats may be used to describe
258an entry depending on the type of change. Tracked entries are printed
259in an undefined order; parsers should allow for a mixture of the 3
260line types in any order.
261
262Ordinary changed entries have the following format:
263
264 1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>
265
266Renamed or copied entries have the following format:
267
268 2 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path><sep><origPath>
269
270 Field Meaning
271 --------------------------------------------------------
272 <XY> A 2 character field containing the staged and
273 unstaged XY values described in the short format,
274 with unchanged indicated by a "." rather than
275 a space.
276 <sub> A 4 character field describing the submodule state.
277 "N..." when the entry is not a submodule.
278 "S<c><m><u>" when the entry is a submodule.
279 <c> is "C" if the commit changed; otherwise ".".
280 <m> is "M" if it has tracked changes; otherwise ".".
281 <u> is "U" if there are untracked changes; otherwise ".".
282 <mH> The octal file mode in HEAD.
283 <mI> The octal file mode in the index.
284 <mW> The octal file mode in the worktree.
285 <hH> The object name in HEAD.
286 <hI> The object name in the index.
287 <X><score> The rename or copy score (denoting the percentage
288 of similarity between the source and target of the
289 move or copy). For example "R100" or "C75".
290 <path> The pathname. In a renamed/copied entry, this
176ea747 291 is the target path.
1cd828dd
JH
292 <sep> When the `-z` option is used, the 2 pathnames are separated
293 with a NUL (ASCII 0x00) byte; otherwise, a tab (ASCII 0x09)
294 byte separates them.
176ea747
NTND
295 <origPath> The pathname in the commit at HEAD or in the index.
296 This is only present in a renamed/copied entry, and
297 tells where the renamed/copied contents came from.
1cd828dd
JH
298 --------------------------------------------------------
299
300Unmerged entries have the following format; the first character is
301a "u" to distinguish from ordinary changed entries.
302
303 u <xy> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>
304
305 Field Meaning
306 --------------------------------------------------------
307 <XY> A 2 character field describing the conflict type
308 as described in the short format.
309 <sub> A 4 character field describing the submodule state
310 as described above.
311 <m1> The octal file mode in stage 1.
312 <m2> The octal file mode in stage 2.
313 <m3> The octal file mode in stage 3.
314 <mW> The octal file mode in the worktree.
315 <h1> The object name in stage 1.
316 <h2> The object name in stage 2.
317 <h3> The object name in stage 3.
318 <path> The pathname.
319 --------------------------------------------------------
320
321### Other Items
322
323Following the tracked entries (and if requested), a series of
324lines will be printed for untracked and then ignored items
325found in the worktree.
326
327Untracked items have the following format:
328
329 ? <path>
330
331Ignored items have the following format:
332
333 ! <path>
334
335### Pathname Format Notes and -z
336
337When the `-z` option is given, pathnames are printed as is and
338without any quoting and lines are terminated with a NUL (ASCII 0x00)
339byte.
340
860cd699
AH
341Without the `-z` option, pathnames with "unusual" characters are
342quoted as explained for the configuration variable `core.quotePath`
343(see linkgit:git-config[1]).
1cd828dd
JH
344
345
31fcd63c
JH
346CONFIGURATION
347-------------
348
349The command honors `color.status` (or `status.color` -- they
350mean the same thing and the latter is kept for backward
351compatibility) and `color.status.<slot>` configuration variables
352to colorize its output.
353
46f721c8 354If the config variable `status.relativePaths` is set to false, then all
482a6c10
MG
355paths shown are relative to the repository root, not to the current
356directory.
46f721c8 357
da0005b8 358If `status.submoduleSummary` is set to a non zero number or true (identical
46b77a6b
JK
359to -1 or an unlimited number), the submodule summary will be enabled for
360the long format and a summary of commits for modified submodules will be
bb58b696
JL
361shown (see --summary-limit option of linkgit:git-submodule[1]). Please note
362that the summary output from the status command will be suppressed for all
363submodules when `diff.ignoreSubmodules` is set to 'all' or only for those
364submodules where `submodule.<name>.ignore=all`. To also view the summary for
365ignored submodules you can either use the --ignore-submodules=dirty command
366line option or the 'git submodule summary' command, which shows a similar
367output but does not honor these settings.
ac8d5afc 368
56ae8df5 369SEE ALSO
cedb8d5d 370--------
5162e697 371linkgit:gitignore[5]
31fcd63c 372
3f971fc4
JH
373GIT
374---
9e1f0a85 375Part of the linkgit:git[1] suite