Skip to content

Add shell auto-completion for the wt command #17

@ukanga

Description

@ukanga

What to build

Add static shell auto-completion for wt covering bash, zsh, fish, and elvish. Completion is generated from the existing clap command tree via clap_complete, exposed through a hidden wt completions <shell> subcommand that prints the script to stdout. install.sh is updated to install the appropriate script into the user's shell completion directory during installation.

End-to-end behaviour after this lands:

  • wt <TAB> completes to the available subcommands (new, use, ls, rm, which, session).
  • wt session <TAB> completes to ls, add, rm, watch.
  • wt session --mode <TAB> completes to panes, windows.
  • Flags (-b, --print-path, --panes, --watch, -d, --dir) complete after their parent subcommand.
  • Long options like wt new --pri<TAB> complete to --print-path.

Because the completion script is generated from the live clap::Command tree, subcommands and flags stay in sync automatically as the CLI evolves — no hand-maintained completion files.

Out of scope (file as follow-ups)

  • Dynamic completion of worktree names for wt use, wt rm, wt session rm (requires shell wrapper functions or clap_complete's unstable dynamic feature).
  • PowerShell support, gated on shipping Windows release binaries.

Implementation notes

  • Add clap_complete = "4" as a dependency.
  • Add a hidden wt completions <shell> subcommand (#[command(hide = true)]) where <shell> is clap_complete::Shell. The handler calls clap_complete::generate against the same root Cli command and writes to stdout.
  • Extend install.sh to install the completion script for the detected shell:
    • bash${BASH_COMPLETION_USER_DIR:-$XDG_DATA_HOME/bash-completion}/completions/wt, falling back to ~/.local/share/bash-completion/completions/wt.
    • zsh → a directory on fpath (e.g. ~/.zsh/completions/_wt); if the dir is not on fpath, append a single guarded fpath=(~/.zsh/completions $fpath) line to ~/.zshrc ahead of any compinit (mirror the existing alias-install idempotency pattern with grep -q).
    • fish~/.config/fish/completions/wt.fish.
    • elvish → document the snippet to add to ~/.config/elvish/rc.elv (elvish loads completions via rc.elv, not from a magic dir).
  • Print a one-line confirmation per shell, mirroring the existing alias-install messaging style.
  • Document wt completions <shell> in the README so users with non-standard setups can pipe it to a custom location.

Acceptance criteria

  • clap_complete is added as a dependency.
  • wt completions <shell> (hidden subcommand) emits a valid completion script for bash, zsh, fish, and elvish to stdout and exits 0.
  • The subcommand does not appear in wt --help.
  • install.sh installs the completion file for the detected shell (bash / zsh / fish) into the correct location and is idempotent (re-running does not append duplicate fpath lines or duplicate completion files).
  • For zsh users whose fpath does not already contain the install directory, install.sh adds the necessary fpath line to ~/.zshrc exactly once, ahead of any existing compinit call.
  • README.md documents (a) automatic install for bash/zsh/fish, (b) the elvish snippet users must add by hand, and (c) the manual wt completions <shell> > <path> escape hatch.
  • An integration test invokes the completions subcommand for each supported shell and asserts the output is non-empty and contains the literal subcommand names (new, use, ls, rm, which, session).
  • PR description records manual verification: in fresh bash, zsh, and fish shells, wt <TAB> lists subcommands and wt session --mode <TAB> lists panes and windows.

Blocked by

None — can start immediately.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions