mirror of
https://github.com/kdave/btrfs-progs
synced 2025-04-01 22:48:06 +00:00
btrfs-progs: docs: update command line and UI conventions
Signed-off-by: David Sterba <dsterba@suse.com>
This commit is contained in:
parent
6eb0e9b3bb
commit
44bd0f6739
@ -1,67 +1,148 @@
|
|||||||
Command line, formatting, UI guidelines
|
Command line, formatting, UI guidelines
|
||||||
=======================================
|
=======================================
|
||||||
|
|
||||||
## Command line options
|
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.
|
||||||
|
|
||||||
### Short options
|
- *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*
|
||||||
|
|
||||||
* reserved for the most common operations
|
Command line options
|
||||||
* should follow some common scheme
|
--------------------
|
||||||
* verbose, recursive, force, output redirection, ...
|
|
||||||
* same option means the same thing in a group of related options
|
|
||||||
* most have an equivalent long option
|
|
||||||
|
|
||||||
### Long options
|
Unless there's a precedent for using a well known short option name, using
|
||||||
|
long option for first implementation is always safe.
|
||||||
|
|
||||||
* short but descriptive
|
All options parsers use :manref:`getopt(3)`, the behaviour is known and
|
||||||
* long-worded long options are acceptable for rare but seemingly unique operations
|
consistent with most tools and utilities found elsewhere. Options and parameters
|
||||||
* example: `btrfs check --clear-space-cache v1`
|
are sorted (options first) up to the ``--`` delimiter. Global options follow right
|
||||||
|
after the main command and are parsed separately from the subcommand, :command:`btrfs`,
|
||||||
|
following syntax
|
||||||
|
:command:`btrfs [global options] subcommand [options] <parameters...>`.
|
||||||
|
|
||||||
### Help text
|
Short options
|
||||||
|
^^^^^^^^^^^^^
|
||||||
|
|
||||||
* short help for *--help* output: `btrfs subcommand [options] param1 param2`
|
Short options are in short supply, ``a-z`` and ``A-Z``.
|
||||||
* the number of options gets unwieldy for many options so it's better to
|
|
||||||
insert the stub and document properly all of them in the detailed section
|
|
||||||
* short description after command line: terse but understandable explanation
|
|
||||||
what the command does
|
|
||||||
* 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
|
|
||||||
|
|
||||||
## Command output, verbosity
|
* reserved for the most common operations
|
||||||
|
* should follow some common scheme
|
||||||
|
|
||||||
### Structured output
|
* 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
|
||||||
|
|
||||||
* `Key: value`
|
* *upper case* could mean negating or extending meaning of lower case if it
|
||||||
* indentation used for visual separation
|
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 :doc:`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 :command:`btrfs filesystem
|
||||||
|
defrag -c` and :command:`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: :command:`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
|
* value column alignment for quick skimming
|
||||||
* must be parseable by scripts but primary consumer of the output is a human, and greppable for logs
|
* must be parseable and also visually comprehensible, related information
|
||||||
|
on one line usually satisfies both (*greppable*)
|
||||||
|
|
||||||
### Default output
|
Default output
|
||||||
|
^^^^^^^^^^^^^^
|
||||||
|
|
||||||
* unix commands do one thing and say nothing, we may diverge a bit from that
|
* 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
|
* 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
|
|
||||||
* line length should not exceed 80 columns if possible but this is not a strict
|
|
||||||
limit and we want to put the relevant information there rather abbreviate too
|
|
||||||
much
|
|
||||||
|
|
||||||
### Formatting
|
* 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 :command:`btrfs -q subcommand`,
|
||||||
|
this can be easily scripted e.g. storing the global verbosity option in a
|
||||||
|
variable, :command:`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
|
* numeric values are not quoted
|
||||||
* string values are quoted if they would be confused when parsed word by word
|
* string values are quoted if they would be confused when parsed word by word
|
||||||
(e.g. file paths)
|
(e.g. file paths)
|
||||||
* quoting is by single apostrophe on both ends
|
* quoting is by single apostrophe on both ends, no fancy backtick+quote
|
||||||
* all messages follow a few known and understood schemes
|
* all messages follow a few known and understood schemes
|
||||||
|
|
||||||
### Verbosity levels
|
Verbosity levels
|
||||||
|
^^^^^^^^^^^^^^^^
|
||||||
|
|
||||||
* 0 - quiet, only errors to stderr, nothing to stdout
|
* 0 - quiet, only errors to *stderr*, nothing to *stdout*
|
||||||
* 1 - default, one line, see above
|
* 1 - default, one line, see above
|
||||||
* 2 - inform about main steps that happen
|
* 2 - inform about main steps that happen
|
||||||
* 3 - a little bit more details about what happens during level 2
|
* 3 - a little bit more detailed about what happens during level 2
|
||||||
* 4 - lots of information, for debugging and close inspection what happens
|
* 4 - possibly lots of information, for debugging and close inspection what happens
|
||||||
|
Loading…
Reference in New Issue
Block a user