From 043b5cd93859d25fa39cbbefd64e62d143b9baf0 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Thu, 26 May 2011 22:31:11 -0400 Subject: docs: minor grammar fixes to git-status Signed-off-by: Jeff King Signed-off-by: Junio C Hamano 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. -- cgit v0.10.2-6-g49f6 From fc17df03442185a23583b959fc70617b69ceb0ca Mon Sep 17 00:00:00 2001 From: Jeff King Date: Thu, 26 May 2011 22:31:51 -0400 Subject: 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 Signed-off-by: Junio C Hamano 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[]:: --untracked-files[=]:: @@ -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 -- cgit v0.10.2-6-g49f6 From 715e716a1b5bc1bc71715286e7a10b7e0c3188e8 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Thu, 26 May 2011 22:32:41 -0400 Subject: docs: make sure literal "->" isn't converted to arrow 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 Signed-off-by: Junio C Hamano 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 -- cgit v0.10.2-6-g49f6 From 62b42d348754231609e07912ac42da6b112008ef Mon Sep 17 00:00:00 2001 From: Jeff King Date: Thu, 26 May 2011 22:33:15 -0400 Subject: docs: fix some antique example output 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 Signed-off-by: Junio C Hamano 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: -- cgit v0.10.2-6-g49f6