Hi Guix,
I found the help output not to be very helpful whenever there are
sub-commands. The output contains options that are not relevant to the
sub-command. The options also don't appear to be ordered.
Here is an example. I want to know more about "guix system
docker-image", so I run "guix system docker-image --help". This is the
output I get:
--8<---------------cut here---------------start------------->8---
Usage: guix system [OPTION ...] ACTION [ARG ...] [FILE]
Build the operating system declared in FILE according to ACTION.
Some ACTIONS support additional ARGS.
The valid values for ACTION are:
search search for existing service types
edit edit the definition of an existing service type
reconfigure switch to a new operating system configuration
roll-back switch to the previous operating system configuration
describe describe the current system
list-generations list the system generations
switch-generation switch to an existing operating system configuration
delete-generations delete old system generations
build build the operating system without installing anything
container build a container that shares the host's store
vm build a virtual machine image that shares the host's store
image build a Guix System image
docker-image build a Docker image
init initialize a root file system to run GNU
extension-graph emit the service extension graph in Dot format
shepherd-graph emit the graph of shepherd services in Dot format
-L, --load-path=DIR prepend DIR to the package module search path
-K, --keep-failed keep build tree of failed builds
-k, --keep-going keep going when some of the derivations fail
-n, --dry-run do not build the derivations
--fallback fall back to building when the substituter fails
--no-substitutes build instead of resorting to pre-built substitutes
--substitute-urls=URLS
fetch substitute from URLS if they are authorized
--no-grafts do not graft packages
--no-offload do not attempt to offload builds
--max-silent-time=SECONDS
mark the build as failed after SECONDS of silence
--timeout=SECONDS mark the build as failed after SECONDS of activity
--rounds=N build N times in a row to detect non-determinism
-c, --cores=N allow the use of up to N CPU cores for the build
-M, --max-jobs=N allow at most N build jobs
--debug=LEVEL produce debugging output at LEVEL
-d, --derivation return the derivation of the given system
-e, --expression=EXPR consider the operating-system EXPR evaluates to
instead of reading FILE, when applicable
--allow-downgrades for 'reconfigure', allow downgrades to earlier
channel revisions
--on-error=STRATEGY
apply STRATEGY (one of nothing-special, backtrace,
or debug) when an error occurs while reading FILE
--list-image-types list available image types
-t, --image-type=TYPE for 'image', produce an image of TYPE
--image-size=SIZE for 'image', produce an image of SIZE
--no-bootloader for 'init', do not install a bootloader
--volatile for 'image', make the root file system volatile
--persistent for 'vm', make the root file system persistent
--label=LABEL for 'image', label disk image with LABEL
--save-provenance save provenance information
--share=SPEC for 'vm' and 'container', share host file system with
read/write access according to SPEC
--expose=SPEC for 'vm' and 'container', expose host file system
directory as read-only according to SPEC
-N, --network for 'container', allow containers to access the
network
-r, --root=FILE for 'vm', 'image', 'container' and 'build',
make FILE a symlink to the result, and
register it as a garbage collector root
--full-boot for 'vm', make a full boot sequence
--no-graphic for 'vm', use the tty that we are started in for IO
--skip-checks skip file system and initrd module safety checks
-v, --verbosity=LEVEL use the given verbosity LEVEL
--graph-backend=BACKEND
use BACKEND for 'extension-graph' and 'shepherd-graph'
-I, --list-installed[=REGEXP]
for 'describe' and 'list-generations', list installed
packages matching REGEXP
--list-targets list available targets
--target=TRIPLET cross-build for TRIPLET--e.g., "aarch64-linux-gnu"
--list-systems list available systems
-s, --system=SYSTEM attempt to build for SYSTEM--e.g., "i686-linux"
--help-docker-format list options specific to the docker image type.
-h, --help display this help and exit
-V, --version display version information and exit
Report bugs to: bug-guix@gnu.org.
GNU Guix home page: <https://guix.gnu.org>
General help using Guix and GNU software: <https://guix.gnu.org/en/help/>
--8<---------------cut here---------------end--------------->8---
Note that this is the same output as for "guix system --help".
I don't think it's great to see all these "for 'vm'" qualifiers on the
right-hand side.
Here is what I propose:
- In the case of commands that offer sub-commands, remove *all* the
options from the help output of the main command (e.g. "guix system
--help"), and only showing the list of available sub-commands.
- For "guix [command] [sub-command] --help" show only options to this
sub-command.
- optionally, group all generic options (e.g. --system, --help,
--version, etc) under a single heading.
What do you think?
OpenPGP_0x0AB0D067012F08C3.asc