Submodules: Add the new "ignore" config option for diff and status
[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--------
9e4b7ab6 11'git status' [<options>...] [--] [<pathspec>...]
3f971fc4
JH
12
13DESCRIPTION
14-----------
2099bca9
JK
15Displays paths that have differences between the index file and the
16current HEAD commit, paths that have differences between the working
17tree and the index file, and paths in the working tree that are not
5162e697 18tracked by git (and are not ignored by linkgit:gitignore[5]). The first
2099bca9 19are what you _would_ commit by running `git commit`; the second and
0b444cdb 20third are what you _could_ commit by running 'git add' before running
2099bca9 21`git commit`.
3f971fc4 22
9e4b7ab6
JH
23OPTIONS
24-------
25
26-s::
27--short::
28 Give the output in the short-format.
29
46077fa5
MG
30-b::
31--branch::
32 Show the branch and tracking info even in short-format.
33
6f157871
JK
34--porcelain::
35 Give the output in a stable, easy-to-parse format for scripts.
36 Currently this is identical to --short output, but is guaranteed
37 not to change in the future, making it safe for scripts.
38
9e4b7ab6
JH
39-u[<mode>]::
40--untracked-files[=<mode>]::
41 Show untracked files (Default: 'all').
42+
43The mode parameter is optional, and is used to specify
44the handling of untracked files. The possible options are:
45+
46--
47 - 'no' - Show no untracked files
48 - 'normal' - Shows untracked files and directories
49 - 'all' - Also shows individual files in untracked directories.
50--
51+
52See linkgit:git-config[1] for configuration variable
53used to change the default for when the option is not
54specified.
55
46a958b3
JL
56--ignore-submodules[=<when>]::
57 Ignore changes to submodules when looking for changes. <when> can be
aee9c7d6
JL
58 either "none", "untracked", "dirty" or "all", which is the default.
59 Using "none" will consider the submodule modified when it either contains
60 untracked or modified files or its HEAD differs from the commit recorded
61 in the superproject and can be used to override any settings of the
62 'ignore' option in linkgit:git-config[1]. When
46a958b3
JL
63 "untracked" is used submodules are not considered dirty when they only
64 contain untracked content (but they are still scanned for modified
65 content). Using "dirty" ignores all changes to the work tree of submodules,
66 only changes to the commits stored in the superproject are shown (this was
67 the behavior before 1.7.0). Using "all" hides all changes to submodules
68 (and suppresses the output of submodule summaries when the config option
69 `status.submodulesummary` is set).
70
9e4b7ab6 71-z::
6f157871
JK
72 Terminate entries with NUL, instead of LF. This implies
73 the `--porcelain` output format if no other format is given.
2099bca9 74
3f971fc4
JH
75
76OUTPUT
77------
78The output from this command is designed to be used as a commit
2099bca9 79template comment, and all the output lines are prefixed with '#'.
9e4b7ab6
JH
80The default, long format, is designed to be human readable,
81verbose and descriptive. They are subject to change in any time.
3f971fc4 82
c7860507 83The paths mentioned in the output, unlike many other git commands, are
2099bca9 84made relative to the current directory if you are working in a
46f721c8
JK
85subdirectory (this is on purpose, to help cutting and pasting). See
86the status.relativePaths config option below.
c7860507 87
9e4b7ab6
JH
88In short-format, the status of each path is shown as
89
90 XY PATH1 -> PATH2
91
92where `PATH1` is the path in the `HEAD`, and ` -> PATH2` part is
93shown only when `PATH1` corresponds to a different path in the
e92e9cd3
ER
94index/worktree (i.e. the file is renamed). The 'XY' is a two-letter
95status code.
96
97The fields (including the `->`) are separated from each other by a
98single space. If a filename contains whitespace or other nonprintable
99characters, that field will be quoted in the manner of a C string
100literal: surrounded by ASCII double quote (34) characters, and with
101interior special characters backslash-escaped.
102
103For paths with merge conflicts, `X` and 'Y' show the modification
104states of each side of the merge. For paths that do not have merge
105conflicts, `X` shows the status of the index, and `Y` shows the status
106of the work tree. For untracked paths, `XY` are `??`. Other status
107codes can be interpreted as follows:
108
109* ' ' = unmodified
110* 'M' = modified
111* 'A' = added
112* 'D' = deleted
113* 'R' = renamed
114* 'C' = copied
115* 'U' = updated but unmerged
116
117Ignored files are not listed.
9e4b7ab6
JH
118
119 X Y Meaning
120 -------------------------------------------------
121 [MD] not updated
122 M [ MD] updated in index
123 A [ MD] added to index
e92e9cd3 124 D [ M] deleted from index
9e4b7ab6
JH
125 R [ MD] renamed in index
126 C [ MD] copied in index
127 [MARC] index and work tree matches
128 [ MARC] M work tree changed since index
129 [ MARC] D deleted in work tree
130 -------------------------------------------------
131 D D unmerged, both deleted
132 A U unmerged, added by us
133 U D unmerged, deleted by them
134 U A unmerged, added by them
135 D U unmerged, deleted by us
136 A A unmerged, both added
137 U U unmerged, both modified
138 -------------------------------------------------
139 ? ? untracked
140 -------------------------------------------------
141
46077fa5
MG
142If -b is used the short-format status is preceded by a line
143
144## branchname tracking info
145
e92e9cd3
ER
146There is an alternate -z format recommended for machine parsing. In
147that format, the status field is the same, but some other things
148change. First, the '->' is omitted from rename entries and the field
149order is reversed (e.g 'from -> to' becomes 'to from'). Second, a NUL
150(ASCII 0) follows each filename, replacing space as a field separator
151and the terminating newline (but a space still separates the status
152field from the first filename). Third, filenames containing special
153characters are not specially formatted; no quoting or
46077fa5 154backslash-escaping is performed. Fourth, there is no branch line.
3f971fc4 155
31fcd63c
JH
156CONFIGURATION
157-------------
158
159The command honors `color.status` (or `status.color` -- they
160mean the same thing and the latter is kept for backward
161compatibility) and `color.status.<slot>` configuration variables
162to colorize its output.
163
46f721c8 164If the config variable `status.relativePaths` is set to false, then all
482a6c10
MG
165paths shown are relative to the repository root, not to the current
166directory.
46f721c8 167
ac8d5afc 168If `status.submodulesummary` is set to a non zero number or true (identical
46b77a6b
JK
169to -1 or an unlimited number), the submodule summary will be enabled for
170the long format and a summary of commits for modified submodules will be
171shown (see --summary-limit option of linkgit:git-submodule[1]).
ac8d5afc 172
56ae8df5 173SEE ALSO
cedb8d5d 174--------
5162e697 175linkgit:gitignore[5]
31fcd63c 176
3f971fc4
JH
177Author
178------
9e4b7ab6 179Written by Junio C Hamano <gitster@pobox.com>.
3f971fc4
JH
180
181Documentation
182--------------
183Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
184
185GIT
186---
9e1f0a85 187Part of the linkgit:git[1] suite