Re: git-diff-index man page

[Jonathan Nieder <jrnieder@gmail.com>]

Junio C Hamano wrote:

> --- 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

[...]
> @@ -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.

> -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
 -------