Re: Updated Kernel Hacker's guide to git

["Francis Moreau" <francis.moro@gmail.com>]

Linus Torvalds wrote:
>
> In short, for git diff (and ONLY) git diff, all of these are the same:
>
> 	git diff a..b
> 	git diff a b
> 	git diff b ^a
>

I think this part is really confusing. For a new comer, saying that:

	git diff a b == git diff a..b

is really not intuitive. Maybe just because adding a new symbol ".."
in git diff command line means (for me) that we're doing a special
diff. I would never thought by my own that ".." means a simple "to".

> [ ADDITIONALLY git diff _also_ has a magic special case of
>
> 	git diff a b ^c
>
>   which actually means the same as "git diff c..a" (and "b" is
>   totally ignored). That may sound strange, but it's because the
>   expression "a...b" means "b a --not $(git-merge-base a b)", and so what
>   you actually WANT is that if you do
>
> 	git diff a...b
>
>   you should get "diff from merge-base to b", so when "a...b" expands to
>   "b a ^merge-base", then git understands that if it gets that stange
>   command line with THREE commits, and one of them is negated, you really
>   wanted the diff from the negated one to the first one ]
>
> It basically all boils down to:
>
> 	"git diff" is special
>

but this very special part of git diff is also not documented at all
when reading the manual of git-diff... Maybe it can be reached by
others manuals ?

> exactly because unlike almost ALL other git commands, "git diff" does not
> work on a _list_ of commits, it only works on two end-points. That means
> that the "list operations" actually end up meaning something else for git
> diff than they do for "git log" and friends.
>

I think I got your point now: git-diff only works on two end-points.


Why not making it less special as follow:

	git diff a b
	git diff b ^a

These two diff commands are the same. They do a diff between a and b
end-points (maybe commits is better there since we don't add one more
keyword). It's similar to diff command. For me it's quite intuitive.

	git diff a..b

Ok now the command syntax is more special (maybe simply because
traditional diff() does not have a similar syntax, it's really
specific to git). "git log" and friends have a similar syntax and they
do work on a list of commits. For consistency sake, make this commad
works on commit list too. Therefore this command would end up doing
exactly the same thing like "git diff a...b"

	git diff a...b

No more need of this special syntax.


What do you think ?

thanks
-- 
Francis