threads / discuss / 33864

git-diff-index man page

Subject: git-diff-index man page

## tl;dr

7 messages between May 18, 2013 and May 20, 2013.

replies: 6people: 4as markdown or json

Albert Netymk· May 18, 2013, 16:26 UTC · lore
Hello,

The man page of git-diff-index: http://git-scm.com/docs/git-diff-index states that `git-diff-index - Compares content and mode of blobs between the index and repository`.

However, in fact this command compares between files on disk and repository by default. It's explained clearly in here: http://git-scm.com/docs/gitdiffcore

Maybe the man page could be updated to reflect this in NAME section: `git-diff-index - Compares content and mode of blobs between files on disk and repository or between the index and repository`

In DESCRIPTION section: `Compares the content and mode of the blobs found via a tree object with the content of the files on disk by default, and could be compared with index only using cached option. ...`

-- Best Regards

Yours faithfully Albert Netymk

Junio C Hamano· May 19, 2013, 07:46 UTC · re: Albert Netymk · lore

Re: git-diff-index man page

Albert Netymk <albertnetymk@gmail.com> writes:
Show 15 quoted lines
> Hello,
>
> The man page of git-diff-index:
> http://git-scm.com/docs/git-diff-index
> states that
> `git-diff-index - Compares content and mode of blobs between the index
> and repository`.
>
> However, in fact this command compares between files on disk and
> repository by default. It's explained clearly in here:
> http://git-scm.com/docs/gitdiffcore
>
> Maybe the man page could be updated to reflect this in NAME section:
> `git-diff-index - Compares content and mode of blobs between files on
> disk and repository or between the index and repository`
Surely; we need to keep it fit on a single line, though.
> In DESCRIPTION section:
> `Compares the content and mode of the blobs found via a tree object
> with the content of the files on disk by default, and could be
> compared with index only using cached option. ...`

Yes, mentioning both mode is a good change. The above exact text may give a false impression (with that "by default") that it is somehow more preferrable to compare tree with working tree through the index, and only weirdos would use "--cached" to compare tree and the index, though.

Patches welcome.  Thanks.
Albert Netymk· May 19, 2013, 20:23 UTC · re: Junio C Hamano · lore

Re: git-diff-index man page

On Sun, May 19, 2013 at 9:46 AM, Junio C Hamano <gitster@pobox.com> wrote:
Show 19 quoted lines
> Albert Netymk <albertnetymk@gmail.com> writes:
>
>> Hello,
>>
>> The man page of git-diff-index:
>> http://git-scm.com/docs/git-diff-index
>> states that
>> `git-diff-index - Compares content and mode of blobs between the index
>> and repository`.
>>
>> However, in fact this command compares between files on disk and
>> repository by default. It's explained clearly in here:
>> http://git-scm.com/docs/gitdiffcore
>>
>> Maybe the man page could be updated to reflect this in NAME section:
>> `git-diff-index - Compares content and mode of blobs between files on
>> disk and repository or between the index and repository`
>
> Surely; we need to keep it fit on a single line, though.

Here's one excerpt from man page of git-diff-index: (this is how one line looks like) Compares the content and mode of the blobs found via a tree object with the content of the current index and, optionally ignoring the stat state of `git-diff-index - Compares content and mode of blobs between files on disk and repository or between the index and repository`

It seems that this one is not longer than one line.
Show 11 quoted lines
>
>> In DESCRIPTION section:
>> `Compares the content and mode of the blobs found via a tree object
>> with the content of the files on disk by default, and could be
>> compared with index only using cached option. ...`
>
> Yes, mentioning both mode is a good change.  The above exact text
> may give a false impression (with that "by default") that it is
> somehow more preferrable to compare tree with working tree through
> the index, and only weirdos would use "--cached" to compare tree and
> the index, though.

I am a little confused about "somehow more preferrable to compare tree with working tree through the index". My understanding is that if `--cached` is not used, the content of index is ignore. This command does direct comparison between repository and working tree. I didn't realized that the above statement implies any subjective preference. If so, provide one objective description, please.

> Patches welcome.  Thanks.

I don't know how to submit patches. Besides, the only part that is a bit misleading is the "NAME" and "DESCRIPTION" section. Could someone just update them?

-- Best Regards

Yours faithfully Albert Netymk

Junio C Hamano· May 20, 2013, 05:01 UTC · re: Albert Netymk · lore

Re: git-diff-index man page

Albert Netymk <albertnetymk@gmail.com> writes:
Show 29 quoted lines
> On Sun, May 19, 2013 at 9:46 AM, Junio C Hamano <gitster@pobox.com> wrote:
>> Albert Netymk <albertnetymk@gmail.com> writes:
>>
>>> Hello,
>>>
>>> The man page of git-diff-index:
>>> http://git-scm.com/docs/git-diff-index
>>> states that
>>> `git-diff-index - Compares content and mode of blobs between the index
>>> and repository`.
>>> However, in fact this command compares between files on disk and
>>> repository by default. It's explained clearly in here:
>>> http://git-scm.com/docs/gitdiffcore
>>>
>>> Maybe the man page could be updated to reflect this in NAME section:
>>> `git-diff-index - Compares content and mode of blobs between files on
>>> disk and repository or between the index and repository`
>>
>> Surely; we need to keep it fit on a single line, though.
>
> Here's one excerpt from man page of git-diff-index: (this is how one
> line looks like)
> Compares the content and mode of the blobs found via a tree object
> with the content of the current index and, optionally ignoring the
> stat state of
> `git-diff-index - Compares content and mode of blobs between files on
> disk and repository or between the index and repository`
>
> It seems that this one is not longer than one line.
I would say
	git-diff-index - Compare a tree and the working tree or the index

should be sufficiently short and much more accurate than the current text.

> I don't know how to submit patches. Besides, the only part that is a
> bit misleading is the "NAME" and "DESCRIPTION" section. Could someone
> just update them?
How about something like this?
-- >8 --
Subject: [PATCH] Documentation/diff-index: mention two modes of operation

"diff-index" can be used to compare a tree with the tracked working tree files (when used without the --index option), or with the index (when used with the --index option).

The text however did not say anything about the comparision with the working tree at all. Fix this.

Reported-by: Albert Netymk <albertnetymk@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-diff-index.txt | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)
diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt
index c0b7c58..58308e1 100644
--- 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
 
 
 SYNOPSIS
@@ -13,11 +13,12 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-Compares the content and mode of the blobs found via a tree
-object with the content of the current index and, optionally
-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.
+
+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.
 
 OPTIONS
 -------
Eric Sunshine· May 20, 2013, 05:40 UTC · re: Junio C Hamano · lore

Re: git-diff-index man page

On Mon, May 20, 2013 at 1:01 AM, Junio C Hamano <gitster@pobox.com> wrote:
Show 7 quoted lines
> Subject: [PATCH] Documentation/diff-index: mention two modes of operation
>
> "diff-index" can be used to compare a tree with the tracked working
> tree files (when used without the --index option), or with the index
> (when used with the --index option).
>
> The text however did not say anything about the comparision with the
s/comparision/comparison/
> working tree at all.  Fix this.
>
> Reported-by: Albert Netymk <albertnetymk@gmail.com>
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jonathan Nieder· May 20, 2013, 06:27 UTC · re: Junio C Hamano · lore

Re: git-diff-index man page

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
 -------
Junio C Hamano· May 20, 2013, 22:48 UTC · re: Jonathan Nieder · lore

Re: git-diff-index man page

Jonathan Nieder <jrnieder@gmail.com> writes:
> Thanks and hope that helps,
> Jonathan
Thanks, the result reads much better, I think.
Albert?
Show 31 quoted lines
> 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
>  -------

← back to recent threads