Repository navigation
v7.4.0: Bash/zsh completion insertion fixes, parent-flag validation under subcommands, and `usage lint --quiet`
LatestThe shared completion subcommand can now send its script and its install report to different streams, and its install flags now declare what they do. This release also fixes how bash and zsh insert completion candidates, enforces parent flag rules after a subcommand is selected, and adds usage lint --quiet and rename_all_keys for #[derive(Config)].
Added
-
(lib)
Completion::run_split(andrun_split_infor tests) takes a second writer for the--installreport (#1629, @jdx). With it,ex completion fishprints only the script on stdout, andex completion fish --installleaves stdout empty and reports on stderr, the same asusage generate completion --install.runandrun_instill write everything to one writer.completion.run_split("ex", &mut std::io::stdout(), &mut std::io::stderr())?;
-
(lib) The shared
Completioncommand's exported spec now gives--installeffect="write"and--forceeffect="destructive"(#1627, @jdx).--forcegets the destructive label because it replaces a file usage did not generate and keeps no backup. Tools that audit or confirm command effects can now tell these flags apart from a plaincompletion <shell>, which still has no effect. -
(derive)
#[derive(Config)]takes a new struct-level option,rename_all_keys, that applies a case style to keys taken from field names (#1633, @jdx). It accepts the same values asrename_all. Explicitkey,prefix,aliasandenvvalues stay as written. A flattened group sets its ownrename_all_keysand does not inherit it from the parent. Without the option, keys don't change.#[derive(usage_rs::Config)] #[usage(prefix = "ui", rename_all_keys = "kebab-case")] struct Ui { dialog_theme: String, // ui.dialog-theme #[usage(key = "tab_width")] explicit_key: Option<u32>, // ui.tab_width }
-
(lint)
usage lint -q/--quietprints only the findings, withoutNo issues found.or theFound N error(s)summary (#1640, @jdx). Exit codes and--format jsondon't change. This is useful when you lint many specs in a loop:for f in scripts/*; do "$f" --usage-spec | usage lint -q -W -; done
Fixed
- (complete) Fixed how bash and zsh insert completion candidates in the scripts generated by usage-argv (#1644, @jdx).
- bash: completing
--shell=banow gives--shell=bashinstead of--shell=--shell=bash. - Trailing spaces: in bash and zsh, only finished candidates get a trailing space. Candidates ending in
@,:,/or=(such asnode@orsub/) are left open so you can keep typing.
- bash: completing
- (complete) With
default_subcommand_on_empty #true, completion at the root now offers the root's own subcommands and flags again instead of the default command's (#1631, @jdx). Parsing, help andusage explainstill select the default command. - (parse) A parent command's non-global flags now have their
required,requiresandconflictsrules enforced after a subcommand is selected, as the docs describe (#1635, @jdx). Before,x --a --c --d subpassed even thoughx --a --c --dfailed.subcommand_negates_reqsstill relaxesrequiredandrequires, and a flag that a subcommand redeclares follows the subcommand's definition. Behavior change: invocations that skipped a required parent flag or broke a parent'srequires/conflictsrule now fail. - (parse) On commands that have subcommands, usage-lib now handles the
helpsubcommand that the help page lists (x help,x help a,x a help) instead of failing withunexpected word: help(#1639, @jdx). On a leaf command,helpis now an ordinary word. A command's ownhelpsubcommand anddisable_help_subcommandstill take precedence. Behavior change: if a positional has strictchoicesthat don't includehelp, the wordhelpis now rejected as an invalid choice instead of showing help. - (cli)
usage bashand the other script runners now use the script's spec to decide whether-h/--helpasks for help (#1637, @jdx). A script withdisable_helpand its own-hflag, or a flag withallow_hyphen_valuesthat receives-has its value, now runs instead of printing help. Arguments after--are also handled correctly. - (cli)
usage bash,usage execand delegated completions now report an error if the shell or interpreter can't be started underqemu-userand similar platforms (#1653, @jdx). Before, they exited 127 with nothing on stderr. One side effect: an executable interpreter file with no shebang line now runs through/bin/shinstead of failing with "Exec format error".
Documentation
- Added
kongusage, a usage spec generator for Kong CLIs in Go, to the integrations page (#1643, @jdx).
Full Changelog: v7.3.0...v7.4.0
💚 Sponsor usage
usage is built and maintained by @jdx, an open source developer at entire.io, the title sponsor of his open source work.
If usage powers CLI specs, docs, or completions for a tool you maintain or use, please consider becoming an individual or company sponsor. Your support funds ongoing development and helps keep usage fast, free, and independent.