Context
N.B. Herein, the terms "tool", "application", and "program" are used interchangeably.
This question is not concerned with CLI tools that are intended to be useful when called without arguments (e.g. ls
, echo
); it only concerns command line interface applications that, when called without arguments, are intended to be:
- nullipotent, and
- not useful.
Many such programs that are mature have adopted one of two conventions for responding to being executed without arguments:
- Advise the user to invoke the tool with the
--help
option (and perhaps also report a missing operand). - Output usage information (as though the user had invoked the tool with the
--help
option).
In both conventions, the exit status (aka "exit code" or "return code") is non-zero.
Examples
The first convention is exemplified by rm
:
$ rm
rm: missing operand
Try 'rm --help' for more information.
and also by wget
$ wget
wget: missing URL
Usage: wget [OPTION]... [URL]...
Try `wget --help' for more options.
The second convention is exemplified by e.g. git
:
$ git
usage: git [--version] [--help] [-C <path>] [-c name=value]
[--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]
[-p|--paginate|--no-pager] [--no-replace-objects] [--bare]
[--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]
<command> [<args>]
The most commonly used git commands are:
add Add file contents to the index
bisect Find by binary search the change that introduced a bug
branch List, create, or delete branches
checkout Checkout a branch or paths to the working tree
clone Clone a repository into a new directory
commit Record changes to the repository
diff Show changes between commits, commit and working tree, etc
fetch Download objects and refs from another repository
grep Print lines matching a pattern
init Create an empty Git repository or reinitialise an existing one
log Show commit logs
merge Join two or more development histories together
mv Move or rename a file, a directory, or a symlink
pull Fetch from and integrate with another repository or a local branch
push Update remote refs along with associated objects
rebase Forward-port local commits to the updated upstream head
reset Reset current HEAD to the specified state
rm Remove files from the working tree and from the index
show Show various types of objects
status Show the working tree status
tag Create, list, delete or verify a tag object signed with GPG
'git help -a' and 'git help -g' lists available subcommands and some
concept guides. See 'git help <command>' or 'git help <concept>'
to read about a specific subcommand or concept.
Question
Which of these two conventions is better from a UX standpoint and why?
Subsidiary to that, is it perhaps the case that there are some instances where one convention is better and other cases where the other is better - or is one of the conventions always superior?