Re: Confusion about diffing branches

From: Theodore Tso <tytso@mit.edu>
Date: Aug 27, 2007, 20:29 UTC
Message-ID: <20070827202949.GA3951@thunk.org>
In-Reply-To: <7vmywczyfp.fsf@gitster.siamese.dyndns.org>

On Mon, Aug 27, 2007 at 10:20:42AM -0700, Junio C Hamano wrote:

> If you wanted to, you could:
> 
> 	$ git format-patch a a

Umm.... dare I ask why this works, or how someone would be expected to know this? Or is the answer, "Meditate deeply on builtin-log.c, grasshopper"? :-)

Show 6 quoted lines

> might have been better.  It is (1) too late to change now, and
> (2) for too small or perhaps negative a gain.
> 
> The reason why I say (2) is because _I_ think it is far more
> common and frequent to want to get "patches the other guy does
> not have" than "everything since nothingness up to this point".

I agree, "patches the other guy does not have" is usually the more common desired result. The problem is that it breaks the regularity of git's command line parsing, which is particularly painful given that users are told to read the man page for git-rev-list and git-rev-parse in order to understand all of the many, many options that might be valid. The fact that the man pages expect the user to do this kinda implies that there is a regularity and orthogonality to git's command structure --- which there is, mostly --- which makes the git-format-patch "hack" that much more surprising.

So it's just one of those things which is surprising to someone who hasn't been fingers deep in the guts of the git implementation for years and years. I think it took me a good hour or two of searching before I was able to even figure out how the special case for git-format-patch was getting implemented; it certainly wasn't well documented in the code last year when I went searching to figure out what the !@#@? was going on.

Show 7 quoted lines

> Oops.  I think I have a solution.
> 
> 	$ git format-patch a a
> 
> does not do _ROOT_ commit.  So you have to say
> 
> 	$ git format-patch --root a a

Wow, I had no idea that --root would even be accepted by git-format-patch. It's not mentioned in the documentation, and a grep of Documentation/*.txt shows that --root is only mentioned in the man pages for git-blame, git-fsck, and git-diff-tree. I assume it's the latter which is getting used here, but there isn't even a mention in the git-format-patch man page that options from git-diff-tree might be applicable.

I presume this is another, "meditate deeply on builtin-log.c and revision.c, and understand that they implement many diverse builtin commands, grasshopper" situation....

Show 8 quoted lines

> for the above example to work.  Why not tweak the option parser
> so that:
> 
> 	$ git format-patch --root a
> 
> to do what you want?  Without --root and with a single positive
> commit, it can keep doing the traditional "what I did since I
> forked from that guy's history".

That seems to make a lot of sense; given the fact that the current behaivor does make sense and is convenient, the big complaints were always (1) not documenting clearly that this was an exception which might be surprising (i.e., hanging a latern[1] on it), and (2) that there wasn't a way to do the alternate expected behavior. --root handles the second, and an explanation in the man page saying that yes, this is a little non-standard wrt to git-rev-list, but it's convenient, and let the user know that he should just give us a pass on it the non-orthoganlity.

					- Ted

[1] 
Daniel:   The mountain... blows up?
Martin:   No possible hope for survival! Cool huh? I just wrote it 
	  based on what's going on with the gate. I love it when art 
	  imitates life. 
Mitchell: Hang on. We're alive in the next scene.
Martin:   Oh, I just haven't fixed that part yet. I'm thinking I can 
	  back-sell it and say you were beamed out at the last second.
Daniel:   "Beamed out?"
Martin:   Sure, why not?
Teal'c:   Is that not too convenient?
Martin:   Not if you hang a lantern on it.
Daniel:   What's that?
Martin:   It's a writer's term. Another character points out how
	  convenient it is. Doctor Levant can say, "Wow, that was
	  great timing."  That way, the audience knows I intended for
	  it to be convenient, and we move on.