--- Em qui, 11/8/11, Junio C Hamano <gitster@xxxxxxxxx> escreveu:
> Luiz Ramos <luizzramos@xxxxxxxxxxxx>
> writes:
>
> > Given this, I'd suggest to change the inline
> documentation of git-diff (git help diff). In the version of
> my machine (1.7.4.4), it's like that:
> >
> > (snip)
> > ...
> > git diff [--options]
> <commit> [--] [<path>...]
> > This form is
> to view the changes you have in your working tree
> > relative to
> the named <commit>. You can use HEAD to compare it
> with
> > the latest
> commit, or a branch name to compare with the tip of a
> > different
> branch.
> > ...
>
> Strictly speaking, "the changes you have in your working
> tree" may be what
> is confusing. Your working tree does _not_ have "changes";
> it only has
> "contents". Changes are perceived only if you compare it
> with something
> else, as their _difference_.
>
> This operation compares "the contents of tracked files in
> your working
> tree" with "the contents recorded in the named
> <commit>"---the result of
> this comparison comparison matches what humans perceive as
> "changes".
>
> So perhaps updating the first sentence with:
>
> Compare the contents of tracked files in
> your working tree with
> what is recorded in the named
> <commit>.
>
Yes, agreed. This sentence seems to embed the right information in a more concise manner.
> would be all that is necessary. I didn't bother to look but
> I suspect we
> have a simlar description for "git diff [--options] [--]
> [<path>...]"
> form, and it should be updated in a similar way (the only
> difference is
> that it compares "with what is recorded in the index").
>
In my version (1.7.4.4):
(snip)
...
git diff [--options] [--] [<path>...]
This form is to view the changes you made relative to the index (staging area for the next commit). In other words, the differences are what you could tell git to further add to
the index but you still haven't. You can stage these changes by using git-add(1).
...
(snip)
And yes, if an untracked new file is in the working directory, it is not reported. Again, the words "changes" and "differences" seem to be confusing in this case as new files may be seen as "changes" or "differences" for an operator not used to git.
Luiz
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html