jdx/usage v7.3.0

v7.3.0: Shared `completion` subcommand for usage-rs CLIs

on GitHub

usage-rs now ships a ready-made completion subcommand. Every CLI built on it can mount the command, so they all print and install shell completions the same way.

Added

• (lib) New usage_rs::completion::Completion subcommand, available with the completions feature (#1624, @jdx). Until now each tool wrote its own completion command: some had --install, while others printed a script for the user to redirect by hand. You can now mount the shared command instead:

  use usage_rs::completion::Completion;
  
  #[derive(Subcommands)]
  enum Commands {
      /// Generate shell completions
      Completion(Completion),
  }
  
  // in the run function:
  completion.run("ex", &mut std::io::stdout())?;

  Any tool that mounts it gets these commands:

  ex completion fish                     # print the script, e.g. `ex completion fish | source`
  ex completion fish --install           # write it where fish looks for it
  ex completion fish --install --force   # also replace a file usage did not generate
  

  • Shells: bash, elvish, fish, nu/nushell, powershell/pwsh and zsh are accepted. Any other shell name fails to parse.
  • Flags: --force requires --install.
  • Scripts: The scripts are the short callback scripts. They contain no spec and don't need the usage binary. On every Tab they ask the installed tool for candidates, so they stay correct when the tool is upgraded.
  • Installing: --install never edits a startup file. If a shell needs a line added once, the command prints that line after the install path.
  • Errors: Completion::run returns Error::Install or Error::Output. A closed pipe (for example ex completion zsh | head) is not treated as an error.
  • Testing: Completion::run_in takes an explicit Env, so tests can install without touching the real home directory.

  The Rust completions guide (docs/rust/completions.md) now uses Completion in place of the hand-written example.

Full Changelog: v7.2.0...v7.3.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.