Shell completions, man pages, and help for every argument d42369abf180

oxy completions bash|zsh|fish|elvish|powershell prints a completion
script and oxy man writes a page per command (104 of them) or prints
oxy.1, both generated from the command definitions. The oh-my-bash
plugin loads the bash completions.

Help text now covers every command and argument (112 were bare, such as
commit's --message and every --json), and a test keeps it that way, so
--help, completions and man pages stay complete. The guide shows how to
install them.

Author: Andy McCall @andymccall <[email protected]>
When: 1 month ago · 2026-09-28 08:51 UTC
Signature: ✔ signed by Andy McCall
Hash: d42369abf1808edc68cfa051eca7024328f39d9732923c52053dca4bdf6a5a65
Depends on: 05e71ed6cdf1 1196b29b5fa9 132b884b9a8d 135212de5370 23b217d75848 252e8cb23fbc 2863456a0f6d 28fc23d7706a 30ea9c1e70fa 387335ff7f4d 3e5772ccf9da 4dee277c327a 4e88e774777a 614541c3cebd 694805cca585 728da0f92161 7421309f5372 750251b21a96 75167672ebcd 7aa2dc9369e3 7b9809e67c3d 83e0677b07fe 957fee30826e b3c5a59a875a c3069537d7c5 c6aa5bd9d1c8 cdb5beba7f05 d82e44097323 e02bf0cd0533 e993a086c13f ee06a6c557b7 fce44ae9ad29 ff0af1ee299d
Depended on by: 284fe47d98b9 9bd98cfb4f7e 157d02e95586 b63fc7a77fc6 0299076f09a2 733ea16a9701 e59512f2f075 a39754d02c58 b582948f1912 bf3a67819b59 d069701a4997 614f55e14eee 2c9ddac3c387 7ba155f20aa0 f874dc8659c2 9aa399044d9d 98a1620a3840 14edbaaf5291 ff1f62fee654 e0d56dfca51d 06d16dc2bc13 4fe7d6045860 83d61e803ccd 6a81dbab471d f8c695764c95 e3d071cecfe2 99e3e0af08df
In bookmarks: agents-in-readme bare-hashes carried-not-removed carry-identical doctor-trust identical-sides keyless-tags main merge-remote-bookmark only-help-103 paths-for-resolutions-and-amend push-notes show-stat subrepo-pin-state switch-says
In tags: v0.1.0 v0.10.0 v0.11.0 v0.2.0 v0.3.0 v0.3.1 v0.4.0 v0.4.1 v0.4.2 v0.4.3 v0.4.4 v0.4.5 v0.4.6 v0.5.0 v0.5.1 v0.6.0 v0.7.0 v0.8.0 v0.9.0
Edits: 121 atoms, 1 tree operation, 7 files

Browse the tree at this change

hide whitespace changes

added tests/cli_docs.rs +69 −0

modified Cargo.lock +27 −0

modified Cargo.toml +2 −0

modified contrib/oh-my-bash/oxy.sh +6 −0

modified docs/guide.md +11 −0

modified docs/spec.md +1 −0

modified src/cli/mod.rs +246 −17

1	+	//! Shell completions and man pages come from the command definitions.
2	+
3	+	use std::process::Command;
4	+
5	+	fn oxy(args: &[&str]) -> (bool, String) {
6	+	let out = Command::new(env!("CARGO_BIN_EXE_oxy"))
7	+	.args(args)
8	+	.env("NO_COLOR", "1")
9	+	.output()
10	+	.unwrap();
11	+	(
12	+	out.status.success(),
13	+	String::from_utf8_lossy(&out.stdout).into_owned(),
14	+	)
15	+	}
16	+
17	+	#[test]
18	+	fn completions_for_each_shell() {
19	+	for (shell, marker) in [
20	+	("bash", "_oxy()"),
21	+	("zsh", "#compdef oxy"),
22	+	("fish", "complete -c oxy"),
23	+	("powershell", "Register-ArgumentCompleter"),
24	+	] {
25	+	let (ok, text) = oxy(&["completions", shell]);
26	+	assert!(ok, "{shell}");
27	+	assert!(
28	+	text.contains(marker),
29	+	"{shell}: {}",
30	+	&text[..text.len().min(200)]
31	+	);
32	+	assert!(
33	+	text.contains("commit") && text.contains("doctor"),
34	+	"{shell} knows the commands"
35	+	);
36	+	}
37	+	assert!(
38	+	!oxy(&["completions", "tcsh"]).0,
39	+	"an unknown shell is refused"
40	+	);
41	+	}
42	+
43	+	#[test]
44	+	fn man_pages_for_every_command() {
45	+	let dir = tempfile::tempdir().unwrap();
46	+	let (ok, _) = oxy(&["man", "--dir", &dir.path().to_string_lossy()]);
47	+	assert!(ok);
48	+	for page in [
49	+	"oxy.1",
50	+	"oxy-commit.1",
51	+	"oxy-remote-add.1",
52	+	"oxy-identity-delegate-add.1",
53	+	"oxy-doctor.1",
54	+	] {
55	+	let text = std::fs::read_to_string(dir.path().join(page))
56	+	.unwrap_or_else(\|_\| panic!("{page} missing"));
57	+	assert!(
58	+	text.starts_with(".ie") \|\| text.contains(".TH"),
59	+	"{page} is roff"
60	+	);
61	+	}
62	+	let commit = std::fs::read_to_string(dir.path().join("oxy-commit.1")).unwrap();
63	+	assert!(
64	+	commit.contains("subject line"),
65	+	"argument help reaches the page"
66	+	);
67	+	let (ok, top) = oxy(&["man"]);
68	+	assert!(ok && top.contains(".TH oxy"), "oxy man prints the top page");
69	+	}

		…	330 unchanged lines
331	331		]
332	332
333	333		[[package]]
	334	+	name = "clap_complete"
	335	+	version = "4.6.11"
	336	+	source = "registry+https://github.com/rust-lang/crates.io-index"
	337	+	checksum = "037e2a1a92236d0aff7e845093f64661d6df4c02c9fcc61a60e9e1d736fa392f"
	338	+	dependencies = [
	339	+	"clap",
	340	+	]
	341	+
	342	+	[[package]]
334	343		name = "clap_derive"
335	344		version = "4.6.7"
336	345		source = "registry+https://github.com/rust-lang/crates.io-index"
		…	12 unchanged lines
349	358		checksum = "1c133bc6a41be0d194c306b5506d15e6feeea7b1d6604bd3f8310dfb2ca96486"
350	359
351	360		[[package]]
	361	+	name = "clap_mangen"
	362	+	version = "0.3.3"
	363	+	source = "registry+https://github.com/rust-lang/crates.io-index"
	364	+	checksum = "211d617eaa4b735c96c9e0228fcbdb5120ef623f2b8cb67ffb84c3e02dbc28a4"
	365	+	dependencies = [
	366	+	"clap",
	367	+	"roff",
	368	+	]
	369	+
	370	+	[[package]]
352	371		name = "cmov"
353	372		version = "0.5.4"
354	373		source = "registry+https://github.com/rust-lang/crates.io-index"
		…	849 unchanged lines
1204	1223		dependencies = [
1205	1224		"anyhow",
1206	1225		"clap",
	1226	+	"clap_complete",
	1227	+	"clap_mangen",
1207	1228		"console",
1208	1229		"indicatif",
1209	1230		"libc",
		…	211 unchanged lines
1421	1442		]
1422	1443
1423	1444		[[package]]
	1445	+	name = "roff"
	1446	+	version = "1.1.1"
	1447	+	source = "registry+https://github.com/rust-lang/crates.io-index"
	1448	+	checksum = "323c417e1d9665a65b263ec744ba09030cfb277e9daa0b018a4ab62e57bc8189"
	1449	+
	1450	+	[[package]]
1424	1451		name = "rustc_version"
1425	1452		version = "0.4.1"
1426	1453		source = "registry+https://github.com/rust-lang/crates.io-index"
		…	946 unchanged lines

		…	428 unchanged lines
429	429		another. Nothing to fix; the state is their union.
430	430		- Undo anything: `oxy undo` reverts the last operation, including
431	431		pulls, checkouts, and rewrites.
	432	+
	433	+	## Shell completions and man pages
	434	+
	435	+	```sh
	436	+	oxy completions bash > ~/.local/share/bash-completion/completions/oxy # bash
	437	+	oxy completions zsh > "${fpath[1]}/_oxy" # zsh
	438	+	oxy completions fish > ~/.config/fish/completions/oxy.fish # fish
	439	+	oxy man --dir ~/.local/share/man/man1 # then: man oxy-commit
	440	+	```
	441	+
	442	+	The oh-my-bash plugin in `contrib/oh-my-bash` loads the bash completions itself.

		…	852 unchanged lines
853	853		oxy root oxy cat PATH [-r CHANGE] oxy version
854	854		oxy fsck [--json] check integrity (§21.1)
855	855		oxy doctor [--offline] [--json] check identity, config and remotes (§21.2)
	856	+	oxy completions SHELL shell completion script oxy man [--dir DIR] man pages
856	857		oxy hunks oxy discard PATH.. \| --hunks N,M
857	858		```
858	859
		…	141 unchanged lines

`/`	Search
`g` `c`	Code
`g` `h`	History
`g` `b`	Bookmarks
`g` `t`	Trust
`y`	Permalink to this state (files and trees)
`?`	This sheet

		…	27 unchanged lines
28	28		console = "0.15"
29	29		indicatif = "0.17"
30	30		serde_json = "1"
	31	+	clap_complete = "4"
	32	+	clap_mangen = "0.3"
31	33
32	34		[dev-dependencies]
33	35		tempfile = "3"

		…	37 unchanged lines
38	38		fi
39	39		_omb_util_print "${OXY_CHAR}${bookmark} ${change} ${glyph}${up}${down}\|${color}"
40	40		}
	41	+
	42	+	# Tab completion for oxy's commands and options.
	43	+	if command -v oxy >/dev/null 2>&1; then
	44	+	# shellcheck disable=SC1090
	45	+	source <(oxy completions bash 2>/dev/null)
	46	+	fi

		…	30 unchanged lines
31	31		enum Cmd {
32	32		/// Create a repository in PATH (default: current directory)
33	33		Init {
	34	+	/// Directory to create the repository in (default: the current directory)
34	35		path: Option<PathBuf>,
35	36		/// No working copy: an object store and references only, for hosting
36	37		#[arg(long)]
		…	1 unchanged lines
38	39		},
39	40		/// Clone a repository from a local path or an http(s) URL
40	41		Clone {
	42	+	/// Local path or http(s) URL of the repository
41	43		url: String,
	44	+	/// Directory to clone into (default: the last part of the URL)
42	45		dest: Option<PathBuf>,
43	46		/// Leave blobs larger than this (e.g. 1M) to be fetched on first read
44	47		#[arg(long)]
		…	7 unchanged lines
52	55		},
53	56		/// Fetch more history below a shallow clone's boundary
54	57		Deepen {
	58	+	/// Levels of history to add below the boundary
55	59		#[arg(default_value_t = 10)]
56	60		depth: u32,
	61	+	/// Remote to fetch the history from
57	62		#[arg(long, default_value = "origin")]
58	63		remote: String,
59	64		},
60	65		/// Show or set the sparse filter (paths to materialize); re-checks out the bookmark
61		-	Sparse { paths: Vec<String> },
	66	+	Sparse {
	67	+	/// Paths to materialize; none prints the current filter
	68	+	paths: Vec<String>,
	69	+	},
62	70		/// Show the working copy: changed paths and conflicts
63	71		Status {
64	72		/// Machine-readable output: paths, and every conflict with its kind and contributing changes
		…	14 unchanged lines
79	87		},

Shell completions, man pages, and help for every argument d42369abf180

Keyboard