me
Hello there! I'm Hylke Bons and
I design pretty and usable digital things
about — hylkebons@gmail.com — @hbons

about

People who haven’t met me in person sometimes wonder if this is a guy’s or a girl’s name. It can be used for either, but I’m a guy. Originally I’m from The Netherlands (but partly of Asian blood). More specifically the northern city of Groningen. There I studied Information Science at the local university.

At the moment I live in London, England, where I work as an Interaction and Graphic Designer at Red Hat’s User Experience team. I like creating (digital) things that aim to make people’s lives easier, and make these things look pretty at the same time. I try to document my experiences in these areas in the Journal section of this site. Right now, SparkleShare and GNOME get most of my attention, but you may know me from my earlier icon work on Pidgin and MeeGo.

In my free time I like to do fun things (surprise!), like doing photography, playing games, and cycling on my trusty Brompton. I like to travel to places to just wander around and see the world, although I should do that more often.

I take design jobs for food, simply send me an email. You can also find me on Twitter, Flickr and Github. If you are in need of an illustrator, consider hiring my sister (because she's awesome).

home   »   journal

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.
hbons@slowpoke:~$

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 ...]
hbons@slowpoke:~$

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'.
hbons@slowpoke:~$

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?
    pull
    push
hbons@slowpoke:~$

Documentation

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 bug-coreutils@gnu.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.
hbons@slowpoke:~$

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.