]>
Commit | Line | Data |
---|---|---|
215a7ad1 JH |
1 | git-status(1) |
2 | ============= | |
3f971fc4 JH |
3 | |
4 | NAME | |
5 | ---- | |
c3f0baac | 6 | git-status - Show the working tree status |
3f971fc4 JH |
7 | |
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
7791a1d9 | 11 | [verse] |
9e4b7ab6 | 12 | 'git status' [<options>...] [--] [<pathspec>...] |
3f971fc4 JH |
13 | |
14 | DESCRIPTION | |
15 | ----------- | |
2099bca9 JK |
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 | |
2de9b711 | 19 | tracked by Git (and are not ignored by linkgit:gitignore[5]). The first |
2099bca9 | 20 | are what you _would_ commit by running `git commit`; the second and |
0b444cdb | 21 | third are what you _could_ commit by running 'git add' before running |
2099bca9 | 22 | `git commit`. |
3f971fc4 | 23 | |
9e4b7ab6 JH |
24 | OPTIONS |
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 | ||
c1b5d019 LB |
35 | --show-stash:: |
36 | Show the number of entries currently stashed away. | |
37 | ||
c4f596b9 | 38 | --porcelain[=<version>]:: |
fc17df03 JK |
39 | Give the output in an easy-to-parse format for scripts. |
40 | This is similar to the short output, but will remain stable | |
2de9b711 | 41 | across Git versions and regardless of user configuration. See |
fc17df03 | 42 | below for details. |
c4f596b9 JH |
43 | + |
44 | The version parameter is used to specify the format version. | |
45 | This is optional and defaults to the original version 'v1' format. | |
6f157871 | 46 | |
f3f47a1e JK |
47 | --long:: |
48 | Give the output in the long-format. This is the default. | |
49 | ||
9c589d97 MH |
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 | ||
9e4b7ab6 JH |
58 | -u[<mode>]:: |
59 | --untracked-files[=<mode>]:: | |
4cc62606 | 60 | Show untracked files. |
9e4b7ab6 | 61 | + |
2b594bf9 MM |
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`). | |
4cc62606 CB |
65 | + |
66 | The possible options are: | |
9e4b7ab6 | 67 | + |
5823eb2b JH |
68 | - 'no' - Show no untracked files. |
69 | - 'normal' - Shows untracked files and directories. | |
9e4b7ab6 | 70 | - 'all' - Also shows individual files in untracked directories. |
9e4b7ab6 | 71 | + |
5823eb2b JH |
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 | |
aeb6f8b3 NTND |
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` | |
5823eb2b JH |
80 | return more quickly without showing untracked files. |
81 | + | |
4cc62606 CB |
82 | The default can be changed using the status.showUntrackedFiles |
83 | configuration variable documented in linkgit:git-config[1]. | |
9e4b7ab6 | 84 | |
46a958b3 JL |
85 | --ignore-submodules[=<when>]:: |
86 | Ignore changes to submodules when looking for changes. <when> can be | |
aee9c7d6 JL |
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 | |
302ad7a9 | 91 | 'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When |
46a958b3 JL |
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 | |
da0005b8 | 98 | `status.submoduleSummary` is set). |
46a958b3 | 99 | |
150b493a JH |
100 | --ignored:: |
101 | Show ignored files as well. | |
102 | ||
9e4b7ab6 | 103 | -z:: |
6f157871 | 104 | Terminate entries with NUL, instead of LF. This implies |
c4f596b9 | 105 | the `--porcelain=v1` output format if no other format is given. |
2099bca9 | 106 | |
323d0530 NTND |
107 | --column[=<options>]:: |
108 | --no-column:: | |
109 | Display untracked files in columns. See configuration variable | |
110 | column.status for option syntax.`--column` and `--no-column` | |
111 | without options are equivalent to 'always' and 'never' | |
112 | respectively. | |
113 | ||
3f971fc4 JH |
114 | |
115 | OUTPUT | |
116 | ------ | |
117 | The output from this command is designed to be used as a commit | |
22d55aee | 118 | template comment. |
9e4b7ab6 | 119 | The default, long format, is designed to be human readable, |
043b5cd9 JK |
120 | verbose and descriptive. Its contents and format are subject to change |
121 | at any time. | |
3f971fc4 | 122 | |
2de9b711 | 123 | The paths mentioned in the output, unlike many other Git commands, are |
2099bca9 | 124 | made relative to the current directory if you are working in a |
46f721c8 JK |
125 | subdirectory (this is on purpose, to help cutting and pasting). See |
126 | the status.relativePaths config option below. | |
c7860507 | 127 | |
fc17df03 JK |
128 | Short Format |
129 | ~~~~~~~~~~~~ | |
130 | ||
043b5cd9 | 131 | In the short-format, the status of each path is shown as |
9e4b7ab6 JH |
132 | |
133 | XY PATH1 -> PATH2 | |
134 | ||
6cf378f0 | 135 | where `PATH1` is the path in the `HEAD`, and the " `-> PATH2`" part is |
9e4b7ab6 | 136 | shown only when `PATH1` corresponds to a different path in the |
7c45cee6 | 137 | index/worktree (i.e. the file is renamed). The `XY` is a two-letter |
e92e9cd3 ER |
138 | status code. |
139 | ||
6cf378f0 | 140 | The fields (including the `->`) are separated from each other by a |
e92e9cd3 ER |
141 | single space. If a filename contains whitespace or other nonprintable |
142 | characters, that field will be quoted in the manner of a C string | |
143 | literal: surrounded by ASCII double quote (34) characters, and with | |
144 | interior special characters backslash-escaped. | |
145 | ||
7c45cee6 | 146 | For paths with merge conflicts, `X` and `Y` show the modification |
e92e9cd3 ER |
147 | states of each side of the merge. For paths that do not have merge |
148 | conflicts, `X` shows the status of the index, and `Y` shows the status | |
149 | of the work tree. For untracked paths, `XY` are `??`. Other status | |
150 | codes can be interpreted as follows: | |
151 | ||
152 | * ' ' = unmodified | |
153 | * 'M' = modified | |
154 | * 'A' = added | |
155 | * 'D' = deleted | |
156 | * 'R' = renamed | |
157 | * 'C' = copied | |
158 | * 'U' = updated but unmerged | |
159 | ||
50cebdad JH |
160 | Ignored files are not listed, unless `--ignored` option is in effect, |
161 | in which case `XY` are `!!`. | |
9e4b7ab6 JH |
162 | |
163 | X Y Meaning | |
164 | ------------------------------------------------- | |
165 | [MD] not updated | |
166 | M [ MD] updated in index | |
167 | A [ MD] added to index | |
e92e9cd3 | 168 | D [ M] deleted from index |
9e4b7ab6 JH |
169 | R [ MD] renamed in index |
170 | C [ MD] copied in index | |
171 | [MARC] index and work tree matches | |
172 | [ MARC] M work tree changed since index | |
173 | [ MARC] D deleted in work tree | |
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 |
187 | Submodules 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 | |
192 | since modified content or untracked files in a submodule cannot be added | |
193 | via `git add` in the superproject to prepare a commit. | |
194 | ||
40069d6e SB |
195 | 'm' and '?' are applied recursively. For example if a nested submodule |
196 | in a submodule contains an untracked file, this is reported as '?' as well. | |
dd6962dd | 197 | |
46077fa5 MG |
198 | If -b is used the short-format status is preceded by a line |
199 | ||
1cd828dd | 200 | ## branchname tracking info |
46077fa5 | 201 | |
1cd828dd JH |
202 | Porcelain Format Version 1 |
203 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
fc17df03 | 204 | |
1cd828dd | 205 | Version 1 porcelain format is similar to the short format, but is guaranteed |
2de9b711 | 206 | not to change in a backwards-incompatible way between Git versions or |
fc17df03 JK |
207 | based on user configuration. This makes it ideal for parsing by scripts. |
208 | The description of the short format above also describes the porcelain | |
209 | format, with a few exceptions: | |
210 | ||
211 | 1. The user's color.status configuration is not respected; color will | |
212 | always be off. | |
213 | ||
214 | 2. The user's status.relativePaths configuration is not respected; paths | |
215 | shown will always be relative to the repository root. | |
216 | ||
217 | There is also an alternate -z format recommended for machine parsing. In | |
e92e9cd3 | 218 | that format, the status field is the same, but some other things |
715e716a JK |
219 | change. First, the '\->' is omitted from rename entries and the field |
220 | order 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 |
222 | and the terminating newline (but a space still separates the status | |
223 | field from the first filename). Third, filenames containing special | |
224 | characters are not specially formatted; no quoting or | |
d4a6bf1f | 225 | backslash-escaping is performed. |
3f971fc4 | 226 | |
dd6962dd SB |
227 | Any submodule changes are reported as modified `M` instead of `m` or single `?`. |
228 | ||
1cd828dd JH |
229 | Porcelain Format Version 2 |
230 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
231 | ||
232 | Version 2 format adds more detailed information about the state of | |
233 | the worktree and changed items. Version 2 also defines an extensible | |
234 | set of easy to parse optional headers. | |
235 | ||
236 | Header lines start with "#" and are added in response to specific | |
237 | command line arguments. Parsers should ignore headers they | |
238 | don't recognize. | |
239 | ||
240 | ### Branch Headers | |
241 | ||
242 | If `--branch` is given, a series of header lines are printed with | |
243 | information 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 | ||
256 | Following the headers, a series of lines are printed for tracked | |
257 | entries. One of three different line formats may be used to describe | |
258 | an entry depending on the type of change. Tracked entries are printed | |
259 | in an undefined order; parsers should allow for a mixture of the 3 | |
260 | line types in any order. | |
261 | ||
262 | Ordinary changed entries have the following format: | |
263 | ||
264 | 1 <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path> | |
265 | ||
266 | Renamed 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 | |
291 | is the path in the index and in the working tree. | |
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. | |
295 | <origPath> The pathname in the commit at HEAD. This is only | |
296 | present in a renamed/copied entry, and tells | |
297 | where the renamed/copied contents came from. | |
298 | -------------------------------------------------------- | |
299 | ||
300 | Unmerged entries have the following format; the first character is | |
301 | a "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 | ||
323 | Following the tracked entries (and if requested), a series of | |
324 | lines will be printed for untracked and then ignored items | |
325 | found in the worktree. | |
326 | ||
327 | Untracked items have the following format: | |
328 | ||
329 | ? <path> | |
330 | ||
331 | Ignored items have the following format: | |
332 | ||
333 | ! <path> | |
334 | ||
335 | ### Pathname Format Notes and -z | |
336 | ||
337 | When the `-z` option is given, pathnames are printed as is and | |
338 | without any quoting and lines are terminated with a NUL (ASCII 0x00) | |
339 | byte. | |
340 | ||
860cd699 AH |
341 | Without the `-z` option, pathnames with "unusual" characters are |
342 | quoted as explained for the configuration variable `core.quotePath` | |
343 | (see linkgit:git-config[1]). | |
1cd828dd JH |
344 | |
345 | ||
31fcd63c JH |
346 | CONFIGURATION |
347 | ------------- | |
348 | ||
349 | The command honors `color.status` (or `status.color` -- they | |
350 | mean the same thing and the latter is kept for backward | |
351 | compatibility) and `color.status.<slot>` configuration variables | |
352 | to colorize its output. | |
353 | ||
46f721c8 | 354 | If the config variable `status.relativePaths` is set to false, then all |
482a6c10 MG |
355 | paths shown are relative to the repository root, not to the current |
356 | directory. | |
46f721c8 | 357 | |
da0005b8 | 358 | If `status.submoduleSummary` is set to a non zero number or true (identical |
46b77a6b JK |
359 | to -1 or an unlimited number), the submodule summary will be enabled for |
360 | the long format and a summary of commits for modified submodules will be | |
bb58b696 JL |
361 | shown (see --summary-limit option of linkgit:git-submodule[1]). Please note |
362 | that the summary output from the status command will be suppressed for all | |
363 | submodules when `diff.ignoreSubmodules` is set to 'all' or only for those | |
364 | submodules where `submodule.<name>.ignore=all`. To also view the summary for | |
365 | ignored submodules you can either use the --ignore-submodules=dirty command | |
366 | line option or the 'git submodule summary' command, which shows a similar | |
367 | output but does not honor these settings. | |
ac8d5afc | 368 | |
56ae8df5 | 369 | SEE ALSO |
cedb8d5d | 370 | -------- |
5162e697 | 371 | linkgit:gitignore[5] |
31fcd63c | 372 | |
3f971fc4 JH |
373 | GIT |
374 | --- | |
9e1f0a85 | 375 | Part of the linkgit:git[1] suite |