Submodules: Add the new "ignore" config option for diff and status
[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 'git status' [<options>...] [--] [<pathspec>...]
12
13 DESCRIPTION
14 -----------
15 Displays paths that have differences between the index file and the
16 current HEAD commit, paths that have differences between the working
17 tree and the index file, and paths in the working tree that are not
18 tracked by git (and are not ignored by linkgit:gitignore[5]). The first
19 are what you _would_ commit by running `git commit`; the second and
20 third are what you _could_ commit by running 'git add' before running
21 `git commit`.
22
23 OPTIONS
24 -------
25
26 -s::
27 --short::
28 Give the output in the short-format.
29
30 -b::
31 --branch::
32 Show the branch and tracking info even in short-format.
33
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
39 -u[<mode>]::
40 --untracked-files[=<mode>]::
41 Show untracked files (Default: 'all').
42 +
43 The mode parameter is optional, and is used to specify
44 the 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 +
52 See linkgit:git-config[1] for configuration variable
53 used to change the default for when the option is not
54 specified.
55
56 --ignore-submodules[=<when>]::
57 Ignore changes to submodules when looking for changes. <when> can be
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
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
71 -z::
72 Terminate entries with NUL, instead of LF. This implies
73 the `--porcelain` output format if no other format is given.
74
75
76 OUTPUT
77 ------
78 The output from this command is designed to be used as a commit
79 template comment, and all the output lines are prefixed with '#'.
80 The default, long format, is designed to be human readable,
81 verbose and descriptive. They are subject to change in any time.
82
83 The paths mentioned in the output, unlike many other git commands, are
84 made relative to the current directory if you are working in a
85 subdirectory (this is on purpose, to help cutting and pasting). See
86 the status.relativePaths config option below.
87
88 In short-format, the status of each path is shown as
89
90 XY PATH1 -> PATH2
91
92 where `PATH1` is the path in the `HEAD`, and ` -> PATH2` part is
93 shown only when `PATH1` corresponds to a different path in the
94 index/worktree (i.e. the file is renamed). The 'XY' is a two-letter
95 status code.
96
97 The fields (including the `->`) are separated from each other by a
98 single space. If a filename contains whitespace or other nonprintable
99 characters, that field will be quoted in the manner of a C string
100 literal: surrounded by ASCII double quote (34) characters, and with
101 interior special characters backslash-escaped.
102
103 For paths with merge conflicts, `X` and 'Y' show the modification
104 states of each side of the merge. For paths that do not have merge
105 conflicts, `X` shows the status of the index, and `Y` shows the status
106 of the work tree. For untracked paths, `XY` are `??`. Other status
107 codes 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
117 Ignored files are not listed.
118
119 X Y Meaning
120 -------------------------------------------------
121 [MD] not updated
122 M [ MD] updated in index
123 A [ MD] added to index
124 D [ M] deleted from index
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
142 If -b is used the short-format status is preceded by a line
143
144 ## branchname tracking info
145
146 There is an alternate -z format recommended for machine parsing. In
147 that format, the status field is the same, but some other things
148 change. First, the '->' is omitted from rename entries and the field
149 order is reversed (e.g 'from -> to' becomes 'to from'). Second, a NUL
150 (ASCII 0) follows each filename, replacing space as a field separator
151 and the terminating newline (but a space still separates the status
152 field from the first filename). Third, filenames containing special
153 characters are not specially formatted; no quoting or
154 backslash-escaping is performed. Fourth, there is no branch line.
155
156 CONFIGURATION
157 -------------
158
159 The command honors `color.status` (or `status.color` -- they
160 mean the same thing and the latter is kept for backward
161 compatibility) and `color.status.<slot>` configuration variables
162 to colorize its output.
163
164 If the config variable `status.relativePaths` is set to false, then all
165 paths shown are relative to the repository root, not to the current
166 directory.
167
168 If `status.submodulesummary` is set to a non zero number or true (identical
169 to -1 or an unlimited number), the submodule summary will be enabled for
170 the long format and a summary of commits for modified submodules will be
171 shown (see --summary-limit option of linkgit:git-submodule[1]).
172
173 SEE ALSO
174 --------
175 linkgit:gitignore[5]
176
177 Author
178 ------
179 Written by Junio C Hamano <gitster@pobox.com>.
180
181 Documentation
182 --------------
183 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
184
185 GIT
186 ---
187 Part of the linkgit:git[1] suite