Fix shell completion installation instructions - #126
Conversation
The previous instructions for bash and zsh failed on Linux because they
write to system directories without proper root access. Shell redirection
(>) is executed by the current shell, not by sudo, so commands like:
$ bcq completion bash > /etc/bash_completion.d/bcq
fail with "Permission denied" even when prefixed with sudo.
This follows the approach used by GitHub CLI (gh):
- Recommend user-local eval method as the primary approach
- Provide system-wide installation as an alternative with correct
`| sudo tee` syntax for Linux
For zsh, replaced the problematic `${fpath[1]}` instruction (which often
points to a system directory) with a user-local ~/.zsh/completions approach.
The eval and fpath approaches have different ordering requirements relative to compinit. Annotate each option and add source <(...) to top-level help for parity with Bash.
jeremy
left a comment
There was a problem hiding this comment.
Two things to tighten up in the Zsh completion instructions — both the top-level completion --help and the completion zsh --help subcommand:
1. compinit ordering is ambiguous (medium)
The eval and fpath approaches have different ordering requirements relative to compinit, but the instructions don't mention this. Users who put eval before compinit or fpath after it will get silent failures.
Fix: annotate each option — eval goes "AFTER compinit", fpath goes "BEFORE compinit" — and expand the fpath block to show the full ~/.zshrc snippet including autoload -U compinit; compinit.
2. Top-level help missing source <(...) for Zsh (low)
The Bash section in top-level help starts with source <(bcq completion bash) for testing in the current session, but the Zsh section jumps straight to persistent install. Adding source <(bcq completion zsh) keeps parity and gives users a quick way to test before committing to a config change.
Both fixes pushed as b111262.
* Fix shell completion installation instructions for Linux
The previous instructions for bash and zsh failed on Linux because they
write to system directories without proper root access. Shell redirection
(>) is executed by the current shell, not by sudo, so commands like:
$ bcq completion bash > /etc/bash_completion.d/bcq
fail with "Permission denied" even when prefixed with sudo.
This follows the approach used by GitHub CLI (gh):
- Recommend user-local eval method as the primary approach
- Provide system-wide installation as an alternative with correct
`| sudo tee` syntax for Linux
For zsh, replaced the problematic `${fpath[1]}` instruction (which often
points to a system directory) with a user-local ~/.zsh/completions approach.
* Make compinit ordering explicit in Zsh completion help
The eval and fpath approaches have different ordering requirements
relative to compinit. Annotate each option and add source <(...)
to top-level help for parity with Bash.
---------
Co-authored-by: Jeremy Daer <jeremy@37signals.com>
Summary
sudo tee(direct>redirect fails without root)eval "$(bcq completion <shell>)"option for ~/.bashrc and ~/.zshrc${fpath[1]}/_bcqwith user-writable~/.zsh/completionsdirectory for zshWhy
The original instructions didn't work on Linux without sudo, and the zsh fpath approach assumed the first fpath directory was user-writable (often not the case).
Fixes #124