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

From: Theodore Tso <tytso@mit.edu>
Date: Oct 30, 2008, 16:30 UTC
Message-ID: <20081030163056.GA8899@mit.edu>
In-Reply-To: <20081030144321.GF24098@artemis.corp>

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