docs: update status --porcelain format
The --porcelain format was originally identical to the --short format, but designed to be stable as the short format changed. Since this was written, the short format picked up a few incompatible niceties, but this description was never changed. Let's mention the differences. While we're at it, let's add some sub-section headings to make the "output" section a little easier to navigate. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jeff King committed
May 26, 2011 at 22:31 UTC
fc17df03442185a23583b959fc70617b69ceb0ca
1 file changed
+23
-4
Documentation/git-status.txt
+23
-4
@@ -32,9 +32,10 @@ OPTIONS
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.
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>]::
@@ -86,6 +87,9 @@ 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
@@ -144,7 +148,22 @@ If -b is used the short-format status is preceded by a line
148
149
## branchname tracking info
150
147
-There is an alternate -z format recommended for machine parsing. In
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