Re: [PATCH] git-rebase -i: improve usage message

Brian Ewins [off-list ref] writes:

The usage message was confusing as it implied that interactive
mode was optional but the default. Change the message to more
appropriately report usage when the -i flag is supplied.
In addition, use the same division into 3 command formats as
the man page.

I agree; if "git rebase--interactive -h" were asked, "-i is always used"
might be a correct thing to say, but nobody will get the message that way.
Instead, "git rebase --nonsense -i" and "git rebase -i --nonsense" will be
the most common way for users to see the message (also "git rebase -i -h").

The OPTIONS_SPEC in rebase--interactive is for the interactive mode and
for nothing else, so it may be a good idea to clearly say so at the
beginning.  The user experience perhaps should look like:

    $ git rebase -i -h
    Note: this help is only about the interactive mode;
    see 'git rebase -h' for help on non-interactive mode.

    usage: git rebase -i [<options>] [--] <upstream> [<branch>]
       or: git rebase -i (--continue|--abort|--skip)

    Available options are
    -v,--verbose          verbose output
    --onto <commit>       rebase onto given commit instead of <upstream>
    -p,--preserve-merges  try to recreate merges
    -i,--interactive      (always in effect in interactive mode)
    -m,--merge            (always in effect in interactive mode)

    Actions:
        --continue        continue the interrupted rebase session
        ...

By the way, I think the main "git rebase" help should be improved first
for this improvement to make sense.

 * Its first line "usage" is too long;

 * It only mentions [-i] in the first line but does not hint that the
   detailed help on interactive mode is available with "rebase -i -h".

The user experience perhaps should look like this:

    $ git rebase -h
    usage: git rebase [<options>] (<upstream>|--root) [<branch>]

    -i,--interactive  go interactive (see 'git rebase -i -h')
    -v,--verbose      verbose output
    ...

Also see

  http://thread.gmane.org/gmane.comp.version-control.git/129906/focus=130646

I agree with Peff that the first-line usage should just say <options> in general
and have a table of options and their descriptions.

Junio C Hamano wrote:

The OPTIONS_SPEC in rebase--interactive is for the interactive mode and
for nothing else, so it may be a good idea to clearly say so at the
beginning.  The user experience perhaps should look like:

    $ git rebase -i -h
    Note: this help is only about the interactive mode;
    see 'git rebase -h' for help on non-interactive mode.

    usage: git rebase -i [<options>] [--] <upstream> [<branch>]
       or: git rebase -i (--continue|--abort|--skip)

Nit-pick: the last line is not correct; the user does not have to
specify -i for git-rebase to figure out that an interactive rebase is
in progress.

(I agree with the rest though.)

-- 
Thomas Rast
trast@{inf,student}.ethz.ch