4

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:

  1. Advise the user to invoke the tool with the --help option (and perhaps also report a missing operand).
  2. 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?

Improve this question
2
  • 1
    Interesting question.
    – Mayo
    Apr 15, 2015 at 13:01
  • always is such a strong word.
    – hometoast
    Apr 15, 2015 at 14:44

2 Answers 2

Reset to default
2

It seems to me, most CLI tools will show "use --help" when its --help information contains multiple pages of info.

rm might be an anomaly (its man page is small in comparison).

I try to use my own "will it scroll" test when deciding whether or not to give usage when a user provides incorrect or no parameters.

Improve this answer
3
  • Thanks. I like the idea of a "will it scroll" test as a criterion for deciding which of the two conventions to adopt. However, it begs the question, "What is the minimum number of lines the user can reasonably be assumed to be able to display?" Any idea what the answer is to that question?
    – user28926
    Apr 15, 2015 at 14:52
  • No idea. Though, most terminal applications or console devices have a typical number of rows (24-40). There's also the third option of "brief usage". Most people execute wget with one or two arguments. It's really going to depend so much on the typical usage of the tool you write
    – hometoast
    Apr 15, 2015 at 14:58
  • Thanks. I'm pretty sure I asked the "What is the minimum number of lines the user can reasonably be assumed to be able to display?" question somewhere else within the Stackexchange network a couple of years ago, but it wasn't appreciated and I can't find it now, so perhaps it was deleted. Irritating :) Anyway, how many lines do you assume, and why?
    – user28926
    Apr 15, 2015 at 15:07
0

I've never seen any research and would love to see some.

A system which simply states that there was an error and reminds the user where to find help seems to be geared more towards the expert user. A system that displays all the options ranging from log to rename to commit seems to be geared more to the new user (someone migrating to this particular system).

Obviously one is expecting a certain amount of facility with computers and applications if one is designing a command-line interface.

Answering your questions: "Which ... is better?" That would depend on your users. :-)

"Is one always better?" Absolutely not.

Improve this answer
2
  • Thanks for your answer. I've been thinking it over, and while your suggestion of an expectation of novice vs expert users as the criterion is well taken, this is also problematic insofar as any program developer probably hopes his/her users will end up as experts even if they (inevitably?) begin as novices. So ideally, the demarcation criterion should probably be based on some other aspect of UX, e.g. minimum likely screen height vs. lines of --help text as suggested by @hometoast.
    – user28926
    Apr 16, 2015 at 12:41
  • I thought that was an excellent point as well and I hadn't considered it. If that is a concern then absolutely that would be front and center.
    – Mayo
    Apr 16, 2015 at 13:08

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.