git-diff-index man page

git-diff-index man page

[Albert Netymk]

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

Re: git-diff-index man page

[Junio C Hamano]

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.

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

Re: git-diff-index man page

[Albert Netymk]

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

Re: git-diff-index man page

[Junio C Hamano]

Albert Netymk <albertnetymk@gmail.com> writes:

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

Re: git-diff-index man page

[Eric Sunshine]

On Mon, May 20, 2013 at 1:01 AM, Junio C Hamano <gitster@pobox.com> wrote:
> 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>

Re: git-diff-index man page

[Jonathan Nieder]

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

Re: git-diff-index man page

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Thanks and hope that helps,
> Jonathan

Thanks, the result reads much better, I think.

Albert?


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