fix(zsh): escape colons in completion insert strings by davidolrik · Pull Request #670 · jdx/usage

davidolrik · 2026-06-07T09:55:31Z

Problem

Completing values that contain colons — e.g. a mise task named chezmoi:brew:dump — truncates at the first colon:

mise run chez<TAB>        # → "mise run chezmoi"   (expected "mise run chezmoi:")
mise run chezmoi:b<TAB>   # → reverts to "mise run chezmoi"   (expected "mise run chezmoi:brew:")

The backend output is correct — display column escaped, insert column raw:

$ usage complete-word --shell zsh -f mise.spec -- mise run chezmoi:b
chezmoi\:brew\:commit:🍻 Commit Brewfile changes	chezmoi:brew:commit
chezmoi\:brew\:dump:🍻 Dump list of currently installed apps into Brewfile	chezmoi:brew:dump

But zsh's _describe parses candidate:description in both arrays it receives, so every insert string collapses to candidate chezmoi with brew:dump treated as its description. Completion then inserts the truncated value, and because matches are added with -U (replace the current word), the next <TAB> destroys what the user already typed past the colon.

Fix

Escape colons in the insert strings in the zsh completion loop, mirroring the escaping the display column already gets:

inserts+=("${insert//:/\\:}")

Verified with a zpty completion harness against mise task names:

input	before	after
`mise run chez<TAB>`	`mise run chezmoi`	`mise run chezmoi:`
`mise run chezmoi:b<TAB>`	`mise run chezmoi` (revert!)	`mise run chezmoi:brew:`
`mise run chezmoi:c<TAB>`	`mise run chezmoi` (revert!)	`mise run chezmoi:cleanup`

Related to but distinct from #558 / the v3.x _describe migration — that covered the display side; this is the insert side.

Changes

lib/src/complete/zsh.rs — escape colons in render_completion_loop (covers both the per-bin script and the shebang-fallback handler), plus a doc comment explaining why
snapshots updated via cargo insta test --accept
cli/assets/completions/_usage re-rendered via mise run render

cargo test --all --all-features and mise run lint pass.

Summary by CodeRabbit

Bug Fixes
- Fixed Zsh shell completion to properly handle values containing colon characters, preventing parsing issues during completion generation.

_describe parses candidate:description in both the display and the insert array, so colons in insert strings must be escaped like the display column already is. Without this, completing a value containing colons (e.g. a mise task named chezmoi:brew:dump) truncates at the first colon, and with -U the next <Tab> replaces text the user already typed past the colon.

coderabbitai · 2026-06-07T09:55:42Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: dbd0fedc-a594-4f1f-bc9c-a80a9337051c

📥 Commits

Reviewing files that changed from the base of the PR and between f1d6e61 and e3bc523.

⛔ Files ignored due to path filters (4)

lib/src/complete/snapshots/usage__complete__zsh__tests__complete_zsh-2.snap is excluded by !**/*.snap
lib/src/complete/snapshots/usage__complete__zsh__tests__complete_zsh-3.snap is excluded by !**/*.snap
lib/src/complete/snapshots/usage__complete__zsh__tests__complete_zsh.snap is excluded by !**/*.snap
lib/src/complete/snapshots/usage__complete__zsh__tests__complete_zsh_init.snap is excluded by !**/*.snap

📒 Files selected for processing (2)

cli/assets/completions/_usage
lib/src/complete/zsh.rs

📝 Walkthrough

Walkthrough

The PR fixes Zsh completion parsing by escaping colon characters (:) in completion insert strings. When _describe parses candidate:description pairs, colons within insert values would truncate results unexpectedly. The fix adds colon escaping in the Rust code generator and updates the static completion template consistently.

Changes

Zsh Completion Colon Escaping

Layer / File(s)	Summary
Escape colons in completion insert strings `lib/src/complete/zsh.rs`, `cli/assets/completions/_usage`	Documentation comments explain that `_describe` expects `candidate:description` format and colons in insert strings must be escaped. The Rust code generator transforms inserts via `${insert//:/\\:}` before storing in the `inserts` array. The static completion template is updated to reflect the same escaping.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰 A colon crept into completion strings,
Breaking the parse with subtle stings.
We escaped it well with backslash care,
Now _describe works beyond compare! 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically summarizes the main change: escaping colons in Zsh completion insert strings to fix a truncation issue.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

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

greptile-apps · 2026-06-07T09:56:55Z

Greptile Summary

This PR fixes a zsh completion regression where values containing colons (e.g. chezmoi:brew:dump) were truncated at the first colon during insertion, because _describe parses candidate:description syntax in both its display and insert arrays.

lib/src/complete/zsh.rs: render_completion_loop now escapes colons in insert strings via ${insert//:/\\:}, mirroring what the display column already received from the backend; a doc comment explains the _describe parsing behaviour. The change is applied to a single shared template that covers both the per-bin script and the shebang-fallback handler.
cli/assets/completions/_usage and all four insta snapshots are regenerated consistently to match the source change.

Confidence Score: 5/5

Safe to merge — the change is a one-line fix in a single shared template, all snapshots and the pre-rendered asset are updated consistently, and the author verified the fix with a zpty harness against real colon-containing task names.

The fix is minimal and targeted: one string-substitution expression in one template function that is the single source of truth for the completion loop. All generated artifacts (snapshots, pre-rendered _usage script) are consistently updated. For values without colons the substitution is a no-op, so there is no regression risk for existing users. For values with colons the : escaping is the documented way to pass literal colons through _describe's candidate:description parser.

No files require special attention.

Important Files Changed

Filename	Overview
lib/src/complete/zsh.rs	Core fix: escapes colons in insert strings via `${insert//:/\:}` so `_describe` doesn't parse them as `candidate:description` separators; includes a helpful doc comment explaining the root cause
cli/assets/completions/_usage	Pre-rendered completion script re-generated to include the same colon-escaping fix applied in the source template
lib/src/complete/snapshots/usage__complete__zsh__tests__complete_zsh.snap	Snapshot updated to reflect the colon-escaping change in the generated completion loop
lib/src/complete/snapshots/usage__complete__zsh__tests__complete_zsh_init.snap	Init-script snapshot updated to reflect the colon-escaping change in the shebang-fallback handler
lib/src/complete/snapshots/usage__complete__zsh__tests__complete_zsh-2.snap	Snapshot updated to reflect the colon-escaping change (cache-key variant)
lib/src/complete/snapshots/usage__complete__zsh__tests__complete_zsh-3.snap	Snapshot updated to reflect the colon-escaping change (kitchen-sink spec variant)

_{Reviews (2): Last reviewed commit: "Merge branch 'main' into fix/zsh-colon-i..." | Re-trigger Greptile}

github-actions · 2026-06-08T00:36:35Z

This PR currently has failing checks. If this continues for 7 days, it will be closed automatically.

This is warning day 1 of 7.

Please update the PR when you have a chance. Feel free to reopen or create a new PR if it is closed and you'd like to continue working on it.

This comment was generated by an automated workflow.

davidolrik · 2026-06-08T11:54:38Z

This PR currently has failing checks. If this continues for 7 days, it will be closed automatically.

This is warning day 1 of 7.

Please update the PR when you have a chance. Feel free to reopen or create a new PR if it is closed and you'd like to continue working on it.

This PR is failing due to a public key issue in Codecov, which I can't do anything about.

Merge branch 'main' into fix/zsh-colon-insert-escape

eba3c40

jdx merged commit 19cc114 into jdx:main Jun 8, 2026
5 checks passed

coderabbitai Bot mentioned this pull request Jun 9, 2026

fix(zsh): show all matches when subcommand names contain : #666

Merged

3 tasks

BrewTestBot mentioned this pull request Jun 11, 2026

usage 3.5.0 Homebrew/homebrew-core#287404

Merged

jdx mentioned this pull request Jun 11, 2026

fix(completions): require usage 3.5 jdx/mise#10313

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(zsh): escape colons in completion insert strings#670

fix(zsh): escape colons in completion insert strings#670
jdx merged 2 commits into
jdx:mainfrom
davidolrik:fix/zsh-colon-insert-escape

davidolrik commented Jun 7, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 7, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

greptile-apps Bot commented Jun 7, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jun 8, 2026

Uh oh!

davidolrik commented Jun 8, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

davidolrik commented Jun 7, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Fix

Changes

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

greptile-apps Bot commented Jun 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Uh oh!

github-actions Bot commented Jun 8, 2026

Uh oh!

davidolrik commented Jun 8, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

davidolrik commented Jun 7, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 7, 2026 •

edited

Loading

greptile-apps Bot commented Jun 7, 2026 •

edited

Loading