From c10faab8511a266cf6b2471924ae218206c0633f Mon Sep 17 00:00:00 2001 From: John Coffey Date: Thu, 12 Nov 2026 14:27:40 -0700 Subject: [PATCH] Add completions and man subcommands inbuxa-migrate completions prints a shell completion script (bash, zsh, fish, elvish or powershell) to standard output, and inbuxa-migrate man prints a man page in roff. Both are generated from the command itself and reach no server, archive or logger, so they resolve to their own actions and are handled before anything connects. --- CHANGELOG.md | 5 +++++ Cargo.lock | 27 +++++++++++++++++++++++++++ Cargo.toml | 2 ++ README.md | 14 ++++++++++++++ src/cli.rs | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ src/main.rs | 22 +++++++++++++++++++++- 6 files changed, 118 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b99d801..7169ea2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,11 @@ candidates before a series ships (`27.1-rc.1`). The tag is the version with a ## [Unreleased] +### Added +- `completions ` prints a shell completion script (bash, zsh, fish, + elvish or powershell) to standard output, and `man` prints a man page in + roff. Both are generated from the command itself and reach no server. + ## [27.1-rc.12] The twelfth release candidate of the 27.1 series: upstream v1.0.15, keywords diff --git a/Cargo.lock b/Cargo.lock index 8eee739..d939277 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -462,6 +462,15 @@ dependencies = [ "strsim", ] +[[package]] +name = "clap_complete" +version = "4.6.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "037e2a1a92236d0aff7e845093f64661d6df4c02c9fcc61a60e9e1d736fa392f" +dependencies = [ + "clap", +] + [[package]] name = "clap_derive" version = "4.6.7" @@ -480,6 +489,16 @@ version = "1.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1c133bc6a41be0d194c306b5506d15e6feeea7b1d6604bd3f8310dfb2ca96486" +[[package]] +name = "clap_mangen" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "211d617eaa4b735c96c9e0228fcbdb5120ef623f2b8cb67ffb84c3e02dbc28a4" +dependencies = [ + "clap", + "roff", +] + [[package]] name = "cmake" version = "0.1.58" @@ -1333,6 +1352,8 @@ dependencies = [ "chrono", "chrono-tz", "clap", + "clap_complete", + "clap_mangen", "crossbeam-channel", "encodify", "flate2", @@ -2119,6 +2140,12 @@ dependencies = [ "windows-sys 0.52.0", ] +[[package]] +name = "roff" +version = "1.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "323c417e1d9665a65b263ec744ba09030cfb277e9daa0b018a4ab62e57bc8189" + [[package]] name = "rsqlite-vfs" version = "0.1.1" diff --git a/Cargo.toml b/Cargo.toml index b314870..6d49c4c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -28,6 +28,8 @@ url= "2.5.8" thiserror = "2.0.18" ureq = { version = "3.5.0", default-features = false, features = ["json", "gzip", "rustls-no-provider", "platform-verifier"] } clap = { version = "4.6.1", features = ["derive"] } +clap_complete = "4.6.11" +clap_mangen = "0.3.3" crossbeam-channel = "0.5.15" num_cpus = "1.17.0" encodify = "1.0" diff --git a/README.md b/README.md index 4ee1e3b..b2d9741 100644 --- a/README.md +++ b/README.md @@ -125,6 +125,20 @@ so you can confirm it came from us before trusting the checksums. The same public key signs every inbuxa release (installer, migrate and cli). +## Shell completions and a man page + +`inbuxa-migrate completions ` prints a completion script to standard +output, for `bash`, `zsh`, `fish`, `elvish` or `powershell`. Install it where +the shell looks: + + inbuxa-migrate completions bash > /etc/bash_completion.d/inbuxa-migrate + inbuxa-migrate completions zsh > "${fpath[1]}/_inbuxa-migrate" + inbuxa-migrate completions fish > ~/.config/fish/completions/inbuxa-migrate.fish + +`inbuxa-migrate man` prints a man page, in roff, to standard output: + + inbuxa-migrate man > /usr/share/man/man1/inbuxa-migrate.1 + ## Building and testing cargo build --release the binary is target/release/inbuxa-migrate diff --git a/src/cli.rs b/src/cli.rs index bf57650..c4236b1 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -107,6 +107,21 @@ enum Command { Plan(Box), #[command(about = "Show the contents of a local archive (read-only)")] Inspect(Box), + /// Print a shell completion script to standard output + /// + /// Source it, or install it where the shell looks: + /// bash: inbuxa-migrate completions bash > /etc/bash_completion.d/inbuxa-migrate + /// zsh: inbuxa-migrate completions zsh > "${fpath[1]}/_inbuxa-migrate" + /// fish: inbuxa-migrate completions fish > ~/.config/fish/completions/inbuxa-migrate.fish + Completions { + /// The shell to generate for + #[arg(value_enum)] + shell: clap_complete::Shell, + }, + /// Print a man page, in roff, to standard output + /// + /// inbuxa-migrate man > /usr/share/man/man1/inbuxa-migrate.1 + Man, } #[derive(Subcommand)] @@ -921,6 +936,8 @@ pub enum Action { ExportManageSieve(CommonConfig, ExportManageSieveConfig), ExportDav(CommonConfig, ExportDavConfig), Inspect(InspectConfig), + Completions(clap_complete::Shell), + Man, } impl Action { @@ -1117,6 +1134,8 @@ impl Cli { Command::ExportCaldav(args) => resolve_export_dav(*args, DavKindArg::Caldav), Command::ExportCarddav(args) => resolve_export_dav(*args, DavKindArg::Carddav), Command::Inspect(args) => resolve_inspect(*args), + Command::Completions { shell } => Ok(Action::Completions(shell)), + Command::Man => Ok(Action::Man), } } } @@ -2234,6 +2253,36 @@ mod tests { use super::*; use std::env; + #[test] + fn completions_resolve_to_the_named_shell() { + let cli = Cli::try_parse_from(["inbuxa-migrate", "completions", "bash"]) + .unwrap_or_else(|e| panic!("clap rejected args: {e}")); + assert!(matches!( + cli.resolve().unwrap(), + Action::Completions(clap_complete::Shell::Bash) + )); + let cli = Cli::try_parse_from(["inbuxa-migrate", "completions", "zsh"]) + .unwrap_or_else(|e| panic!("clap rejected args: {e}")); + assert!(matches!( + cli.resolve().unwrap(), + Action::Completions(clap_complete::Shell::Zsh) + )); + } + + #[test] + fn completions_reject_an_unknown_shell() { + assert!(Cli::try_parse_from(["inbuxa-migrate", "completions", "powershellx"]).is_err()); + // The shell is required. + assert!(Cli::try_parse_from(["inbuxa-migrate", "completions"]).is_err()); + } + + #[test] + fn man_resolves() { + let cli = Cli::try_parse_from(["inbuxa-migrate", "man"]) + .unwrap_or_else(|e| panic!("clap rejected args: {e}")); + assert!(matches!(cli.resolve().unwrap(), Action::Man)); + } + #[test] fn parse_duration_reads_units_and_rejects_nonsense() { use std::time::Duration; diff --git a/src/main.rs b/src/main.rs index 5b94cbc..38ca12a 100644 --- a/src/main.rs +++ b/src/main.rs @@ -5,7 +5,7 @@ * SPDX-License-Identifier: Apache-2.0 OR MIT */ -use clap::Parser; +use clap::{CommandFactory, Parser}; use inbuxa_migrate::cli::{Action, Cli}; use inbuxa_migrate::error::Error; @@ -31,6 +31,24 @@ fn run() -> i32 { Err(err) => return fail(&err), }; + // Completions and the man page are generated from the command itself and + // touch no network, archive or logger, so they come before everything else. + match &action { + Action::Completions(shell) => { + let mut cmd = Cli::command(); + let name = cmd.get_name().to_string(); + clap_complete::generate(*shell, &mut cmd, name, &mut std::io::stdout()); + return 0; + } + Action::Man => { + return match clap_mangen::Man::new(Cli::command()).render(&mut std::io::stdout()) { + Ok(()) => 0, + Err(err) => fail(&Error::from(err)), + }; + } + _ => {} + } + let do_estimate = action.estimate_available(); if action.estimate_requested() && !do_estimate { eprintln!( @@ -184,6 +202,8 @@ fn run() -> i32 { Err(err) => fail(&err), }; } + // Handled before the match, above. + Action::Completions(_) | Action::Man => unreachable!(), }; if do_estimate { -- 2.54.0