“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.

Pros and cons

The CLI can be helpful in a lot of cases, but it has a bit of a learning curve. It allows you to do simple canonical things, but these things can be linked together in various ways that can’t often be done with Graphical User Interfaces (or GUIs). Thus sparing you from tedious repetitive labour.

Some applications also allow for command line interaction next to their graphical user interface, which makes them able to be integrated in automated processes.

In my opinion, the CLI sits about half way between raw programming and using a graphical application to get your tasks done. There are graphical applications that can give you a lot of control as well. A good example of this is OS X’s Automator.

It may be that your product provides (or requires) some interaction on the CLI level. Now how do you go about doing this right?

GNU and BSD

Linux distributions are a mixed bag of different programs, and so these programs don’t always behave in the same predictable ways. Most common commands originate either from the GNU or BSD projects.

Superficially, BSD sticks more to the older Unix days, whilst GNU tries to come up with new ideas that makes their programs a little more convenient to use.

Eric Raymond’s The Art of UNIX programming goes into CLI interface design a little bit. The GNU Coding Standards has something to say about the topic as well.

Overall, documentation and guidelines are sparse. As a developer writing software for Linux distributions, it’s not clear where one should go.

Best practises

The CLI is used most often by people that are more familiar with computers, software developers, system administrators, and those who like to tinker. This doesn’t mean that the CLI has to or is allowed be a suboptimal experience on that level.

What’s noticeable is that there doesn’t seem to be much documented reasoning or motivation behind any of the CLI design decisions. Things mostly seem the way they are because of “historic” reasons or tradition.

The next couple of months I’m going to to assess the CLI of various common software packages and write blog posts about them, to come up with a list of best practises that doesn’t conflict with the current state of utilities out there.

I’d like to explicitly mention that these will be best practises that are compatible with current conventions, not some new official “standard”. Having some rules that you can keep in mind, as well as knowing the reasons behind them. I don’t want to fall into the standards trap.

The usual suspects

If you administrate a server, you’ve probably used commands from the following packages:

• GNU coreutils, a collection of basic tools, such as cat, ls, and rm
• GnuPG, encryption tools
• openSSH, connectivity tools for remote access
• Apt, package management
• Git, source code management
• cURL, data transfer/download tool

These are some of the tools I’ll be looking at.

To wrap up: this is not about redefining the command line experience, or creating some revolutionary alternative. rather to identify issues, streamline the process, and come up with some design patterns that may help you write a usable CLI application for Linux.

If you have any CLI pet peeves, know of commands that are really good/bad, or have any other tips or links you think I should read, please let me know.

What is SparkleShare?

SparkleShare is an Open Source (self hosted) file synchronisation and collaboration tool and is available for Linux distributions, Mac, and Windows.

SparkleShare creates a special folder on your computer in which projects are kept. All projects are automatically synced to their respective hosts (you can have multiple projects connected to different hosts) and to your team’s SparkleShare folders when someone adds, removes or edits a file.

The idea for SparkleShare sprouted about three years ago at the gnome Usability Hackfest in London (for more background on this read The one where the designers ask for a pony).

SparkleShare uses the version control system Git under the hood, so people collaborating on projects can make use of existing infrastructure, and setting up a host yourself will be easy enough. Using your own host gives you more privacy and control, as well as lots of cheap storage space and higher transfer speeds.

Like every piece of software it’s not bug free, even though it has hit 1.0. But it’s been tested for a long time now and all reproducable and known major issues have been fixed. It works reliably and the issue tracker is mostly filled with feature requests now.

The biggest sign that it was time for a 1.0 release was the fact that Lapo hasn’t reported brokenness for a while now. This can either mean that SparkleShare has been blessed by a unicorn or that the world will end soon. I think it’s the first.

Features

For those of you that are not (that) familiar with SparkleShare, I’ll sum up its most important features:

The SparkleShare Folder

This is where all of your projects are kept. Everything in this folder will be automatically synced to the remote host(s), as well as to your other computers and everyone else connected to the same projects. Are you done with a project? Simply delete it from your SparkleShare folder.

The status icon

The status icon gives you quick access to all of your projects and shows you what’s going on regarding the synchronisation process. From here you can connect to existing remote projects and open the recent changes window.

The setup dialog

Here you can link to a remote project. SparkleShare ships with a couple of presets. You can have mulitple projects syncing to different hosts at the same time. For example, I use this to sync some public projects with Github, some personal documents with my own private vps and work stuff with a host on the intranet.

Recent changes

The recent changes window shows you everything that has recently changed and by whom.

History

The history view let’s you see who has edited a particular file before and allows you to restore deleted files or revert back to a previous version.

Conflict handling

When a file has been changed by two people at the same time and causes a conflict, SparkleShare will create a copy of the conflicting file and adds a timestamp. This way changes won’t get accidentally lost and you can either choose to keep one of the files or cherry pick the wanted changes.

Notifications

If someone makes a change to a file a notification will pop up saying what changed and by whom.

Client side encryption

Optionally you can protect a project with a password. When you do, all files in it will be e encrypted locally using AES-256-CBC before being transferred to the host. The password is only stored locally, so if someone cracked their way into your server it will be very hard (if not impossible) to get the files’ contents. This on top of the file transfer mechanism, which is already encrypted and secure. You can set up an encrypted project easily with Dazzle.

Dazzle, the host setup script

I’ve created a script called Dazzle that helps you set up a Linux host to which you have SSH access. It installs Git, adds a user account and configures the right permissions. With it, you should be able to get up and running by executing just three simple commands.

Plans for the future

Something that comes up a lot is the fact that Git doesn’t handle large (binary) files well. Git also stores a database of all the files including history on every client, causing it to use a lot of space pretty quickly. Now this may or may not be a problem depending on your usecase. Nevertheless I want SparkleShare to be better at the “large backups of bulks of data” usecase.

I’ve stumbled upon a nice little project called git-bin in some obscure corner of Github. It seems like a perfect match for SparkleShare. Some work needs to be done to integrate it and to make sure it works over SSH. This will be the goal for SparkleShare 2.0, which can follow pretty soon (hopefully in months, rather than years).

I really hope contributors can help me out in this area. The Github network graph is feeling a bit lonely. Your help can make a big difference!

Some other fun things to work on may be:

• Saving the modification times of files
• Creating a binary Linux bundle
• SparkleShare folder location selection
• GNOME 3 integration
• ...other things that you may find useful.

If you want to get started on contributing, feel free to visit the IRC channel: #sparkleshare on irc.gnome.org so I can answer any questions you may have and give support.

Finally...

I’d like to thank everyone who has helped testing and submitted patches so far. SparkleShare wouldn’t be nearly as far as it is now without you. Cheers!

This has been a public service announcement. :)

What is SparkleShare?

SparkleShare is the result of “Project SparklePonyP. At the Usability Hackfest this year in London, a couple of us open source designers came to the conclusion that we don’t have a proper collaboration tool. We have been using Dropbox for this for a while. Dropbox has a great user experience, but it has downsides as well: you can’t host your own server; it’s not open source and has some freaky things in its license agreement.

Features

So SparkleShare aims to replace Dropbox for us. There are some resemblances and some differences. SparkleShare creates a SparkleShare folder in your home directory in which you can add different remote folders (these can be on different servers). It has the same Dropbox like notification system, one feature that we really liked. It allows you to see what others are doing and take peek, much easier than sending around e-mails, forget attachments and add wrong CCs. The most important thing is that the synchronisation is automatic and happens when you add or edit files.

Technology

SparkleShare is build on Mono, GTK+ and wraps around Git. It aims to integrate with the GNOME desktop environment. I’m planning OS X and Windows versions as well (in that order).

There is no release out yet, as I’ve yet to fix some nasty bugs, but my programming skills are quite limited as of yet. So this is a…

Call for contributors

Help would be very much appreciated! Any kind of contribution would be great. Translations, bug reports, code, docs, it doesn’t matter. Check out sparkleshare.org for links to the source code on gitorious. Join #sparkleshare on git.gnome.org if you have any questions

Special thanks…

…to Jakub Steiner and Lapo Calamandrei for the awesome artwork and website design!