Merge branch 'master' of git://git.kernel.org/pub/scm/git/git
[git/jnareb-git.git] / Documentation / git-status.txt
blob9046df98a03fe11a203f06d79be0128309a201c5
1 git-status(1)
2 =============
4 NAME
5 ----
6 git-status - Show the working tree status
9 SYNOPSIS
10 --------
11 [verse]
12 'git status' [<options>...] [--] [<pathspec>...]
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`.
24 OPTIONS
25 -------
27 -s::
28 --short::
29         Give the output in the short-format.
31 -b::
32 --branch::
33         Show the branch and tracking info even in short-format.
35 --porcelain::
36         Give the output in an easy-to-parse format for scripts.
37         This is similar to the short output, but will remain stable
38         across Git versions and regardless of user configuration. See
39         below for details.
41 --long::
42         Give the output in the long-format. This is the default.
44 -u[<mode>]::
45 --untracked-files[=<mode>]::
46         Show untracked files.
48 The mode parameter is optional (defaults to 'all'), and is used to
49 specify the handling of untracked files.
51 The possible options are:
53         - 'no'     - Show no untracked files.
54         - 'normal' - Shows untracked files and directories.
55         - 'all'    - Also shows individual files in untracked directories.
57 When `-u` option is not used, untracked files and directories are
58 shown (i.e. the same as specifying `normal`), to help you avoid
59 forgetting to add newly created files.  Because it takes extra work
60 to find untracked files in the filesystem, this mode may take some
61 time in a large working tree.  You can use `no` to have `git status`
62 return more quickly without showing untracked files.
64 The default can be changed using the status.showUntrackedFiles
65 configuration variable documented in linkgit:git-config[1].
67 --ignore-submodules[=<when>]::
68         Ignore changes to submodules when looking for changes. <when> can be
69         either "none", "untracked", "dirty" or "all", which is the default.
70         Using "none" will consider the submodule modified when it either contains
71         untracked or modified files or its HEAD differs from the commit recorded
72         in the superproject and can be used to override any settings of the
73         'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When
74         "untracked" is used submodules are not considered dirty when they only
75         contain untracked content (but they are still scanned for modified
76         content). Using "dirty" ignores all changes to the work tree of submodules,
77         only changes to the commits stored in the superproject are shown (this was
78         the behavior before 1.7.0). Using "all" hides all changes to submodules
79         (and suppresses the output of submodule summaries when the config option
80         `status.submodulesummary` is set).
82 --ignored::
83         Show ignored files as well.
85 -z::
86         Terminate entries with NUL, instead of LF.  This implies
87         the `--porcelain` output format if no other format is given.
89 --column[=<options>]::
90 --no-column::
91         Display untracked files in columns. See configuration variable
92         column.status for option syntax.`--column` and `--no-column`
93         without options are equivalent to 'always' and 'never'
94         respectively.
97 OUTPUT
98 ------
99 The output from this command is designed to be used as a commit
100 template comment, and all the output lines are prefixed with '#'.
101 The default, long format, is designed to be human readable,
102 verbose and descriptive.  Its contents and format are subject to change
103 at any time.
105 The paths mentioned in the output, unlike many other Git commands, are
106 made relative to the current directory if you are working in a
107 subdirectory (this is on purpose, to help cutting and pasting). See
108 the status.relativePaths config option below.
110 Short Format
111 ~~~~~~~~~~~~
113 In the short-format, the status of each path is shown as
115         XY PATH1 -> PATH2
117 where `PATH1` is the path in the `HEAD`, and the " `-> PATH2`" part is
118 shown only when `PATH1` corresponds to a different path in the
119 index/worktree (i.e. the file is renamed). The 'XY' is a two-letter
120 status code.
122 The fields (including the `->`) are separated from each other by a
123 single space. If a filename contains whitespace or other nonprintable
124 characters, that field will be quoted in the manner of a C string
125 literal: surrounded by ASCII double quote (34) characters, and with
126 interior special characters backslash-escaped.
128 For paths with merge conflicts, `X` and 'Y' show the modification
129 states of each side of the merge. For paths that do not have merge
130 conflicts, `X` shows the status of the index, and `Y` shows the status
131 of the work tree.  For untracked paths, `XY` are `??`.  Other status
132 codes can be interpreted as follows:
134 * ' ' = unmodified
135 * 'M' = modified
136 * 'A' = added
137 * 'D' = deleted
138 * 'R' = renamed
139 * 'C' = copied
140 * 'U' = updated but unmerged
142 Ignored files are not listed, unless `--ignored` option is in effect,
143 in which case `XY` are `!!`.
145     X          Y     Meaning
146     -------------------------------------------------
147               [MD]   not updated
148     M        [ MD]   updated in index
149     A        [ MD]   added to index
150     D         [ M]   deleted from index
151     R        [ MD]   renamed in index
152     C        [ MD]   copied in index
153     [MARC]           index and work tree matches
154     [ MARC]     M    work tree changed since index
155     [ MARC]     D    deleted in work tree
156     -------------------------------------------------
157     D           D    unmerged, both deleted
158     A           U    unmerged, added by us
159     U           D    unmerged, deleted by them
160     U           A    unmerged, added by them
161     D           U    unmerged, deleted by us
162     A           A    unmerged, both added
163     U           U    unmerged, both modified
164     -------------------------------------------------
165     ?           ?    untracked
166     !           !    ignored
167     -------------------------------------------------
169 If -b is used the short-format status is preceded by a line
171 ## branchname tracking info
173 Porcelain Format
174 ~~~~~~~~~~~~~~~~
176 The porcelain format is similar to the short format, but is guaranteed
177 not to change in a backwards-incompatible way between Git versions or
178 based on user configuration. This makes it ideal for parsing by scripts.
179 The description of the short format above also describes the porcelain
180 format, with a few exceptions:
182 1. The user's color.status configuration is not respected; color will
183    always be off.
185 2. The user's status.relativePaths configuration is not respected; paths
186    shown will always be relative to the repository root.
188 There is also an alternate -z format recommended for machine parsing. In
189 that format, the status field is the same, but some other things
190 change.  First, the '\->' is omitted from rename entries and the field
191 order is reversed (e.g 'from \-> to' becomes 'to from'). Second, a NUL
192 (ASCII 0) follows each filename, replacing space as a field separator
193 and the terminating newline (but a space still separates the status
194 field from the first filename).  Third, filenames containing special
195 characters are not specially formatted; no quoting or
196 backslash-escaping is performed.
198 CONFIGURATION
199 -------------
201 The command honors `color.status` (or `status.color` -- they
202 mean the same thing and the latter is kept for backward
203 compatibility) and `color.status.<slot>` configuration variables
204 to colorize its output.
206 If the config variable `status.relativePaths` is set to false, then all
207 paths shown are relative to the repository root, not to the current
208 directory.
210 If `status.submodulesummary` is set to a non zero number or true (identical
211 to -1 or an unlimited number), the submodule summary will be enabled for
212 the long format and a summary of commits for modified submodules will be
213 shown (see --summary-limit option of linkgit:git-submodule[1]).
215 SEE ALSO
216 --------
217 linkgit:gitignore[5]
221 Part of the linkgit:git[1] suite