threads / patch / 21412

patchgit-rebase -i: improve usage message

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

## tl;dr

3 messages between Oct 29, 2009 and Oct 29, 2009. Diffs are folded; open one to read it.

replies: 2people: 3as markdown or json

Brian Ewins· Oct 29, 2009, 00:02 UTC · lore

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(-)
Show changes to git-rebase--interactive.sh +7 −6
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
Junio C Hamano· Oct 29, 2009, 06:24 UTC · re: Brian Ewins · lore

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

Brian Ewins <brian.ewins@gmail.com> writes:
Show 5 quoted lines
> 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.

Thomas Rast· Oct 29, 2009, 09:40 UTC · re: Junio C Hamano · lore

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

Junio C Hamano wrote:
Show 11 quoted lines
> 
> 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

← back to recent threads