CLI: 'tahoe $SUBCOMMAND --help' no longer shows "global" options

[daira]

For example, in Tahoe-LAFS v1.9.2:

$ bin/tahoe start --help
Usage:  tahoe start [options] [NODEDIR]
Options:
  -q, --quiet             Operate silently.
  -V, --version           Display version numbers.
      --version-and-path  Display version numbers and paths to their locations.
  -p, --profile           Run under the Python profiler, putting results in
                          'profiling_results.prof'.
      --syslog            Tell the node to log to syslog, not a file.
  -C, --basedir=          Same as --node-directory.
  -d, --node-directory=   Specify which Tahoe node directory should be used.
                          [default for most commands: 'REDACTED']
      --help              Display this help and exit.

In Tahoe-LAFS v1.10.0:

$ bin/tahoe start --help
Usage:  tahoe [global-opts] start [options] [NODEDIR]
Options:
  -p, --profile   Run under the Python profiler, putting results in
                  'profiling_results.prof'.
      --syslog    Tell the node to log to syslog, not a file.
  -C, --basedir=  Same as --node-directory (default REDACTED).
      --version   
      --help      Display this help and exit.

This appears to be a regression due to the fix for #166.

[daira]

The desired output is:

$ bin/tahoe start --help
Usage:  tahoe [global-opts] start [options] [NODEDIR]
Global options:
  -q, --quiet             Operate silently.
  -V, --version           Display version numbers.
      --version-and-path  Display version numbers and paths to their locations.
  -d, --node-directory=   Specify an empty directory to be used for the new Tahoe node.
                          [default for most commands: '/home/davidsarah/.tahoe']
Options:
  -p, --profile   Run under the Python profiler, putting results in
                  'profiling_results.prof'.
      --syslog    Tell the node to log to syslog, not a file.
  -C, --basedir=  Same as --node-directory.
      --version   
      --help      Display this help and exit.

Notice that the desired description of -d for create-* subcommands is not the one that is currently printed for tahoe --help:

$ bin/tahoe --help

Usage: tahoe [global-opts] <command> [command-options]
Options:
  -q, --quiet             Operate silently.
  -V, --version           Display version numbers.
      --version-and-path  Display version numbers and paths to their locations.
  -d, --node-directory=   Specify which Tahoe node directory should be used. The
                          directory should either contain a full Tahoe node, or
                          a file named node.url that points to some other Tahoe
                          node. It should also contain a file named
                          'private/aliases' which contains the mapping from
                          alias name to root dirnode URI. [default for most
                          commands: '/home/davidsarah/.tahoe']
      --help              Display this help and exit.

[daira]

This is not a blocker for 1.10.1, just a nice-to-have.

[warner]

Hm, does it really need to do this? I think that could get a bit noisy, to have those same global opts on every command. Git doesn't do it that way.

How about a single line that points to tahoe --help to get the global options, like:

$ bin/tahoe start --help
Usage:  tahoe [global-opts] start [options] [NODEDIR]
(use 'tahoe --help' to view global options)

Options:
  -p, --profile   Run under the Python profiler, putting results in
                  'profiling_results.prof'.
      --syslog    Tell the node to log to syslog, not a file.
  -C, --basedir=  Same as --node-directory.
      --version   
      --help      Display this help and exit.

but maybe we inline the global-opts on just the create-* subcommands, to emphasize how -d is different there:

$ ./bin/tahoe create-node --help
Usage: tahoe [global-opts] create-node [options] [NODEDIR]

Global options:
  -q, --quiet             Operate silently.
  -V, --version           Display version numbers.
      --version-and-path  Display version numbers and paths to their locations.
  -d, --node-directory=   Specify an empty directory to be used for the new
                          Tahoe node.
      --help              Display this help and exit.

Options:
      --no-storage   Do not offer storage service to other nodes.
  -C, --basedir=     Specify which Tahoe base directory should be used.
                     [default: '/Users/warner/.tahoe']
  -n, --nickname=    Specify the nickname for this node.
  -i, --introducer=  Specify the introducer FURL to use.
  -p, --webport=     Specify which TCP port to run the HTTP interface on. Use
                     'none' to disable. [default: tcp:3456:interface=127.0.0.1]
      --version
      --help         Display this help and exit.

[daira]

Hmm. The description "Same as --node-directory." for -C doesn't make sense unless --node-directory is described. I think I'd prefer it as it is in comment:1, TBH.

[warner]

What it we removed that "same as" reference?:

$ bin/tahoe start --help
Usage:  tahoe [global-opts] start [options] [NODEDIR]
(use 'tahoe --help' to view global options)

Options:
  -p, --profile   Run under the Python profiler, putting results in
                  'profiling_results.prof'.
      --syslog    Tell the node to log to syslog, not a file.
  -C, --basedir=  Specify which Tahoe base directory should be used.
                  [default: '/Users/warner/.tahoe']. Overrides any
                  global --basedir option.
      --version   
      --help      Display this help and exit.

[daira]

It is not the case that --basedir= overrides --node-directory=; only one may be present.

Better would be:

$ bin/tahoe start --help
Usage:  tahoe [global-opts] start [options] [NODEDIR]
(use 'tahoe --help' to view global options)

Options:
  -p, --profile   Run under the Python profiler, putting results in
                  'profiling_results.prof'.
      --syslog    Tell the node to log to syslog, not a file.
  -C, --basedir=  Specify which Tahoe base directory should be used.
                  [default: '/Users/warner/.tahoe']. This has the same
                  effect as the global --node-directory option.
      --version   
      --help      Display this help and exit.

[warner]

PR ready for review in ​https://github.com/tahoe-lafs/tahoe-lafs/pull/168

[daira]

LGTM.

[Brian Warner <warner@…>]

In 9d6003357da3eab8106269a022f4a615d52b0f8b/trunk:

Merge branch 'globalopts2'

Improves CLI rendering of --help for global options. Closes ticket:2233.