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
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
# Help text style guide
The command-line interface (CLI) tools `gitaly` and `praefect` are the primary interfaces to Gitaly and Gitaly Cluster.
For this reason, it's important that help text is standardized and complete.
The [`urfave/cli` library](https://cli.urfave.org) is used for CLI tooling in this project. It provides a number of
options for developers to provide help text to users.
## Rules for options
To help users discover `gitaly` and `praefect` features through the CLI:
- Always provide a value for the `Description` field key. This field key provides a lot of space to describe the command
or subcommand. At a minimum, provide a longer full sentence restatement of (but don't duplicate) the `Usage` field key
value.
- Always provide a value for the `UsageText` field key. Use this field key to provide:
- A template for invocation with placeholder values.
- Optional flags in square brackets.
- One or more examples with plausible values.
For example:
```go
UsageText: `gitaly subcommand <placeholder_value> --mandatory-flag <placeholder_value> [--optional-flag]
Example: gitaly subcommand plausible-value.toml --mandatory-flag plausible-value`,
```
- Because of a [known issue](https://gitlab.com/gitlab-org/gitaly/-/issues/5350), always set the `HideHelpCommand`
field key to `true`. Setting this hides the `COMMANDS:` section of the help text,
which hides a generated list of available subcommands, if available.
Instead, list subcommands in the value of the `Description` field key. For example:
```go
Description: `This is a long description of all the things example command can do.
Provides the following subcommands:
- subcommand1
- subcommand2`,
```
## Rules for command strings
When adding or updating `gitaly` and `praefect` CLI tools, use the following guidance for values for the different field
keys for commands and subcommands:
| Field key | All lower case | Use period | Example key and value |
|:--------------|:---------------|:-----------|:----------------------|
| `Name` | Yes | No | `Name: "example"` |
| `Usage` | Yes | No | `Usage: "short description of example command"` |
| `UsageText` | No | No | `example subcommand <example_placeholder>\n\nExample: example subcommand plausible-value.toml` |
| `Description` | No | Yes | `Description: "This is a long description of all the things example command can do."` |
### Specific rules for `Usage`
When providing values for the `Usage` field key:
- Don't mention Gitaly or Praefect explicitly. We imply in the help text the tool we're referring to.
- Do:
```plaintext
start the daemon
```
- Don't:
```plaintext
start the Gitaly daemon
```
- Always start with a verb and always write the string from the user's perspective, not the tool's perspective:
- Do:
```plaintext
run the process
```
- Don't:
```plaintext
runs the process
```
- Don't:
```plaintext
the process runs
```
### Specific rules for `Description`
When providing values for the `Description` field key:
- Can mention Gitaly, Praefect, or Gitaly Cluster. For example:
```plaintext
Runs all of the processes for the Gitaly Cluster.
```
- If the command or subcommand requires more than just flags, add an example of invoking the command. For example:
```go
Description: `The subcommand accepts a file on stdin.
Example: command subcommand < file`
```
## Related topics
- [UI text](https://design.gitlab.com/content/ui-text) from GitLab Design System.
- [Language](https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#language) from GitLab
Documentation Style Guide.
- [Command Line Interface Guidelines](https://clig.dev).
|
