Re: git-diff-index man page

From: Albert Netymk <albertnetymk@gmail.com>
Date: May 19, 2013, 20:23 UTC
Message-ID: <CAKEGsXRry_=BuPRPK_syW7_W+_Bh+A1bB9U5YC02=a+Z+SHv1w@mail.gmail.com>
In-Reply-To: <7vhahzza2v.fsf@alter.siamese.dyndns.org>

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