feat(complete)!: remove the vendored bash-completion copy

[jdx]

Follow-up to #1174, which surfaced this. Stacked on it, so GitHub will retarget this to main when #1174 merges.

lib/bash-completion/bash_completion was a verbatim copy of scop/bash-completion 2.15.0, embedded with include_str! and emitted by --include-bash-completion-lib. It's GPL-2.0-or-later, which meant an MIT-declared usage-lib was redistributing GPL text in its published artifact and in every binary built from it. Since 6.x is going out anyway, this removes it rather than papering over it with an SPDX expression or a feature flag.

Removed: the vendored script, CompleteOptions::include_bash_completion_lib, and the --include-bash-completion-lib flag on usage generate completion.

It also fixes a bug the vendored copy was hiding

CI caught this once the system library stopped being shadowed: ubuntu-latest is 24.04, which ships bash-completion 2.11, and 2.11 defines none of _comp_initialize, _comp_compgen, or _comp_ltrim_colon_completions — those are the 2.12 renames the generated script called. So usage-generated bash completions have never worked on the current LTS unless --include-bash-completion-lib injected the vendored 2.15 copy.

The script now emits the pre-2.12 spellings (_init_completion, __ltrim_colon_completions, plain compgen -W … -- "$cur"), which 2.12+ still support through their compat layer. That covers 2.11 through 2.16 rather than trading one broken range for another, and it is verified end to end against real libraries at both ends. CI stays on 24.04's 2.11 deliberately — it is the floor being claimed, and 26.04's 2.16 would pass either way.

The generated script already required bash-completion

Worth being explicit about, because it makes this less of a functional loss than it looks: the completion body calls _comp_initialize, _comp_compgen and _comp_ltrim_colon_completions. Those come from bash-completion. So anyone who generated a completion without the flag already needed it installed — the flag was a convenience for self-contained scripts, not the thing that made bash completions work.

What changes is that it's now the only path, so the generated script says so in a header comment and guards for it, in the same shape as the existing "usage CLI not found" guard:

Error: bash-completion 2.12+ is required for testcli completions but was not loaded.
Install it from your package manager and source it before this script.

Previously that state surfaced as _init_completion: command not found.

Tests and CI

test_bash_completion_integration sources the system bash-completion instead of the embedded copy. Finding it is a new bash_completion_or_skip, which panics under CI for the same reason skip_if_shell_missing does — a bash suite that quietly skipped its only end-to-end completion test would report green having exercised nothing. The workflow's apt step installs bash-completion to keep that honest.

Verified locally both ways: with a real bash-completion 2.16 on the search path and CI=1, the test runs and completes (GOT_COMPLETIONS, COMPLETION_SUB_FOUND); without one and CI=1, it panics rather than skipping.

New test_bash_guard_reports_missing_bash_completion covers the guard, including that it fires before bash reports a missing function.

Downstream note

mise's own mise completion bash --include-bash-completion-lib passes this option through, and mise's help text recommends that invocation. It'll need updating when mise moves to usage 6.x — flagging it since it's the one known caller.

mise run lint, mise run render, and cargo test -p usage-lib -p usage-cli -p usage-conformance --all-features are clean. cargo package -p usage-lib --list no longer contains any bash-completion file. No version fields touched.

This PR description was generated by Claude Code.

---

Note

Medium Risk
Breaking public API: generated bash completions no longer embed bash-completion, and --include-bash-completion-lib is removed. Downstream CLIs (notably mise) and users without a system bash-completion will need to update.

Overview
Stops shipping a GPL copy of bash-completion inside the MIT crate. Generated bash scripts now expect the system library to be sourced first.

Removes --include-bash-completion-lib and CompleteOptions::include_bash_completion_lib. The generated script guards for _init_completion with a clear error instead of command not found.

Also switches the generated helpers to the pre-2.12 names (_init_completion, __ltrim_colon_completions, compgen -W) so completions work on Ubuntu 24.04’s bash-completion 2.11, which the vendored 2.15 copy had been hiding. CI installs the distro package and tests against that floor; a new test covers the missing-library guard.

^{Reviewed by Cursor Bugbot for commit 8db85bb. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: cc389014-b3a2-4516-a210-b1ad8f3dad68

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁█▇▇▇▅	226,070,483 → 223,712,148	-1.04%	22.04 → 21.60ms	-1.97%
startup	▁▃▄▄█▃	1,225,801 → 1,224,954	-0.07%	1.46 → 1.42ms	-2.88%

No instruction-count regression above 1%.

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

Shadow comparison

Parsing mise use -g node@20 against a shadow of mise's committed spec.
Reported, not gated: the shadow grows as the derive learns to express more, so
what to watch is the ratio rather than either column.

framework	instructions, cold parse	vs usage
usage	8315	—
argh	6307	0.8x
clap	6316072	759x
bpaf	21909147	2634x

                                              min       p01       p10    median
usage-rs: argv -> struct                      435       439       445       457  ns
argh: argv -> struct                          272       278       283       290  ns
clap: build tree + parse -> struct         534973    536158    540842    550705  ns
bpaf: build parser + parse -> struct      1624362   1624362   1640353   1674347  ns

usage: argv -> struct                             423 ns      0.42 µs
clap: build tree + parse -> struct             554825 ns    554.83 µs
clap: parse -> struct, tree reused              23126 ns     23.13 µs
clap: build tree only                          338768 ns    338.77 µs

_{50b71b3fa4e2 vs 2c4a1c0b7621 · measured on the runner, not pushed to the history.}

[jdx]

CI found a real bug behind the vendored copy

Worth calling out, because it changes what this PR does. The first CI run after the vendored script stopped shadowing the system one failed like this:

no usable bash-completion but CI is set — refusing to skip. Tried: ["/usr/share/bash-completion/bash_completion", …]

ubuntu-latest is 24.04, which ships bash-completion 2.11 (1:2.11-8 — already installed, so the apt line I added was a no-op). 2.11 defines none of _comp_initialize, _comp_compgen, or _comp_ltrim_colon_completions; those are the 2.12 renames, and they're exactly what the generated completion called.

So usage-generated bash completions have never worked on Ubuntu 24.04 LTS — supported until 2029 — unless --include-bash-completion-lib injected the vendored 2.15 copy. The bundled script wasn't just saving users an install; it was hiding an incompatibility with the current LTS. Removing it as originally written would have shipped that as a regression to everyone.

Fix

Emit the pre-2.12 spellings: _init_completion -n :, __ltrim_colon_completions, and a plain compgen -W … -- "$cur" for _comp_compgen. 2.12 kept the old names working through its compat layer (bash_completion.d/000_bash_completion_compat.bash, loaded by the main library, no runtime deprecation warning), so this covers 2.11 and everything after it rather than trading one broken range for another.

Verified end to end against real libraries at both ends — 2.11 and 2.16 — with subcommand, partial, and flag completion asserted on each.

On the runner version

ubuntu-26.04 is available as a public preview and ships 2.16, so switching the runner would also have turned CI green — with no code change and no fix. CI deliberately stays on 24.04's 2.11: it's the floor the generated script now claims, so testing it is the point. 26.04 would pass either way, which is exactly why it's the wrong thing to test on.

The discovery helper also probes each candidate by sourcing it and checking for the function, rather than trusting a path — which is what turned this from a mysterious assertion failure into a legible one.

This comment was generated by Claude Code.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 9db8b03. Configure here.}