Target is a required argument even though it appears to be optional in help

[ilyakam]

Before I start using any CLI, I like to go through its --help options to make sure I understand how to use it. In this case, here is the abbreviated output of git-revise version 0.4.2:

$ git-revise --help
usage: git-revise [-h] [--ref REF] [--reauthor] [--version] [--autosquash]
                  [--edit] [--no-index | --all]
                  [--interactive | --message MESSAGE | --cut]
                  [target]

As you can see on the last line, [target] appears to be optional since it's wrapped in square brackets ([]). However, when I call git-revise with no additional parameters in some repo, it reports the following error:

$ git-revise
invalid value: <target> is a required argument

Please consider updating the --help output to indicate that target is in fact a required argument.

[mystor]

It's an optional argument when the --interactive or --autosquash flags are passed, which is why the usage displays it as optional.

[ilyakam]

Is there a way to indicate the different paths that the user can take and the required flags for each one? Check out these two examples:

git version 2.18.0:

$ git --help
usage: git [--version] [--help] [-C <path>] [-c <name>=<value>]
           [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
           [-p | --paginate | -P | --no-pager] [--no-replace-objects] [--bare]
           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
           <command> [<args>]

Note the non-optional <command> in this case

---

Homebrew version 2.1.7

$ brew --help
Example usage:
  brew search [TEXT|/REGEX/]
  brew info [FORMULA...]
  brew install FORMULA...
  brew update
  brew upgrade [FORMULA...]
  brew uninstall FORMULA...
  brew list [FORMULA...]

Note that the optional flags are listed after each required command.

---

I'm not sure what's the best option for git-revise, but I'll be happy to brainstorm and come up with a clearer --help output so that not every flags appears to be optional at first glance.

[mystor]

It's possible to have a similar pattern with a required <command> option, and it's fairly common for argparse-based tools.

Unfortunately, git revise was designed to have a similar command line interface to git rebase, which specifies the interactive mode with an --interactive parameter. git rebase also has this issue, with this usage line:

git rebase [-i | --interactive] [<options>] [--exec <cmd>] [--onto <newbase>]
        [<upstream> [<branch>]]
git rebase [-i | --interactive] [<options>] [--exec <cmd>] [--onto <newbase>]
        --root [<branch>]
git rebase --continue | --skip | --abort | --quit | --edit-todo | --show-current-patch

I don't intend to change the command line API of git revise to be dramatically different from rebase, as having it be similar makes it easier to learn.

I should also note that the direct git-revise --help API is generally hidden when used as a git subcommand, as git will open the manpage in response to git revise --help. It's probably best to make the behaviour of the command more clear by clarifying usage suggestions in the manpage.