Re: git-diff-index man page

From: Jonathan Nieder <jrnieder@gmail.com>
Date: May 20, 2013, 06:27 UTC
Message-ID: <20130520062743.GA2919@elie.Belkin>
In-Reply-To: <7vr4h2w8gv.fsf@alter.siamese.dyndns.org>

Junio C Hamano wrote:

Show 8 quoted lines

> --- a/Documentation/git-diff-index.txt
> +++ b/Documentation/git-diff-index.txt
> @@ -3,7 +3,7 @@ git-diff-index(1)
>  
>  NAME
>  ----
> -git-diff-index - Compares content and mode of blobs between the index and repository
> +git-diff-index - Compare a tree and the working tree or the index

Looks good.  I think it scans better with the second "the" left out:

	git diff-index - Compare a tree to the working tree or index

[...]

Show 6 quoted lines

> @@ -13,11 +13,12 @@ SYNOPSIS
>  
>  DESCRIPTION
>  -----------
> -Compares the content and mode of the blobs found via a tree
> +Compare the content and mode of the blobs found in a tree object

I think this s/Compares/Compare/ is a regression: traditionally the DESCRIPTION sections of manpages describe what a command does in the present indicative ("When paths are specified, compares only those named paths"), freeing up the imperative for cases where it is useful to instruct the user about what to do.

The s/via/in/ looks fine.

> -object with the content of the current index and, optionally
> +with the corresponding tracked file in the working tree, or with the

Since they are being compared to blobs, "file" should be "files" here.

Show 6 quoted lines

> -ignoring the stat state of the file on disk.  When paths are
> -specified, compares only those named paths.  Otherwise all
> -entries in the index are compared.
> +corresponding paths in the index.  When paths are specified,
> +compares only those named paths.  Otherwise all entries in the index
> +are compared.

The <path> parameters to git diff-index are pathspecs and not literal paths.

This should say somewhere that this only looks at paths in the index and that untracked files are ignored. Perhaps something as simple as s/entries in the index/tracked files/ would do the trick.

Thanks and hope that helps, Jonathan

diff --git i/Documentation/git-diff-index.txt w/Documentation/git-diff-index.txt
index 58308e15..a86cf62e 100644
--- i/Documentation/git-diff-index.txt
+++ w/Documentation/git-diff-index.txt
@@ -3,7 +3,7 @@ git-diff-index(1)
 
 NAME
 ----
-git-diff-index - Compare a tree and the working tree or the index
+git-diff-index - Compare a tree to the working tree or index
 
 
 SYNOPSIS
@@ -13,12 +13,11 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-
-Compare the content and mode of the blobs found in a tree object
-with the corresponding tracked file in the working tree, or with the
-corresponding paths in the index.  When paths are specified,
-compares only those named paths.  Otherwise all entries in the index
-are compared.
+Compares the content and mode of the blobs found in a tree object
+with the corresponding tracked files in the working tree, or with the
+corresponding paths in the index.  When <path> arguments are present,
+compares only paths matching those patterns.  Otherwise all tracked
+files are compared.
 
 OPTIONS
 -------