The CLI (1): Getting help
This is part one of the series “The State of the CLI”. There’s a lot to write about, but let’s start small: how helpful are command line tools and how do we acquire help?
Tue, 12 Feb 2013
“Help!”, I mean, “Hilfe?”
You’d think that getting help on certain commands is the most straightforward thing ever, but I’ve found that this isn’t always the case. Most commands carry help screens and documentation, but the way you access these may vary.
If you’re a bit more familiar with the CLI, you’d probably start by running the command accompanied by arguments or options that may show you the help screen. These will be different depending on who provided it (eg. GNU, or BSD): help, --help, -help, -h, ?, and -? are all possibilities (I will discuss the different option styles in a different post). I’m trying to figure out how this new command works. This is a bit like someone nagging who’s asking for help because they didn’t say "please" correctly in the right language. This is mostly due to Linux distributions shipping tools from many different projects. Overall though, --help seems to be the safest bet.
A less proactive approach would be to pretend to be clueless and pass a bogus argument or option to a command. If you’re lucky, you’ll be shown some information on how to get to the help screen.
hbons@slowpoke:~$ ip --foo
Option "-foo" is unknown, try "ip -help".
hbons@slowpoke:~$ mkdir --foo
mkdir: unrecognized option '--foo'
Try `mkdir --help' for more information.
We didn’t get what we wanted in either case here, but at least we’re being led into the right direction.
Lastly, and probably most obviously, you can launch the command without any arguments at all. Some commands will give you the help this way. There is a downside to this kind of investigation, however. Running a command blindly can have unintended consequences, and may actually be dangerous due to inconsistency between different commands (“will this trigger an action, or show me the help?”).
Handholding (or not)
The access to useful help differs greatly between commands. This is what the BSD version of the ls command does:
hbons@slowpoke:~$ ls --help
ls: illegal option -- -
usage: ls [-ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1] [file ...]
It doesn’t look particularly useful at all. It lists all the option that you can possibly enter, but there’s no indication of what any of these do, nor are there any hints about how you can find out. Even if I was more experienced using this command, it’s hard to see how a line like this could be helpful.
The git command line tools are short but helpful when you do something wrong. You’re being pointed to the help:
hbons@slowpoke:~$ git unknown
git: 'unknown' is not a git command. See 'git --help'.
Additionally, these tools have a nice mechanism built in that tries to guess your intentions when you’ve made a typo, or when you’ve entered a command that doesn’t exist:
hbons@slowpoke:~$ git pu
git: 'pu' is not a git command. See 'git --help'.
Did you mean one of these?
In addition to help screens, most commands have a good (sometimes overwhelming) amount of well written documentation available. It’s just a matter of how you get to it. The vast majority of commands ship with what are called “man” (manual) pages. Documentation on a command can be retrieved by running the man command with a subject (command name) as an argument. There’s also the info command by the GNU project, but it doesn’t seem as commonly used.
Some commands have pointers at the end of their help screens on how to get more detailed help and documentation. Good examples of this are git and GNU’s version of ls:
hbons@slowpoke:~$ ls --help
Report ls bugs to firstname.lastname@example.org
GNU coreutils home page: <http://www.gnu.org/software/coreutils/>
General help using GNU software: <http://www.gnu.org/gethelp/>
For complete documentation, run: info coreutils 'ls invocation'
hbons@slowpoke:~$ git --help
See 'git help <command>' for more information on a specific command.
Do you have problems getting help with commands, or do you have opinions or tips on how to make things better? I look forward to your feedback, please let me know.
Comments? Send me a tweet.