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

[Theodore Tso <tytso@mit.edu>]

On Sat, Nov 01, 2008 at 11:08:06PM -0700, Junio C Hamano wrote:
> > (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.)
> 
> Huh?  I am so used to "git format-patch -1 HEAD" (or "332d2e78") that I am
> very surprised.

Well, the explanation is that "-<n>" isn't in the SYNPOSIS section of
'git format-patch', and so I never knew you could do it that way.  A
new user of git has to paw through approximately 50 options in the
OPTIONS section of the man page before finding "-<n>"; and somehow
I've always missed it.  I'd suggest adding an explicit mention of -<n>
to the DESCRIPTION section, perhaps in the paragraph:

   A single commit, when interpreted as a <revision range> expression,
   means "everything that leads to that commit", but if you write git
   format-patch <commit>, the previous rule applies to that command
   line and you do not get "everything since the beginning of the
   time". If you want to format everything since project inception to
   one commit, say "git format-patch --root <commit>" to make it clear
   that it is the latter case.

Adding the sentence:

   If you want to format a single commit, you can do this via 
   "git format-patch -1 <commit>" or the more esoteric and perl-ish,
   "git format-patch <commit>^!"

might be helpful.

						- Ted