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