[PATCH 2/4] docs: update status --porcelain format
- From
Jeff King <peff@peff.net>
- Date
- May 27, 2011, 02:31 UTC
- Message-ID
- <20110527023151.GB25362@sigill.intra.peff.net>
- In-Reply-To
- <30543.1305828072@plover.com>
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> --- Documentation/git-status.txt | 27 +++++++++++++++++++++++---- 1 files changed, 23 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt index 7702727..edacf6b 100644 --- a/Documentation/git-status.txt +++ b/Documentation/git-status.txt @@ -32,9 +32,10 @@ OPTIONS Show the branch and tracking info even in short-format. --porcelain:: - Give the output in a stable, easy-to-parse format for scripts. - Currently this is identical to --short output, but is guaranteed - not to change in the future, making it safe for scripts. + Give the output in an easy-to-parse format for scripts. + This is similar to the short output, but will remain stable + across git versions and regardless of user configuration. See + below for details. -u[<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 the status.relativePaths config option below. +Short Format +~~~~~~~~~~~~ + In the short-format, the status of each path is shown as XY PATH1 -> PATH2 @@ -144,7 +148,22 @@ If -b is used the short-format status is preceded by a line ## 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 change. First, the '->' is omitted from rename entries and the field order is reversed (e.g 'from -> to' becomes 'to from'). Second, a NUL
-- 1.7.4.5.26.g0c6a2