{"thread":{"id":"27409","subject":"Bug report : git-status manual fibs about semantics of --porcelain","startedAt":"2011-05-19T18:01:12Z","lastAt":"2011-05-27T05:16:33Z","messageCount":6,"participants":["Mark Jason Dominus","Jeff King","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"168239","messageId":"30543.1305828072@plover.com","threadId":"27409","inReplyTo":null,"subject":"Bug report : git-status manual fibs about semantics of --porcelain","fromName":"Mark Jason Dominus","fromEmail":"mjd@plover.com","sentAt":"2011-05-19T18:01:12Z","receivedAt":"2011-05-19T18:01:12Z","isPatch":false,"sender":{"key":"mjd@plover.com","avatar":"https://gravatar.com/avatar/a874d23a21a54fc9c5e9d91614219a150bd89c90c1cb0ef970e689f5b88c098b?d=mp&s=160"},"body":"\nThe 1.7.5.1 manual says:\n\n     --porcelain::\n    \tGive the output in a stable, easy-to-parse format for scripts.\n    \tCurrently this is identical to --short output, but is guaranteed\n    \tnot to change in the future, making it safe for scripts.\n\nHowever, this is not actually true.  --porcelain differs from --short\nin at least two ways, one of them significant.  \n\n--short is colorized when color.status = auto, while --porcelain is\nnot.\n\nMore importantly, --short reports file paths relative to the\ncurrent directory, while --porcelain reports file paths relative to\nthe root of the repository.\n\nAll of this was the case in 1.7.0.4 also, and presumably the versions\nin between.\n\nMark Jason Dominus \t  \t\t\t                 mjd@plover.com\n"},{"id":"168849","messageId":"20110527023111.GA25362@sigill.intra.peff.net","threadId":"27409","inReplyTo":"30543.1305828072@plover.com","subject":"[PATCH 1/4] docs: minor grammar fixes to git-status","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2011-05-27T02:31:11Z","receivedAt":"2011-05-27T02:31:11Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"\nSigned-off-by: Jeff King <peff@peff.net>\n---\nNoticed these while working on 2/4.\n\n Documentation/git-status.txt |    7 ++++---\n 1 files changed, 4 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex 00b699f..7702727 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -78,18 +78,19 @@ OUTPUT\n The output from this command is designed to be used as a commit\n template comment, and all the output lines are prefixed with '#'.\n The default, long format, is designed to be human readable,\n-verbose and descriptive.  They are subject to change in any time.\n+verbose and descriptive.  Its contents and format are subject to change\n+at any time.\n \n The paths mentioned in the output, unlike many other git commands, are\n made relative to the current directory if you are working in a\n subdirectory (this is on purpose, to help cutting and pasting). See\n the status.relativePaths config option below.\n \n-In short-format, the status of each path is shown as\n+In the short-format, the status of each path is shown as\n \n \tXY PATH1 -> PATH2\n \n-where `PATH1` is the path in the `HEAD`, and ` -> PATH2` part is\n+where `PATH1` is the path in the `HEAD`, and the ` -> PATH2` part is\n shown only when `PATH1` corresponds to a different path in the\n index/worktree (i.e. the file is renamed). The 'XY' is a two-letter\n status code.\n-- \n1.7.4.5.26.g0c6a2\n"},{"id":"168850","messageId":"20110527023151.GB25362@sigill.intra.peff.net","threadId":"27409","inReplyTo":"30543.1305828072@plover.com","subject":"[PATCH 2/4] docs: update status --porcelain format","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2011-05-27T02:31:51Z","receivedAt":"2011-05-27T02:31:51Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"The --porcelain format was originally identical to the\n--short format, but designed to be stable as the short\nformat changed. Since this was written, the short format\npicked up a few incompatible niceties, but this description\nwas never changed.\n\nLet's mention the differences. While we're at it, let's add\nsome sub-section headings to make the \"output\" section a\nlittle easier to navigate.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\n Documentation/git-status.txt |   27 +++++++++++++++++++++++----\n 1 files changed, 23 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex 7702727..edacf6b 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -32,9 +32,10 @@ OPTIONS\n \tShow the branch and tracking info even in short-format.\n \n --porcelain::\n-\tGive the output in a stable, easy-to-parse format for scripts.\n-\tCurrently this is identical to --short output, but is guaranteed\n-\tnot to change in the future, making it safe for scripts.\n+\tGive the output in an easy-to-parse format for scripts.\n+\tThis is similar to the short output, but will remain stable\n+\tacross git versions and regardless of user configuration. See\n+\tbelow for details.\n \n -u[<mode>]::\n --untracked-files[=<mode>]::\n@@ -86,6 +87,9 @@ made relative to the current directory if you are working in a\n subdirectory (this is on purpose, to help cutting and pasting). See\n the status.relativePaths config option below.\n \n+Short Format\n+~~~~~~~~~~~~\n+\n In the short-format, the status of each path is shown as\n \n \tXY PATH1 -> PATH2\n@@ -144,7 +148,22 @@ If -b is used the short-format status is preceded by a line\n \n ## branchname tracking info\n \n-There is an alternate -z format recommended for machine parsing.  In\n+Porcelain Format\n+~~~~~~~~~~~~~~~~\n+\n+The porcelain format is similar to the short format, but is guaranteed\n+not to change in a backwards-incompatible way between git versions or\n+based on user configuration. This makes it ideal for parsing by scripts.\n+The description of the short format above also describes the porcelain\n+format, with a few exceptions:\n+\n+1. The user's color.status configuration is not respected; color will\n+   always be off.\n+\n+2. The user's status.relativePaths configuration is not respected; paths\n+   shown will always be relative to the repository root.\n+\n+There is also an alternate -z format recommended for machine parsing. In\n that format, the status field is the same, but some other things\n change.  First, the '->' is omitted from rename entries and the field\n order is reversed (e.g 'from -> to' becomes 'to from'). Second, a NUL\n-- \n1.7.4.5.26.g0c6a2\n"},{"id":"168851","messageId":"20110527023241.GC25362@sigill.intra.peff.net","threadId":"27409","inReplyTo":"30543.1305828072@plover.com","subject":"[PATCH 3/4] docs: make sure literal \"->\" isn't converted to arrow","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2011-05-27T02:32:41Z","receivedAt":"2011-05-27T02:32:41Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"Recent versions of asciidoc will treat \"->\" as a\nsingle-glyph arrow symbol, unless it is inside a literal\ncode block. This is a problem if we are discussing literal\noutput and want to show the ASCII characters.\n\nOur usage falls into three categories:\n\n  1. Inside a code block. These can be left as-is.\n\n  2. Discussing literal output or code, but inside a\n     paragraph. This patch escapes these as \"\\->\".\n\n  3. Using the arrow as a symbolic element, such as \"use the\n     Edit->Account Settings menu\". In this case, the\n     arrow symbol is preferable, so we leave it as-is.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\nI noticed this while checking the output of my git-status.txt changes.\nNo idea when asciidoc started doing this (I am running 8.6.4 from debian\nunstable).\n\n Documentation/git-cvsserver.txt |    2 +-\n Documentation/git-status.txt    |    8 ++++----\n 2 files changed, 5 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt\nindex 88d814a..827bc98 100644\n--- a/Documentation/git-cvsserver.txt\n+++ b/Documentation/git-cvsserver.txt\n@@ -252,7 +252,7 @@ Configuring database backend\n \n 'git-cvsserver' uses the Perl DBI module. Please also read\n its documentation if changing these variables, especially\n-about `DBI->connect()`.\n+about `DBI\\->connect()`.\n \n gitcvs.dbname::\n \tDatabase name. The exact meaning depends on the\ndiff --git a/Documentation/git-status.txt b/Documentation/git-status.txt\nindex edacf6b..38cb741 100644\n--- a/Documentation/git-status.txt\n+++ b/Documentation/git-status.txt\n@@ -94,12 +94,12 @@ In the short-format, the status of each path is shown as\n \n \tXY PATH1 -> PATH2\n \n-where `PATH1` is the path in the `HEAD`, and the ` -> PATH2` part is\n+where `PATH1` is the path in the `HEAD`, and the ` \\-> PATH2` part is\n shown only when `PATH1` corresponds to a different path in the\n index/worktree (i.e. the file is renamed). The 'XY' is a two-letter\n status code.\n \n-The fields (including the `->`) are separated from each other by a\n+The fields (including the `\\->`) are separated from each other by a\n single space. If a filename contains whitespace or other nonprintable\n characters, that field will be quoted in the manner of a C string\n literal: surrounded by ASCII double quote (34) characters, and with\n@@ -165,8 +165,8 @@ format, with a few exceptions:\n \n There is also an alternate -z format recommended for machine parsing. In\n that format, the status field is the same, but some other things\n-change.  First, the '->' is omitted from rename entries and the field\n-order is reversed (e.g 'from -> to' becomes 'to from'). Second, a NUL\n+change.  First, the '\\->' is omitted from rename entries and the field\n+order is reversed (e.g 'from \\-> to' becomes 'to from'). Second, a NUL\n (ASCII 0) follows each filename, replacing space as a field separator\n and the terminating newline (but a space still separates the status\n field from the first filename).  Third, filenames containing special\n-- \n1.7.4.5.26.g0c6a2\n"},{"id":"168852","messageId":"20110527023315.GD25362@sigill.intra.peff.net","threadId":"27409","inReplyTo":"30543.1305828072@plover.com","subject":"[PATCH 4/4] docs: fix some antique example output","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2011-05-27T02:33:15Z","receivedAt":"2011-05-27T02:33:15Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"These diff-index and diff-tree sample outputs date back to\nthe first month of git's existence. The output format has\nchanged slightly since then, so let's have it match the\ncurrent output.\n\nSigned-off-by: Jeff King <peff@peff.net>\n---\nI just noticed these while auditing all of the \"->\" in the docs\ndirectory. I didn't read through the whole text to make sure there were\nno other inaccuracies, though.\n\n Documentation/git-diff-index.txt |    4 ++--\n Documentation/git-diff-tree.txt  |    4 ++--\n 2 files changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt\nindex 6d18486..2ea22ab 100644\n--- a/Documentation/git-diff-index.txt\n+++ b/Documentation/git-diff-index.txt\n@@ -96,8 +96,8 @@ show that. So let's say that you have edited `kernel/sched.c`, but\n have not actually done a 'git update-index' on it yet - there is no\n \"object\" associated with the new state, and you get:\n \n-  torvalds@ppc970:~/v2.6/linux> git diff-index HEAD\n-  *100644->100664 blob    7476bb......->000000......      kernel/sched.c\n+  torvalds@ppc970:~/v2.6/linux> git diff-index --abbrev HEAD\n+  :100644 100664 7476bb... 000000...      kernel/sched.c\n \n i.e., it shows that the tree has changed, and that `kernel/sched.c` has is\n not up-to-date and may contain new stuff. The all-zero sha1 means that to\ndiff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt\nindex 4e5f127..1439486 100644\n--- a/Documentation/git-diff-tree.txt\n+++ b/Documentation/git-diff-tree.txt\n@@ -138,8 +138,8 @@ so it can be used to name subdirectories.\n \n An example of normal usage is:\n \n-  torvalds@ppc970:~/git> git diff-tree 5319e4......\n-  *100664->100664 blob    ac348b.......->a01513.......      git-fsck-objects.c\n+  torvalds@ppc970:~/git> git diff-tree --abbrev 5319e4\n+  :100664 100664 ac348b... a01513...\tgit-fsck-objects.c\n \n which tells you that the last commit changed just one file (it's from\n this one:\n-- \n1.7.4.5.26.g0c6a2\n"},{"id":"168853","messageId":"7vr57ku3im.fsf@alter.siamese.dyndns.org","threadId":"27409","inReplyTo":"20110527023315.GD25362@sigill.intra.peff.net","subject":"Re: [PATCH 4/4] docs: fix some antique example output","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-05-27T05:16:33Z","receivedAt":"2011-05-27T05:16:33Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Thanks. All patches look good.\n"}]}