From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 29 Oct 2009 06:24:30 GMT
Subject: Re: [PATCH] git-rebase -i: improve usage message
Message-ID: <7vtyxiafa9.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1256774549-8191-1-git-send-email-brian.ewins@gmail.com>

Brian Ewins <brian.ewins@gmail.com> 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.