How to Set Up ripgrep Shell Completions for Bash, Zsh, and Fish

Run rg --generate complete-<shell> to output a completion script for Bash, Zsh, or Fish, then install the result to your shell’s completion directory.

ripgrep includes built-in logic to generate shell-specific completion scripts dynamically, ensuring your completions automatically match the exact version installed on your machine. According to the BurntSushi/ripgrep source code, this system sources definitions directly from the FLAGS table in crates/core/flags/defs.rs to produce accurate completion scripts for all three shells.

How ripgrep Generates Shell Completions

The completion system is implemented in the core crate under crates/core/flags/complete/. When you invoke the --generate flag, ripgrep forwards the request to shell-specific generators that parse the FLAGS table defined in crates/core/flags/defs.rs—the same data structure that drives --help output.

The three generators work as follows:

• Bash (crates/core/flags/complete/bash.rs): Renders a function _rg that uses compgen to offer long (--flag) and short (-f) options, plus flag-specific choices when applicable.
• Fish (crates/core/flags/complete/fish.rs): Outputs a script that registers completions via complete -c rg … and expands flag choices.
• Zsh (crates/core/flags/complete/rg.zsh): Provides a hand-written _rg function that mirrors Bash behavior while respecting Zsh completion styles.

User-facing documentation for this feature appears in the Does ripgrep have support for shell auto-completion? section of FAQ.md.

Installing Bash Completions

Create the user-local completion directory and generate the script:

dir="${XDG_CONFIG_HOME:-$HOME/.config}/bash_completion"
mkdir -p "$dir"
rg --generate complete-bash > "$dir/rg.bash"

Then source the file in your ~/.bashrc:

source "$dir/rg.bash"

Installing Zsh Completions

You can install Zsh completions statically or load them dynamically on each session start.

Static Installation

Generate the completion file and place it in a directory added to your fpath:

dir="$HOME/.zsh-complete"
mkdir -p "$dir"
rg --generate complete-zsh > "$dir/_rg"

Add the directory to your fpath in ~/.zshrc before calling compinit:

fpath=($HOME/.zsh-complete $fpath)

Dynamic Loading

To avoid maintaining a separate file, source the generator output directly in ~/.zshrc:

source <(rg --generate complete-zsh)

Installing Fish Completions

Fish automatically loads completions from its configuration directory. Generate the script to the correct location:

dir="${XDG_CONFIG_HOME:-$HOME/.config}/fish/completions"
mkdir -p "$dir"
rg --generate complete-fish > "$dir/rg.fish"

No additional sourcing is required; Fish reads this directory on startup.

Summary

• Bash: Run rg --generate complete-bash and source the output in your ~/.bashrc.
• Zsh: Use rg --generate complete-zsh and place the output in a directory listed in your fpath, or source it dynamically with source <(rg --generate complete-zsh).
• Fish: Run rg --generate complete-fish and save to ~/.config/fish/completions/rg.fish.
• All generators inspect the live FLAGS table in crates/core/flags/defs.rs, ensuring completions match your ripgrep version exactly.

Frequently Asked Questions

Where does ripgrep store its completion scripts?

ripgrep does not store static completion scripts on disk. Instead, it generates them on-demand using logic compiled into the binary from crates/core/flags/complete/bash.rs, fish.rs, and rg.zsh. The generators read the FLAGS table in crates/core/flags/defs.rs to produce scripts that match your specific binary.

Why should I use --generate instead of downloading completion files?

Using rg --generate complete-<shell> guarantees that your completions match the exact version of ripgrep you have installed. Because the generator reads the live flag definitions from crates/core/flags/defs.rs, the output automatically includes any new flags or changes present in your binary without waiting for distribution packages to update.

How do I update completions after upgrading ripgrep?

Simply re-run the generation command for your shell. Since the script is derived from the current binary's internal FLAGS table in crates/core/flags/defs.rs, regenerating ensures immediate access to new options and eliminates version drift between the CLI and your completions.

Can I use these completions with system package managers?

Yes. While the examples above use user-local directories, you can generate fresh completions and copy them to system-wide paths such as /usr/share/bash-completion/completions/ or /usr/share/zsh/site-functions/. This approach ensures system-wide consistency while maintaining synchronization with your ripgrep binary.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}