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

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

[Brian Ewins]

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.

Signed-off-by: Brian Ewins <brian.ewins@gmail.com>
---
 git-rebase--interactive.sh |   13 +++++++------
 1 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/git-rebase--interactive.sh b/git-rebase--interactive.sh
index a1879e3..b988c30 100755
--- a/git-rebase--interactive.sh
+++ b/git-rebase--interactive.sh
@@ -12,22 +12,23 @@
 
 OPTIONS_KEEPDASHDASH=
 OPTIONS_SPEC="\
-git-rebase [-i] [options] [--] <upstream> [<branch>]
-git-rebase [-i] (--continue | --abort | --skip)
+git rebase -i [options] [--onto <newbase>] [--] <upstream> [<branch>]
+git rebase -i [options] --onto <newbase> --root [--] [<branch>]
+git rebase (--continue | --abort | --skip)
 --
  Available options are
 v,verbose          display a diffstat of what changed upstream
 onto=              rebase onto given branch instead of upstream
 p,preserve-merges  try to recreate merges instead of ignoring them
 s,strategy=        use the given merge strategy
-m,merge            always used (no-op)
-i,interactive      always used (no-op)
+i,interactive      interactively edit commits. Implies -m.
+m,merge            use merging strategies
+no-verify          override pre-rebase hook from stopping the operation
+root               rebase all reachable commmits up to the root(s)
  Actions:
 continue           continue rebasing process
 abort              abort rebasing process and restore original branch
 skip               skip current patch and continue rebasing process
-no-verify          override pre-rebase hook from stopping the operation
-root               rebase all reachable commmits up to the root(s)
 "
 
 . git-sh-setup
-- 
1.6.5

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

[Junio C Hamano]

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.

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

[Thomas Rast]

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