1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
|
# Command line, formatting, UI guidelines
## Command line options
### Short options
* reserved for the most common operations
* 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
* short but descriptive
* long-worded long options are acceptable for rare but seemingly unique operations
* example: `btrfs check --clear-space-cache v1`
### Help text
* short help for *--help* output: `btrfs subcommand [options] param1 param2`
* 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
### Structured output
* `Key: value`
* indentation used for visual separation
* value column alignment for quick skimming
* must be parseable by scripts but primary consumer of the output is a human, and greppable for logs
### Default output
* unix commands do one thing and say nothing, we may diverge a bit from that
* 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
* 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
* 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 details about what happens during level 2
* 4 - lots of information, for debugging and close inspection what happens
|
