Skip to content

v7.4.0: Bash/zsh completion insertion fixes, parent-flag validation under subcommands, and `usage lint --quiet`

Latest

Choose a tag to compare

@github-actions github-actions released this 16 Nov 20:13
Immutable release. Only release title and notes can be modified.
f259729

The 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 (and run_split_in for tests) takes a second writer for the --install report (#1629, @jdx). With it, ex completion fish prints only the script on stdout, and ex completion fish --install leaves stdout empty and reports on stderr, the same as usage generate completion --install. run and run_in still write everything to one writer.

    completion.run_split("ex", &mut std::io::stdout(), &mut std::io::stderr())?;
  • (lib) The shared Completion command's exported spec now gives --install effect="write" and --force effect="destructive" (#1627, @jdx). --force gets 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 plain completion <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 as rename_all. Explicit key, prefix, alias and env values stay as written. A flattened group sets its own rename_all_keys and 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/--quiet prints only the findings, without No issues found. or the Found N error(s) summary (#1640, @jdx). Exit codes and --format json don'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=ba now gives --shell=bash instead of --shell=--shell=bash.
    • Trailing spaces: in bash and zsh, only finished candidates get a trailing space. Candidates ending in @, :, / or = (such as node@ or sub/) are left open so you can keep typing.
  • (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 and usage explain still select the default command.
  • (parse) A parent command's non-global flags now have their required, requires and conflicts rules enforced after a subcommand is selected, as the docs describe (#1635, @jdx). Before, x --a --c --d sub passed even though x --a --c --d failed. subcommand_negates_reqs still relaxes required and requires, 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's requires/conflicts rule now fail.
  • (parse) On commands that have subcommands, usage-lib now handles the help subcommand that the help page lists (x help, x help a, x a help) instead of failing with unexpected word: help (#1639, @jdx). On a leaf command, help is now an ordinary word. A command's own help subcommand and disable_help_subcommand still take precedence. Behavior change: if a positional has strict choices that don't include help, the word help is now rejected as an invalid choice instead of showing help.
  • (cli) usage bash and the other script runners now use the script's spec to decide whether -h/--help asks for help (#1637, @jdx). A script with disable_help and its own -h flag, or a flag with allow_hyphen_values that receives -h as its value, now runs instead of printing help. Arguments after -- are also handled correctly.
  • (cli) usage bash, usage exec and delegated completions now report an error if the shell or interpreter can't be started under qemu-user and 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/sh instead 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.