Re: [PATCH 1/2] rebase -i: reword in-editor documentation of "exec"

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Jan 20, 2011, 20:09 UTC
Message-ID: <20110120200949.GB11702@burratino>
In-Reply-To: <vpq39otrvmk.fsf@bauges.imag.fr>

Matthieu Moy wrote:

> Jonathan Nieder <jrnieder@gmail.com> writes:

Show 13 quoted lines

>> -#  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.