diff options
| author | Jeff King <peff@peff.net> | 2011-05-26 22:31:51 -0400 |
|---|---|---|
| committer | Junio C Hamano <gitster@pobox.com> | 2011-05-26 22:15:36 -0700 |
| commit | fc17df03442185a23583b959fc70617b69ceb0ca (patch) | |
| tree | 335bb302aa1033eb1f2c48ab124df4ef5956ae46 | |
| parent | 043b5cd93859d25fa39cbbefd64e62d143b9baf0 (diff) | |
| download | git-fc17df03442185a23583b959fc70617b69ceb0ca.tar.gz git-fc17df03442185a23583b959fc70617b69ceb0ca.tar.xz | |
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>
| -rw-r--r-- | 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 77027276b..edacf6b93 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 |