C0025 cli-color-flag¶
Rule: A CLI takes a global --color flag with auto, always and never.
| Code | C0025 (stable, never reused) |
| Id | cli-color-flag |
| Category | cli |
| Source | spirit_level |
| Fix | by hand |
| Needs | cargo installed |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | warn |
--color settles what automatic colour guesses wrong, the same way in every tool; older CLIs add it when touched |
| small-workspace | warn |
--color settles what automatic colour guesses wrong, the same way in every tool; older CLIs add it when touched |
| medium | warn |
--color settles what automatic colour guesses wrong, the same way in every tool; older CLIs add it when touched |
| big | warn |
--color settles what automatic colour guesses wrong, the same way in every tool; older CLIs add it when touched |
| ai | off | |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
flag |
string | "--color" |
the colour flag |
values |
list of strings | ["auto", "always", "never"] |
the values it takes |
Why¶
Automatic colour guesses wrong sometimes: a pager that understands escapes, a CI log that renders them, a terminal a person wants plain. A --color auto|always|never flag settles it the same way in every tool. It is global, so it works after the subcommand too (tool sync --color never).
Example¶
#[derive(clap::Parser)]
struct Cli {
#[command(flatten)]
color: vc_ui::ColorFlag, // --color <WHEN>, global, default auto
#[command(subcommand)]
cmd: Cmd,
}
How to fix¶
Flatten vc_ui::ColorFlag into the root parser and call cli.color.apply() after parsing, or declare --color <WHEN> with the values auto, always and never and global = true. The parameters flag and values name the flag and its values.
Configure¶
[lints.cli-color-flag]
level = "deny"
flag = "--color"
values = ["auto", "always", "never"]
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(cli-color-flag) <reason> (waivers); the code works there too, as in [lints.C0025].