From: Jonathan Nieder <jrnieder@gmail.com>
Date: Thu, 20 Jan 2011 20:09:49 GMT
Subject: Re: [PATCH 1/2] rebase -i: reword in-editor documentation of "exec"
Message-ID: <20110120200949.GB11702@burratino>
In-Reply-To: <vpq39otrvmk.fsf@bauges.imag.fr>

Matthieu Moy wrote:
> Jonathan Nieder <jrnieder@gmail.com> writes:

>> -#  x <cmd>, exec <cmd> = Run a shell command <cmd>, and stop if it fails
>> +#  x, exec = run command using shell, and stop if it fails
>
> I don't think this is a good change to remove the <cmd> part. All
> other commands are used with
>
> <command> <sha1> <subject line>
>
> and I don't think the user would be able to guess that exec is
> different without a hint.
> 
> If the problem is the wording of the sentence that may imply that
> <cmd> should be the shell itself, then why not

Yes, sorry, I combined two problems into a single patch.  That was a
mistake.  The current cheat sheet says:

# Rebase 3f14246..a1d7e01 onto 3f14246
#
# Commands:
#  p, pick = use commit
#  r, reword = use commit, but edit the commit message
#  e, edit = use commit, but stop for amending
#  s, squash = use commit, but meld into previous commit
#  f, fixup = like "squash", but discard this commit's log message
#  x <cmd>, exec <cmd> = Run a shell command <cmd>, and stop if it fails
#
# If you remove a line here THAT COMMIT WILL BE LOST.
# However, if you remove everything, the rebase will be aborted.
#

This does not make it clear that the format of each line is

	<instruction> <commit id> <explanatory text that will be printed>

but the reader will probably infer that from the automatically
generated pick examples above.

What about the "exec" instruction?  By analogy, I might imagine that
the format of that line is

	exec <command> <explanatory text that will be printed>

So the "<cmd>" does not address that question for me.  It does succeed
in clarifying that "a shell command" does not mean an arbitrary shell
command but a user-specified one.

Meanwhile, it makes the cheat sheet harder to visually scan as a table

 i, instruction = action performed by instruction

Maybe "exec" should be explained outside this table?  For example,
maybe something along the lines of

	 x, exec = run an arbitrary command (see below)

	A line of the form "exec <command>" will run <command> using your
	shell and stop for investigation or amending if the command fails.

	If you remove a line here, THAT COMMIT WILL BE LOST.
	However, if you remove everything, the rebase will be aborted.