Re: git-diff-index man page

From: Junio C Hamano <gitster@pobox.com>
Date: May 20, 2013, 05:01 UTC
Message-ID: <7vr4h2w8gv.fsf@alter.siamese.dyndns.org>
In-Reply-To: <CAKEGsXRry_=BuPRPK_syW7_W+_Bh+A1bB9U5YC02=a+Z+SHv1w@mail.gmail.com>

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