Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Shell Completions

gist-cache-rs supports shell completions for Bash, Zsh, Fish, and PowerShell. This enables auto-completion of commands, subcommands, and options by pressing the Tab key, significantly improving the command-line experience.

Supported Shells

  • Bash - Linux, macOS, Windows (Git Bash, WSL)
  • Zsh - macOS (default), Linux
  • Fish - Linux, macOS
  • PowerShell - Windows, Linux, macOS (PowerShell Core)

Generating Completion Scripts

Use the completions subcommand to generate shell-specific completion scripts:

gist-cache-rs completions <SHELL>

Where <SHELL> is one of: bash, zsh, fish, or powershell.

Before Installation

Backup Your Configuration

Before modifying shell configuration files, it’s recommended to create backups:

Bash:

# Backup .bashrc
cp ~/.bashrc ~/.bashrc.backup

Zsh:

# Backup .zshrc
cp ~/.zshrc ~/.zshrc.backup

Fish:

# Backup Fish config
cp -r ~/.config/fish ~/.config/fish.backup

PowerShell:

# Backup PowerShell profile (if exists)
if (Test-Path $PROFILE) {
    Copy-Item $PROFILE "$PROFILE.backup"
}

Restore from Backup

If something goes wrong, you can restore your configuration:

Bash/Zsh:

# Restore .bashrc or .zshrc
cp ~/.bashrc.backup ~/.bashrc
# or
cp ~/.zshrc.backup ~/.zshrc

# Reload configuration
source ~/.bashrc  # or source ~/.zshrc

Fish:

# Restore Fish config
rm -rf ~/.config/fish
cp -r ~/.config/fish.backup ~/.config/fish

PowerShell:

# Restore PowerShell profile
Copy-Item "$PROFILE.backup" $PROFILE

# Reload profile
. $PROFILE

Installation Instructions

Bash

Linux / macOS:

  1. Generate Completion Script: Create the directory for completions and generate the script.

    # Create the directory if it doesn't exist
mkdir -p ~/.local/share/bash-completion/completions

# Generate and install the completion script
gist-cache-rs completions bash > ~/.local/share/bash-completion/completions/gist-cache-rs

  2. Activate Completions: The bash-completion package should automatically load the script. If completions do not work after starting a new shell session, you may need to source it manually in your ~/.bashrc.

    # Add this line to ~/.bashrc if completions are not loading
echo 'source ~/.local/share/bash-completion/completions/gist-cache-rs' >> ~/.bashrc

    To apply the change immediately, run source ~/.bashrc.

Windows (Git Bash):

# Create completions directory
mkdir -p ~/bash-completion/completions

# Generate completion script
gist-cache-rs completions bash > ~/bash-completion/completions/gist-cache-rs

# Add to ~/.bashrc
echo 'source ~/bash-completion/completions/gist-cache-rs' >> ~/.bashrc

Zsh

macOS / Linux:

# Create completion directory if it doesn't exist
mkdir -p ~/.zfunc

# Generate completion script
gist-cache-rs completions zsh > ~/.zfunc/_gist-cache-rs

Add to your ~/.zshrc (if not already present):

# Add custom completion directory to fpath
fpath=(~/.zfunc $fpath)

# Initialize completion system
autoload -Uz compinit && compinit

Reload your shell or run:

source ~/.zshrc

Fish

Linux / macOS:

Fish automatically loads completion scripts from its completions directory.

# Generate and place the completion script
gist-cache-rs completions fish > ~/.config/fish/completions/gist-cache-rs.fish

The changes will take effect when you start a new Fish session. No additional configuration is needed.

PowerShell

Windows:

  1. Generate Completion Script: First, ensure the target directory exists and then generate the script.

    # Create a directory for PowerShell scripts if it doesn't exist
$scriptDir = ~\Documents\PowerShell\Scripts
if (-not (Test-Path $scriptDir)) {
    New-Item -ItemType Directory -Force -Path $scriptDir
}

# Generate the completion script
gist-cache-rs completions powershell > $scriptDir\gist-cache-rs.ps1

  2. Update PowerShell Profile: Next, add the script to your PowerShell profile to have it load automatically.

    # Create the profile if it doesn't exist
if (-not (Test-Path $PROFILE)) {
    New-Item -Path $PROFILE -ItemType File -Force
}

# Add the script loading command to your profile
Add-Content $PROFILE "`n. $scriptDir\gist-cache-rs.ps1"

  3. Activate Completions: The changes will take effect when you start a new PowerShell session. To apply them immediately in your current session, run:

    . $PROFILE

    Note on Execution Policy: If you encounter an error, your script execution policy might be too restrictive. You can check it with Get-ExecutionPolicy. If it’s Restricted, you may need to change it. For example:

    # This allows locally created scripts to run
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Linux / macOS (PowerShell Core):

# Create scripts directory
mkdir -p ~/.config/powershell/scripts

# Generate completion script
gist-cache-rs completions powershell > ~/.config/powershell/scripts/gist-cache-rs.ps1

# Add to profile
Add-Content $PROFILE "`n. ~/.config/powershell/scripts/gist-cache-rs.ps1"

Configuration Files

After installation, the following files will be created:

Bash

Completion script location:

~/.local/share/bash-completion/completions/gist-cache-rs

Profile configuration (~/.bashrc):

# gist-cache-rs shell completion (if manually added)
source ~/.local/share/bash-completion/completions/gist-cache-rs

Zsh

Completion script location:

~/.zfunc/_gist-cache-rs

Profile configuration (~/.zshrc):

# Add custom completion directory to fpath
fpath=(~/.zfunc $fpath)

# Initialize completion system
autoload -Uz compinit && compinit

Fish

Completion script location:

~/.config/fish/completions/gist-cache-rs.fish

No profile configuration needed - Fish automatically loads completions from this directory.

PowerShell

Completion script location (Windows):

~\Documents\PowerShell\Scripts\gist-cache-rs.ps1

Profile configuration ($PROFILE):

# gist-cache-rs shell completion
. ~\Documents\PowerShell\Scripts\gist-cache-rs.ps1

PowerShell profile location:

  • Windows: ~\Documents\PowerShell\Microsoft.PowerShell_profile.ps1
  • Linux/macOS: ~/.config/powershell/Microsoft.PowerShell_profile.ps1

Verifying Installation

After installation, restart your shell or reload the configuration file to test the completion.

Bash/Zsh (WSL2/Linux/macOS)

Complete subcommands:

$ gist-cache-rs [Tab]
-h           -V           --help       --version
update       run          cache        config       completions  help

Complete options:

$ gist-cache-rs run --[Tab]
--interactive  --preview      --force        --download
--id           --filename     --description  --help

Auto-complete partial input:

gist-cache-rs ru[Tab]
gist-cache-rs run    # ← Auto-completed

View help after completion:

$ gist-cache-rs run --help
Search from cache and execute

Usage: gist-cache-rs run [OPTIONS] [QUERY] [INTERPRETER] [SCRIPT_ARGS]...

Arguments:
  [QUERY]           Search keyword (ID, filename, or description)
  [INTERPRETER]     Interpreter or execution command (bash, python3, uv, etc.)
  [SCRIPT_ARGS]...  Additional arguments to pass to the script

Options:
  -i, --interactive  Interactive script execution mode
  -p, --preview      Preview mode (display content only)
  -f, --force        Update Gist cache before execution
      --download     Save file to download folder
      --id           Direct ID specification mode
      --filename     Search by filename
      --description  Search by description
  -h, --help         Print help

PowerShell (Windows)

Complete subcommands (press Tab after typing):

PS> gist-cache-rs [Tab]
# Cycles through: update, run, cache, config, completions, help, -h, --help, -V, --version

Complete options:

PS> gist-cache-rs run --[Tab]
# Cycles through: --interactive, --preview, --force, --download, --id, --filename, --description, --help

Auto-complete partial input:

PS> gist-cache-rs ru[Tab]
PS> gist-cache-rs run    # ← Auto-completed

Complete cache subcommands:

PS> gist-cache-rs cache [Tab]
# Cycles through: list, size, clean, clear, help

Troubleshooting

Completions Not Working (Bash)

  1. Verify the completion script exists:

    ls -l ~/.local/share/bash-completion/completions/gist-cache-rs

  2. Check if bash-completion is installed:

    # Ubuntu/Debian
sudo apt install bash-completion

# macOS (via Homebrew)
brew install bash-completion@2

  3. Reload your shell:

    source ~/.bashrc

Completions Not Working (Zsh)

  1. Verify compinit is called in ~/.zshrc:

    grep compinit ~/.zshrc

  2. Check the fpath includes your completion directory:

    echo $fpath

  3. Rebuild completion cache:

    rm ~/.zcompdump
compinit

Completions Not Working (Fish)

  1. Verify the completion script exists:

    ls -l ~/.config/fish/completions/gist-cache-rs.fish

  2. Reload Fish completions:

    fish_update_completions

Completions Not Working (PowerShell)

  1. Check execution policy:

    Get-ExecutionPolicy

    If it’s Restricted, change it:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

  2. Verify profile exists and is loaded:

    Test-Path $PROFILE
cat $PROFILE

  3. Reload profile:

    . $PROFILE

Updating Completions

When you update gist-cache-rs to a new version with new commands or options, regenerate the completion scripts using the same installation commands shown above. The new script will overwrite the old one.

Editing Shell Configuration

If you need to modify or review your shell configuration:

Edit Configuration Files

Bash:

# Edit .bashrc with your preferred editor
nano ~/.bashrc
# or
vim ~/.bashrc
# or
code ~/.bashrc  # VS Code

Zsh:

# Edit .zshrc
nano ~/.zshrc
# or
vim ~/.zshrc

Fish:

# Edit Fish config
nano ~/.config/fish/config.fish
# or use Fish's web-based configuration
fish_config

PowerShell:

# Edit PowerShell profile
notepad $PROFILE
# or
code $PROFILE  # VS Code

Verify Configuration Content

Check what was added to your configuration files:

Bash:

# View .bashrc content related to gist-cache-rs
grep -A 2 "gist-cache-rs" ~/.bashrc

Zsh:

# View .zshrc content related to completion setup
grep -A 3 "gist-cache-rs\|compinit" ~/.zshrc

PowerShell:

# View profile content related to gist-cache-rs
Get-Content $PROFILE | Select-String -Pattern "gist-cache-rs" -Context 0,2

Apply Changes

After editing, reload the configuration:

Bash:

source ~/.bashrc

Zsh:

source ~/.zshrc

Fish:

source ~/.config/fish/config.fish

PowerShell:

. $PROFILE

Uninstalling Completions

To remove shell completions:

Bash:

rm ~/.local/share/bash-completion/completions/gist-cache-rs

Zsh:

rm ~/.zfunc/_gist-cache-rs

Fish:

rm ~/.config/fish/completions/gist-cache-rs.fish

PowerShell:

# Windows
Remove-Item ~\Documents\PowerShell\Scripts\gist-cache-rs.ps1

# Linux/macOS
rm ~/.config/powershell/scripts/gist-cache-rs.ps1

Don’t forget to remove the corresponding lines from your shell’s configuration file (.bashrc, .zshrc, or PowerShell profile).