docs: update status --porcelain format
[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 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.
39
40 -u[<mode>]::
41 --untracked-files[=<mode>]::
42 Show untracked files.
43 +
44 The mode parameter is optional (defaults to 'all'), and is used to
45 specify the handling of untracked files; when -u is not used, the
46 default is 'normal', i.e. show untracked files and directories.
47 +
48 The possible options are:
49 +
50 - 'no' - Show no untracked files
51 - 'normal' - Shows untracked files and directories
52 - 'all' - Also shows individual files in untracked directories.
53 +
54 The default can be changed using the status.showUntrackedFiles
55 configuration variable documented in linkgit:git-config[1].
56
57 --ignore-submodules[=<when>]::
58 Ignore changes to submodules when looking for changes. <when> can be
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
63 'ignore' option in linkgit:git-config[1] or linkgit:gitmodules[5]. When
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
72 -z::
73 Terminate entries with NUL, instead of LF. This implies
74 the `--porcelain` output format if no other format is given.
75
76
77 OUTPUT
78 ------
79 The output from this command is designed to be used as a commit
80 template comment, and all the output lines are prefixed with '#'.
81 The default, long format, is designed to be human readable,
82 verbose and descriptive. Its contents and format are subject to change
83 at any time.
84
85 The paths mentioned in the output, unlike many other git commands, are
86 made relative to the current directory if you are working in a
87 subdirectory (this is on purpose, to help cutting and pasting). See
88 the status.relativePaths config option below.
89
90 Short Format
91 ~~~~~~~~~~~~
92
93 In the short-format, the status of each path is shown as
94
95 XY PATH1 -> PATH2
96
97 where `PATH1` is the path in the `HEAD`, and the ` -> PATH2` part is
98 shown only when `PATH1` corresponds to a different path in the
99 index/worktree (i.e. the file is renamed). The 'XY' is a two-letter
100 status code.
101
102 The fields (including the `->`) are separated from each other by a
103 single space. If a filename contains whitespace or other nonprintable
104 characters, that field will be quoted in the manner of a C string
105 literal: surrounded by ASCII double quote (34) characters, and with
106 interior special characters backslash-escaped.
107
108 For paths with merge conflicts, `X` and 'Y' show the modification
109 states of each side of the merge. For paths that do not have merge
110 conflicts, `X` shows the status of the index, and `Y` shows the status
111 of the work tree. For untracked paths, `XY` are `??`. Other status
112 codes 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
122 Ignored files are not listed.
123
124 X Y Meaning
125 -------------------------------------------------
126 [MD] not updated
127 M [ MD] updated in index
128 A [ MD] added to index
129 D [ M] deleted from index
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
147 If -b is used the short-format status is preceded by a line
148
149 ## branchname tracking info
150
151 Porcelain Format
152 ~~~~~~~~~~~~~~~~
153
154 The porcelain format is similar to the short format, but is guaranteed
155 not to change in a backwards-incompatible way between git versions or
156 based on user configuration. This makes it ideal for parsing by scripts.
157 The description of the short format above also describes the porcelain
158 format, with a few exceptions:
159
160 1. The user's color.status configuration is not respected; color will
161 always be off.
162
163 2. The user's status.relativePaths configuration is not respected; paths
164 shown will always be relative to the repository root.
165
166 There is also an alternate -z format recommended for machine parsing. In
167 that format, the status field is the same, but some other things
168 change. First, the '->' is omitted from rename entries and the field
169 order is reversed (e.g 'from -> to' becomes 'to from'). Second, a NUL
170 (ASCII 0) follows each filename, replacing space as a field separator
171 and the terminating newline (but a space still separates the status
172 field from the first filename). Third, filenames containing special
173 characters are not specially formatted; no quoting or
174 backslash-escaping is performed. Fourth, there is no branch line.
175
176 CONFIGURATION
177 -------------
178
179 The command honors `color.status` (or `status.color` -- they
180 mean the same thing and the latter is kept for backward
181 compatibility) and `color.status.<slot>` configuration variables
182 to colorize its output.
183
184 If the config variable `status.relativePaths` is set to false, then all
185 paths shown are relative to the repository root, not to the current
186 directory.
187
188 If `status.submodulesummary` is set to a non zero number or true (identical
189 to -1 or an unlimited number), the submodule summary will be enabled for
190 the long format and a summary of commits for modified submodules will be
191 shown (see --summary-limit option of linkgit:git-submodule[1]).
192
193 SEE ALSO
194 --------
195 linkgit:gitignore[5]
196
197 GIT
198 ---
199 Part of the linkgit:git[1] suite