* Bug report : git-status manual fibs about semantics of --porcelain
@ 2011-05-19 18:01 Mark Jason Dominus
2011-05-27 2:31 ` [PATCH 1/4] docs: minor grammar fixes to git-status Jeff King
` (3 more replies)
0 siblings, 4 replies; 6+ messages in thread
From: Mark Jason Dominus @ 2011-05-19 18:01 UTC (permalink / raw)
To: git
The 1.7.5.1 manual says:
--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.
However, this is not actually true. --porcelain differs from --short
in at least two ways, one of them significant.
--short is colorized when color.status = auto, while --porcelain is
not.
More importantly, --short reports file paths relative to the
current directory, while --porcelain reports file paths relative to
the root of the repository.
All of this was the case in 1.7.0.4 also, and presumably the versions
in between.
Mark Jason Dominus mjd@plover.com
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH 1/4] docs: minor grammar fixes to git-status
2011-05-19 18:01 Bug report : git-status manual fibs about semantics of --porcelain Mark Jason Dominus
@ 2011-05-27 2:31 ` Jeff King
2011-05-27 2:31 ` [PATCH 2/4] docs: update status --porcelain format Jeff King
` (2 subsequent siblings)
3 siblings, 0 replies; 6+ messages in thread
From: Jeff King @ 2011-05-27 2:31 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git
Signed-off-by: Jeff King <peff@peff.net>
---
Noticed these while working on 2/4.
Documentation/git-status.txt | 7 ++++---
1 files changed, 4 insertions(+), 3 deletions(-)
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index 00b699f..7702727 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -78,18 +78,19 @@ OUTPUT
The output from this command is designed to be used as a commit
template comment, and all the output lines are prefixed with '#'.
The default, long format, is designed to be human readable,
-verbose and descriptive. They are subject to change in any time.
+verbose and descriptive. Its contents and format are subject to change
+at any time.
The paths mentioned in the output, unlike many other git commands, are
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.
-In 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
-where `PATH1` is the path in the `HEAD`, and ` -> PATH2` part is
+where `PATH1` is the path in the `HEAD`, and the ` -> PATH2` part is
shown only when `PATH1` corresponds to a different path in the
index/worktree (i.e. the file is renamed). The 'XY' is a two-letter
status code.
--
1.7.4.5.26.g0c6a2
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH 2/4] docs: update status --porcelain format
2011-05-19 18:01 Bug report : git-status manual fibs about semantics of --porcelain Mark Jason Dominus
2011-05-27 2:31 ` [PATCH 1/4] docs: minor grammar fixes to git-status Jeff King
@ 2011-05-27 2:31 ` Jeff King
2011-05-27 2:32 ` [PATCH 3/4] docs: make sure literal "->" isn't converted to arrow Jeff King
2011-05-27 2:33 ` [PATCH 4/4] docs: fix some antique example output Jeff King
3 siblings, 0 replies; 6+ messages in thread
From: Jeff King @ 2011-05-27 2:31 UTC (permalink / raw)
To: Junio C Hamano; +Cc: Mark Jason Dominus, git
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
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH 3/4] docs: make sure literal "->" isn't converted to arrow
2011-05-19 18:01 Bug report : git-status manual fibs about semantics of --porcelain Mark Jason Dominus
2011-05-27 2:31 ` [PATCH 1/4] docs: minor grammar fixes to git-status Jeff King
2011-05-27 2:31 ` [PATCH 2/4] docs: update status --porcelain format Jeff King
@ 2011-05-27 2:32 ` Jeff King
2011-05-27 2:33 ` [PATCH 4/4] docs: fix some antique example output Jeff King
3 siblings, 0 replies; 6+ messages in thread
From: Jeff King @ 2011-05-27 2:32 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git
Recent versions of asciidoc will treat "->" as a
single-glyph arrow symbol, unless it is inside a literal
code block. This is a problem if we are discussing literal
output and want to show the ASCII characters.
Our usage falls into three categories:
1. Inside a code block. These can be left as-is.
2. Discussing literal output or code, but inside a
paragraph. This patch escapes these as "\->".
3. Using the arrow as a symbolic element, such as "use the
Edit->Account Settings menu". In this case, the
arrow symbol is preferable, so we leave it as-is.
Signed-off-by: Jeff King <peff@peff.net>
---
I noticed this while checking the output of my git-status.txt changes.
No idea when asciidoc started doing this (I am running 8.6.4 from debian
unstable).
Documentation/git-cvsserver.txt | 2 +-
Documentation/git-status.txt | 8 ++++----
2 files changed, 5 insertions(+), 5 deletions(-)
diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt
index 88d814a..827bc98 100644
--- a/Documentation/git-cvsserver.txt
+++ b/Documentation/git-cvsserver.txt
@@ -252,7 +252,7 @@ Configuring database backend
'git-cvsserver' uses the Perl DBI module. Please also read
its documentation if changing these variables, especially
-about `DBI->connect()`.
+about `DBI\->connect()`.
gitcvs.dbname::
Database name. The exact meaning depends on the
diff --git a/Documentation/git-status.txt b/Documentation/git-status.txt
index edacf6b..38cb741 100644
--- a/Documentation/git-status.txt
+++ b/Documentation/git-status.txt
@@ -94,12 +94,12 @@ In the short-format, the status of each path is shown as
XY PATH1 -> PATH2
-where `PATH1` is the path in the `HEAD`, and the ` -> PATH2` part is
+where `PATH1` is the path in the `HEAD`, and the ` \-> PATH2` part is
shown only when `PATH1` corresponds to a different path in the
index/worktree (i.e. the file is renamed). The 'XY' is a two-letter
status code.
-The fields (including the `->`) are separated from each other by a
+The fields (including the `\->`) are separated from each other by a
single space. If a filename contains whitespace or other nonprintable
characters, that field will be quoted in the manner of a C string
literal: surrounded by ASCII double quote (34) characters, and with
@@ -165,8 +165,8 @@ format, with a few exceptions:
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
+change. First, the '\->' is omitted from rename entries and the field
+order is reversed (e.g 'from \-> to' becomes 'to from'). Second, a NUL
(ASCII 0) follows each filename, replacing space as a field separator
and the terminating newline (but a space still separates the status
field from the first filename). Third, filenames containing special
--
1.7.4.5.26.g0c6a2
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH 4/4] docs: fix some antique example output
2011-05-19 18:01 Bug report : git-status manual fibs about semantics of --porcelain Mark Jason Dominus
` (2 preceding siblings ...)
2011-05-27 2:32 ` [PATCH 3/4] docs: make sure literal "->" isn't converted to arrow Jeff King
@ 2011-05-27 2:33 ` Jeff King
2011-05-27 5:16 ` Junio C Hamano
3 siblings, 1 reply; 6+ messages in thread
From: Jeff King @ 2011-05-27 2:33 UTC (permalink / raw)
To: Junio C Hamano; +Cc: git
These diff-index and diff-tree sample outputs date back to
the first month of git's existence. The output format has
changed slightly since then, so let's have it match the
current output.
Signed-off-by: Jeff King <peff@peff.net>
---
I just noticed these while auditing all of the "->" in the docs
directory. I didn't read through the whole text to make sure there were
no other inaccuracies, though.
Documentation/git-diff-index.txt | 4 ++--
Documentation/git-diff-tree.txt | 4 ++--
2 files changed, 4 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt
index 6d18486..2ea22ab 100644
--- a/Documentation/git-diff-index.txt
+++ b/Documentation/git-diff-index.txt
@@ -96,8 +96,8 @@ show that. So let's say that you have edited `kernel/sched.c`, but
have not actually done a 'git update-index' on it yet - there is no
"object" associated with the new state, and you get:
- torvalds@ppc970:~/v2.6/linux> git diff-index HEAD
- *100644->100664 blob 7476bb......->000000...... kernel/sched.c
+ torvalds@ppc970:~/v2.6/linux> git diff-index --abbrev HEAD
+ :100644 100664 7476bb... 000000... kernel/sched.c
i.e., it shows that the tree has changed, and that `kernel/sched.c` has is
not up-to-date and may contain new stuff. The all-zero sha1 means that to
diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
index 4e5f127..1439486 100644
--- a/Documentation/git-diff-tree.txt
+++ b/Documentation/git-diff-tree.txt
@@ -138,8 +138,8 @@ so it can be used to name subdirectories.
An example of normal usage is:
- torvalds@ppc970:~/git> git diff-tree 5319e4......
- *100664->100664 blob ac348b.......->a01513....... git-fsck-objects.c
+ torvalds@ppc970:~/git> git diff-tree --abbrev 5319e4
+ :100664 100664 ac348b... a01513... git-fsck-objects.c
which tells you that the last commit changed just one file (it's from
this one:
--
1.7.4.5.26.g0c6a2
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH 4/4] docs: fix some antique example output
2011-05-27 2:33 ` [PATCH 4/4] docs: fix some antique example output Jeff King
@ 2011-05-27 5:16 ` Junio C Hamano
0 siblings, 0 replies; 6+ messages in thread
From: Junio C Hamano @ 2011-05-27 5:16 UTC (permalink / raw)
To: Jeff King; +Cc: Junio C Hamano, git
Thanks. All patches look good.
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2011-05-27 5:16 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2011-05-19 18:01 Bug report : git-status manual fibs about semantics of --porcelain Mark Jason Dominus
2011-05-27 2:31 ` [PATCH 1/4] docs: minor grammar fixes to git-status Jeff King
2011-05-27 2:31 ` [PATCH 2/4] docs: update status --porcelain format Jeff King
2011-05-27 2:32 ` [PATCH 3/4] docs: make sure literal "->" isn't converted to arrow Jeff King
2011-05-27 2:33 ` [PATCH 4/4] docs: fix some antique example output Jeff King
2011-05-27 5:16 ` Junio C Hamano
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.