undef/git-commit-vandalism
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: update status --porcelain format

Browse Source 
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>
This commit is contained in:
Jeff King 2011-05-26 22:31:51 -04:00 committed by Junio C Hamano
parent 043b5cd938
commit fc17df0344
1 changed files with 23 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
Documentation/git-status.txt
View File

@ -32,9 +32,10 @@ OPTIONS
Show the branch and tracking info even in short-format. Show the branch and tracking info even in short-format.
--porcelain:: --porcelain::
Give the output in a stable, easy-to-parse format for scripts. Give the output in an easy-to-parse format for scripts.
Currently this is identical to --short output, but is guaranteed This is similar to the short output, but will remain stable
not to change in the future, making it safe for scripts. across git versions and regardless of user configuration. See
below for details.
-u[<mode>]:: -u[<mode>]::
--untracked-files[=<mode>]:: --untracked-files[=<mode>]::
@ -86,6 +87,9 @@ made relative to the current directory if you are working in a
subdirectory (this is on purpose, to help cutting and pasting). See subdirectory (this is on purpose, to help cutting and pasting). See
the status.relativePaths config option below. the status.relativePaths config option below.
Short Format
~~~~~~~~~~~~
In the short-format, the status of each path is shown as In the short-format, the status of each path is shown as
XY PATH1 -> PATH2 XY PATH1 -> PATH2
@ -144,7 +148,22 @@ If -b is used the short-format status is preceded by a line
## branchname tracking info ## branchname tracking info
There is an alternate -z format recommended for machine parsing. In Porcelain Format
~~~~~~~~~~~~~~~~
The porcelain format is similar to the short format, but is guaranteed
not to change in a backwards-incompatible way between git versions or
based on user configuration. This makes it ideal for parsing by scripts.
The description of the short format above also describes the porcelain
format, with a few exceptions:
1. The user's color.status configuration is not respected; color will
always be off.
2. The user's status.relativePaths configuration is not respected; paths
shown will always be relative to the repository root.
There is also an alternate -z format recommended for machine parsing. In
that format, the status field is the same, but some other things that format, the status field is the same, but some other things
change. First, the '->' is omitted from rename entries and the field change. First, the '->' is omitted from rename entries and the field
order is reversed (e.g 'from -> to' becomes 'to from'). Second, a NUL order is reversed (e.g 'from -> to' becomes 'to from'). Second, a NUL