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

Installation Guide

Prerequisites

Required

  • Rust toolchain (1.85 or later)

    Linux / macOS:

    rustc --version  # Verify

    Installation method:

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

    Windows:

    rustc --version  # Verify

    Installation method: Download from rustup.rs

  • GitHub CLI (gh) - Authenticated

    Linux / macOS:

    gh --version     # Verify
gh auth status   # Check authentication status

    Windows:

    gh --version     # Verify
gh auth status   # Check authentication status

    Authentication method:

    gh auth login

    Installation: GitHub CLI

  • Git (for repository cloning)

Installation Methods

Interactively performs all steps.

Linux / macOS

# Clone the repository
git clone https://github.com/7rikazhexde/gist-cache-rs.git
cd gist-cache-rs

# Run the setup script
./script/setup.sh install

Actions performed:

  1. ✅ Prerequisite check
  2. 📁 Project directory detection
  3. 🔨 Release build
  4. 📦 Select installation method
  5. ⚙️ Perform installation
  6. ⚙️ Configuration file setup (optional - v0.8.7+)
    • Interactive interpreter selection for each file extension
    • Python (.py): uv or python3
    • Ruby (.rb): ruby
    • JavaScript (.js): node
    • TypeScript (.ts): ts-node, deno, or bun
    • Shell (.sh): bash, sh, or zsh
    • PHP (.php): php
    • Perl (.pl): perl
    • PowerShell (.ps1): pwsh
    • Fallback (*): bash, python3, or sh
  7. 🔄 Initial cache creation
  8. ⌨️ Alias setup (optional)

Windows

# Clone the repository
git clone https://github.com/7rikazhexde/gist-cache-rs.git
cd gist-cache-rs

# Run the setup script
.\script\setup.ps1 install

Actions performed:

  1. ✅ Prerequisite check (Rust, GitHub CLI)
  2. 🔨 Release build
  3. 📦 Perform cargo install
  4. ⚙️ Configuration file setup (optional - v0.8.7+)
    • Interactive interpreter selection for each file extension
    • Python (.py): uv or python3
    • Ruby (.rb): ruby
    • JavaScript (.js): node
    • TypeScript (.ts): ts-node, deno, or bun
    • Shell (.sh): bash, sh, or zsh
    • PHP (.php): php
    • Perl (.pl): perl
    • PowerShell (.ps1): pwsh
    • Fallback (*): bash, python3, or sh
  5. 🔄 Initial cache creation (optional)

Installation location:

  • Binary: %USERPROFILE%\.cargo\bin\gist-cache-rs.exe
  • Cache: %LOCALAPPDATA%\gist-cache\

Method 2: cargo install (All platforms)

cargo build --release
cargo install --path .

Installation location:

  • Linux/macOS: ~/.cargo/bin/gist-cache-rs
  • Windows: %USERPROFILE%\.cargo\bin\gist-cache-rs.exe

PATH setting:

Linux / macOS: Usually set automatically. If not set:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.cargo/bin:$PATH"
source ~/.bashrc

Windows: Cargo’s bin directory is automatically added to PATH. If not set:

  1. Open “Edit the system environment variables”
  2. Click “Environment Variables…” button
  3. Edit “Path” under User variables
  4. Add %USERPROFILE%\.cargo\bin

Method 3: System directory

cargo build --release
sudo cp target/release/gist-cache-rs /usr/local/bin/

Installation location: /usr/local/bin/gist-cache-rs Feature: Shared by all users, requires sudo privileges

Method 4: User directory

cargo build --release
mkdir -p ~/bin
cp target/release/gist-cache-rs ~/bin/

Installation location: ~/bin/gist-cache-rs

PATH setting:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/bin:$PATH"
source ~/.bashrc

cargo build --release

# Link to /usr/local/bin (requires sudo)
sudo ln -sf "$(pwd)/target/release/gist-cache-rs" /usr/local/bin/gist-cache-rs

# Or link to ~/bin
mkdir -p ~/bin
ln -sf "$(pwd)/target/release/gist-cache-rs" ~/bin/gist-cache-rs

Feature: Automatically reflected after build, convenient for development

Post-Installation Setup

If you didn’t set up configuration during installation, you can configure it anytime:

Interactive Setup (Recommended):

# Use interactive configuration with cursor-based UI
gist-cache-rs config setting

This will guide you through:

  • Selecting interpreters for each file extension (.py, .rb, .js, .ts, .sh, .php, .pl, .ps1)
  • Setting fallback interpreter for unknown extensions (*)
  • Configuring execution settings (confirm_before_run)
  • Setting cache retention period

Manual Configuration:

# Set interpreter for Python files
gist-cache-rs config set defaults.interpreter.py python3

# Set fallback interpreter
gist-cache-rs config set defaults.interpreter."*" bash

# View configuration
gist-cache-rs config show

For more details, see the Configuration Guide.

2. Initial Cache Creation

gist-cache-rs update

Detailed display:

gist-cache-rs update --verbose

3. Alias Setting (Optional)

Automatic setting (when using setup.sh)

Set interactively during installation:

Use recommended alias names (gcrsu, gcrsr)? [Y/n]: y

Or

Use recommended alias names (gcrsu, gcrsr)? [Y/n]: n
Alias name for gist-cache-rs update: gcu
Alias name for gist-cache-rs run: gcr

Manual setting

# Add to ~/.bashrc or ~/.zshrc
alias gcrsu='gist-cache-rs update'
alias gcrsr='gist-cache-rs run'

# Apply settings
source ~/.bashrc

Installation Verification

# Check version
gist-cache-rs --version

# Display help
gist-cache-rs --help

# Check cache status
gist-cache-rs update --verbose

Troubleshooting

command not found: gist-cache-rs

Cause: PATH is not set

Solution (Linux/macOS):

# Check installation location
which gist-cache-rs

# Check PATH
echo $PATH

# If in ~/.cargo/bin
export PATH="$HOME/.cargo/bin:$PATH"

# If in ~/bin
export PATH="$HOME/bin:$PATH"

# Apply settings
source ~/.bashrc

Solution (Windows):

# Check installation location
where.exe gist-cache-rs

# Check PATH
$env:PATH

# Set environment variable (PowerShell)
$env:PATH += ";$env:USERPROFILE\.cargo\bin"

# For persistent setting
[System.Environment]::SetEnvironmentVariable("Path", $env:PATH, [System.EnvironmentVariableTarget]::User)

Permission error

Cause: No execution permission

Solution:

# Grant execution permission
chmod +x ~/.cargo/bin/gist-cache-rs
# Or
chmod +x /usr/local/bin/gist-cache-rs
# Or
chmod +x ~/bin/gist-cache-rs

Build error

Cause: Outdated Rust version, dependency issues

Solution:

# Update Rust
rustup update

# Update dependencies
cargo update

# Clean build
cargo clean
cargo build --release

GitHub CLI authentication error

Error: GitHub CLI (gh) is not authenticated

Solution:

gh auth login

PowerShell execution policy error (Windows)

Error: This system\'s script execution is disabled...

Solution:

# Allow script execution for current user
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Or bypass for specific script only
powershell -ExecutionPolicy Bypass -File .\script\setup.ps1 install

Cache not created

Error: Cache file not found

Solution:

# Initial cache creation
gist-cache-rs update

# Display detailed information
gist-cache-rs update --verbose

Rate limit error

Warning: Rate limit remaining is low

Solution:

  • Wait for a while and retry
  • Avoid --force option
  • Use differential update

Uninstallation

Automatic Uninstallation

Linux / macOS

./script/setup.sh uninstall

Interactively select:

  • Binary deletion
  • Cache directory deletion
  • Alias deletion

Windows

.\script\setup.ps1 uninstall

Interactively select:

  • Binary deletion
  • Cache directory deletion

Manual Uninstallation

Linux / macOS

# If installed with cargo
cargo uninstall gist-cache-rs

# If installed in system directory
sudo rm /usr/local/bin/gist-cache-rs

# If installed in user directory
rm ~/bin/gist-cache-rs

# Delete cache directory
rm -rf ~/.cache/gist-cache/

# Delete config directory
rm -rf ~/.config/gist-cache/

# Remove aliases (delete relevant lines from ~/.bashrc or ~/.zshrc)
# Example:
# alias gcrsu='gist-cache-rs update'
# alias gcrsr='gist-cache-rs run'

Windows

# If installed with cargo
cargo uninstall gist-cache-rs

# Delete cache directory
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\gist-cache"

# Delete config directory
Remove-Item -Recurse -Force "$env:APPDATA\gist-cache"

Next Steps