About git-diff

About git-diff

[Luiz Ramos]

Hello,

just a doubt, but it can also be a bug.

Suppose there is a project stored in git, and it has two branches. In the branch b1, there is a single file, file_1. In the branch b2, there is a single file file_2.

Suppose also I am using branch b1 above (that is, "git checkout b1" was previously run), but the file file_2 was left in the working directory along with file_1.

If I run:

$ git diff --cached b2 ./

The results will point that the file file_1 is added, as it is in the index and not in the tree b2. It will also point that file file_2 is removed, as it is listed in the tree b2, but not in the index. No doubts here.

If I run:

$ git diff b2 ./

that is, the "non-cached" version, it will show the same results. This is confusing IMHO, because the git-diff manual suggests that invocation should render the difference between the named tree contents and the working directory. In the working directory, only to recall, file_1 and file_2 are both present and with good versions. In my understanding, the command should report that file_1 is in excess in the working directory, relative to b2, and report nothing about file_2, as it is in the same version as the sample in the tree b2.

This doesn't seem to be the same thing git-diff-index manual states, however. The manual gets more deep into the details, and it's not so easy to understand it unless one knows a lot of the inner commands, which does not apply to me. In my basic reading, it seems that behind the scenes, git-diff-index is what is run in this case, and the fact that file_2 is not in the tree associated to b1 is a relevant thing in this case. So, the index seem to matter, and if I try to do it, a previous "git update-index" should be done.

I may be wrong, but as a user, I'd like to have the non-cached command version comparing tree and working directory, as the manual of git-diff suggests, eventually helped by the index, but not limited to it. Because if I'd like to compare with index, I would try it using --cached instead.

Please accept my apologies if there is some newbie mistake here.

Thanks,

Luiz Ramos
São Paulo - Brazil

Re: About git-diff

[Andreas Schwab]

Luiz Ramos <luizzramos@yahoo.com.br> writes:

> If I run:
>
> $ git diff b2 ./
>
> that is, the "non-cached" version, it will show the same results. This is
> confusing IMHO, because the git-diff manual suggests that invocation
> should render the difference between the named tree contents and the
> working directory. In the working directory, only to recall, file_1 and
> file_2 are both present and with good versions. In my understanding, the
> command should report that file_1 is in excess in the working directory,
> relative to b2, and report nothing about file_2, as it is in the same
> version as the sample in the tree b2.

Since file_2 is not tracked in the current branch, its existence in the
directory is ignored.

> This doesn't seem to be the same thing git-diff-index manual states,
> however. The manual gets more deep into the details, and it's not so easy
> to understand it unless one knows a lot of the inner commands, which does
> not apply to me. In my basic reading, it seems that behind the scenes,
> git-diff-index is what is run in this case, and the fact that file_2 is
> not in the tree associated to b1 is a relevant thing in this case. So, the
> index seem to matter, and if I try to do it, a previous "git update-index"
> should be done.

It's not the index, but the current tree that matters:

           show me the differences between HEAD and the currently checked out
           tree - index contents _and_ files that aren't up-to-date

Note that it talks about "files that aren't up-to-date".  Thus untracked
files are not considered.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: About git-diff

[Luiz Ramos]

--- Em qua, 10/8/11, Andreas Schwab <schwab@linux-m68k.org> escreveu:

> De: Andreas Schwab <schwab@linux-m68k.org>
> Assunto: Re: About git-diff
> Para: "Luiz Ramos" <luizzramos@yahoo.com.br>
> Cc: git@vger.kernel.org
> Data: Quarta-feira, 10 de Agosto de 2011, 14:01
> Luiz Ramos <luizzramos@yahoo.com.br>
> writes:
> 
> > If I run:
> >
> > $ git diff b2 ./
> >
> > that is, the "non-cached" version, it will show the
> same results. This is
> > confusing IMHO, because the git-diff manual suggests
> that invocation
> > should render the difference between the named tree
> contents and the
> > working directory. In the working directory, only to
> recall, file_1 and
> > file_2 are both present and with good versions. In my
> understanding, the
> > command should report that file_1 is in excess in the
> working directory,
> > relative to b2, and report nothing about file_2, as it
> is in the same
> > version as the sample in the tree b2.
> 
> Since file_2 is not tracked in the current branch, its
> existence in the
> directory is ignored.
> 
> > This doesn't seem to be the same thing git-diff-index
> manual states,
> > however. The manual gets more deep into the details,
> and it's not so easy
> > to understand it unless one knows a lot of the inner
> commands, which does
> > not apply to me. In my basic reading, it seems that
> behind the scenes,
> > git-diff-index is what is run in this case, and the
> fact that file_2 is
> > not in the tree associated to b1 is a relevant thing
> in this case. So, the
> > index seem to matter, and if I try to do it, a
> previous "git update-index"
> > should be done.
> 
> It's not the index, but the current tree that matters:
> 
>            show me the
> differences between HEAD and the currently checked out
>            tree - index
> contents _and_ files that aren't up-to-date
> 
> Note that it talks about "files that aren't
> up-to-date".  Thus untracked
> files are not considered.
> 

Ok, understood.

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.
...
(snip)

A unadvised reader could understand that the comparison is between <commit> and the working directory, as if <commit> was the current branch, plainly stated. In fact, there is no mention to the current branch, or to the files being tracked or not, except for the option of mentioning HEAD as the <commit> to be taken into account.

If you'd accept a small contribution of yours truly, here's amy suggestion for this text:

...
       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. Note, however, that files untracked in the 
           current branch are handled as if they are missing in the working
           directory. Check out git-diff-index documentation for further
           information.
...

It's not in the patch format, but if you'd like the suggestion, there is no problem in re-sending it as a formatted patch.

Thanks,

Luiz


> Andreas.
> 
> -- 
> Andreas Schwab, schwab@linux-m68k.org
> GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3
> 44D5 214B 8276 4ED5
> "And now for something completely different."
> 

Re: About git-diff

[Junio C Hamano]

Luiz Ramos <luizzramos@yahoo.com.br> 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>.

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

Re: About git-diff

[Luiz Ramos]

--- Em qui, 11/8/11, Junio C Hamano <gitster@pobox.com> escreveu:

> Luiz Ramos <luizzramos@yahoo.com.br>
> 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