Command line, formatting, UI guidelines

The guidelines try to follow common principles and build on experience based on user feedback or practices seen in other projects. There are no strict rules but rather vague statements or principles that is recommended to follow. It’s recommended to follow them or use them as review checklist. Optimize for humans.

  • sane defaults

  • principle of least surprise

  • it does what it says

  • it says what it does

  • frequently performed actions have shortcuts

  • easy thing easy, hard things possible

  • dangerous actions are explicit or need a confirmation

  • same name means the same thing everywhere

  • it’s hard to change things once they are released

Command line options

Unless there’s a precedent for using a well known short option name, using long option for first implementation is always safe.

All options parsers use getopt(3), the behaviour is known and consistent with most tools and utilities found elsewhere. Options and parameters are sorted (options first) up to the -- delimiter. Global options follow right after the main command and are parsed separately from the subcommand, btrfs, following syntax btrfs [global options] subcommand [options] <parameters...>.

Short options

Short options are in short supply, a-z and A-Z.

  • reserved for the most common operations

  • should follow some common scheme

    • verbose (-v), recursive (-r, -R), force (-f), output redirection (-o), …

    • same option means the same thing in a group of related options

    • mnemonic naming when possible, e.g. first letter of the action like -l for length but with growing number of features clashes can and will happen

  • upper case could mean negating or extending meaning of lower case if it exists, using both upper and lower case for different purposes can be confusing

  • most short options should have an equivalent long option

  • rarely done actions do not need short options at all

Long options

Long options are meant to be descriptive, e.g. when used in scripts, documentation or change descriptions.

  • brief but descriptive

  • long and descriptive can be used in justified cases (e.g. conversion options in btrfstune because of the single command without subcommands)

Option parameters

Note

Avoid using optional parameter. This is a usability misfeature of getopt() because of the mandatory short option syntax where the parameter must be glued to the option name, like -czstd so this looks like a group of short options but it is not. In this example -c zstd is not the same, the parameter will take default value and zstd will be understood as another parameter. Unfortunate examples are btrfs filesystem defrag -c and btrfs balance start -d. Both quite common and we probably cannot fix this without breaking existing scripts.

Help text

Description in the help text should be long enough to describe what it does, mention default value and should not be too long or detailed. Referring to documentation is recommended when it’s really wise to read it first before using it. Otherwise it’s a reminder to user who has probably used it in the past.

  • short help for --help output: btrfs subcommand [options] param1 param2

    • the number of options gets unwieldy for a command with many tunable features so it’s better to write a short description and document properly everything in the manual page or in the followup text

  • short description after command line: terse but understandable explanation what the command does, mention dangers

  • long description after the short description

    • explain in more detail what the command does, different use cases, things to notice

    • more complex things should be documented in the manual pages and pointed to (examples)

Command output, verbosity

Structured output

If the output consists of a lot of information, try to present it in a concise way and structure related information together using some known formats or already used ones in this project.

  • Key: value, spacing by tabs or spaces

  • use indentation and empty lines for visual separation

  • value column alignment for quick skimming

  • must be parseable and also visually comprehensible, related information on one line usually satisfies both (greppable)

Default output

  • UNIX commands do one thing and say nothing, we diverge from that as it does not work well for a multi-command tools

  • default output is one line shortly describing the action

    • why: running commands from scripts or among many other commands should be noticeable due to progress tracking or for analysis if something goes wrong

    • there’s a global option to make the commands silent btrfs -q subcommand, this can be easily scripted e.g. storing the global verbosity option in a variable, btrfs $quiet subcommand and then enabling or disabling as needed

  • there should be a line length limit so the output visually fits to one line without wrapping, there’s no exact number of columns, assume something around 100, keep related information on one line (printed) rather then breaking it.

Formatting

  • numeric values are not quoted

  • string values are quoted if they would be confused when parsed word by word (e.g. file paths) * quoting is by single apostrophe on both ends, no fancy backtick+quote

  • all messages follow a few known and understood schemes

Verbosity levels

  • 0 - quiet, only errors to stderr, nothing to stdout

  • 1 - default, one line, see above

  • 2 - inform about main steps that happen

  • 3 - a little bit more detailed about what happens during level 2

  • 4 - possibly lots of information, for debugging and close inspection what happens