Re: [PATCH] Documentation: add a planning document for the next CLI revamp

[Theodore Tso <tytso@mit.edu>]

On Thu, Oct 30, 2008 at 03:43:21PM +0100, Pierre Habouzit wrote:
> 
> git format-patch origin/next.. works already. I'm used to the asymetric
> git format-patch origin/next syntax, and I would be sorry if it
> disappeared though, and I see no really good reason to get rid of it.

The reason why it annoys me is because I often what to cherry-pick a
single patch to send to someone, and so while "git show 332d2e78"
shows me the patch, but if I want to use git-send-email for that
particular patch, "git format-patch 332d2e78" doesn't DTRT.  I have to
type "git format-patch 332d2e78^..332d2e78" instead.  I've learned to
live with it, but it's annoying each time I have to do it.

More generally, the fact that the CLI has different ways the same set
of arguments can be decoded can be quite confusing.  The most obvious
way this turns up is to consider which set of commits are
displayed/formatted via these three commands:

   git format-patch 332d2e78
   git show 332d2e78
   git log -p 332d2e78

The first formats all patches that follow commit 332d2e78 (not
including commit 332d2e78), the second shows just commit 332d2e78, and
the last prints all commits starting at 332d2e78 and before it.

For many workflows, the default way a single commit-id is interpreted
makes a lot of sense.  But for a newcomer, it's very confusing.  I'm
not saying that we should collapse everything down to a single way of
doing things, but git format-patch is an exception, and I don't think
anything else actually works that way; looking at the man page makes
it clear that it treats its argument as a revision range EXCEPT when
only a single commit is specified.

It can be justified, and maybe it's convenient enough that this is one
of those places where tutorials should just explicitly call this out
as one of those exceptions that make sense given common workflows.
But just as English can be heard to learn because "though", "through",
"plough", "cough", and "tough" don't rhyme even though they look like
they should (even though native speakers have no problem with it),
similarly this is one of those inconsistencies that makes git hard to
learn.  

(And I get annoyed when I want to run git format-patch on a single
patch not at the tip of the tree; but if it's just me, I can write a
"git format-single-patch" wrapper script to get around it.)

     	      	       		     	    	 - Ted