Cacher

A command-line tool for caching command outputs to save time when running repetitive commands.

Features

• Cache command outputs in memory and on disk
• Retrieve cached results instead of re-running commands
• Set time-to-live (TTL) for cached entries
• Force execution to bypass cache
• List all cached commands
• Clear specific or all cached entries
• Get hash ID for any command
• Cache artifacts like directories and files alongside command outputs

Installation

Pre-built Binaries

You can download pre-built binaries for your platform from the latest GitHub release:

• Linux (x86_64)
• Linux (ARM64)
• macOS (x86_64)
• macOS (ARM64/Apple Silicon)
• Windows (x86_64)

After downloading, make the binary executable (Linux/macOS):

chmod +x cacher-*

From Source

# Clone the repository
git clone https://github.com/deanshub/cacher.git
cd cacher

# Build the project
cargo build --release

# Optional: Install the binary
cargo install --path .

Using Cargo

cargo install cacher

Usage

Run a command with caching

# Basic usage
cacher run "ls -la"

# With TTL (time-to-live) in seconds
cacher run "ls -la" --ttl 3600

# Force execution (ignore cache)
cacher run "ls -la" --force

List cached commands

cacher list

Clear cache

# Clear all cache
cacher clear --all

# Clear specific command
cacher clear --command "ls -la"

Get hash ID for a command

cacher hash "ls -la"

Using a .cacher hint file

You can create a .cacher file in your project to customize caching behavior. Cacher will automatically look for this file in the current directory and its parent directories.

Basic Configuration

# Default settings for all commands
default:
  ttl: 3600  # Default TTL in seconds (1 hour)
  include_env:
    - PATH
    - NODE_ENV  # Include environment variables in cache key

Command Patterns

Use glob patterns to match commands:

commands:
  - pattern: "npm run *"  # Matches all npm run commands
    ttl: 7200  # 2 hours
  
  - pattern: "git status"  # Exact match
    ttl: 60  # 1 minute

File Dependencies

Specify files that should invalidate the cache when modified:

commands:
  - pattern: "npm run build"
    depends_on:
      - file: "package.json"  # Single file
      - files: "src/**/*.js"  # Glob pattern for multiple files

Environment Variables

Include specific environment variables in the cache key:

commands:
  - pattern: "docker-compose up"
    include_env:
      - DOCKER_HOST
      - COMPOSE_PROJECT_NAME

Line Patterns

Only consider specific lines in files using regex patterns:

commands:
  - pattern: "npm run dev"
    depends_on:
      - lines:
          file: ".env"
          pattern: "^(API_|DEV_)"  # Only match lines starting with API_ or DEV_

Artifact Caching

Cache directories or files produced by commands:

commands:
  - pattern: "npm run build"
    artifacts:
      - type: "directory"
        path: "dist"  # Cache the dist directory
        
  - pattern: "docker build -t myapp ."
    artifacts:
      - type: "docker_image"
        name_from: "argument"
        position: 1  # Extract from the -t argument

Complete Example

# Default settings for all commands
default:
  ttl: 3600  # Default TTL in seconds
  include_env:
    - PATH
    - NODE_ENV

# Command-specific settings
commands:
  # Cache npm build commands for 2 hours
  - pattern: "npm run build"
    ttl: 7200
    include_env:
      - NODE_ENV
    depends_on:
      - files: "src/**/*.{js,jsx,ts,tsx}"  # All source files
      - files: "package*.json"             # package.json and package-lock.json
      - file: "tsconfig.json"              # Specific file
      
  # Cache docker-compose commands for 1 day
  - pattern: "docker-compose up *"
    ttl: 86400
    include_env:
      - DOCKER_HOST
    depends_on:
      - file: "docker-compose.yml"
      - files: "Dockerfile*"
      - lines:
          file: ".env"
          pattern: "^(DB_|API_)"  # Only consider DB_ and API_ variables
    artifacts:
      - type: "directory"
        path: "node_modules"  # Cache node_modules directory

How it works

Cacher uses SHA-256 hashing to generate unique identifiers for each command. When you run a command through Cacher, it:

1. Checks if the command is already cached in memory
2. If not found in memory, checks if it's cached on disk
3. If not found or if cache is expired (based on TTL), executes the command
4. Stores the result in both memory and disk cache
5. If artifacts are defined, caches them alongside the command output

When retrieving a cached command, Cacher will:

1. Restore any cached artifacts (like directories or files)
2. Return the cached command output

The cache is stored in your system's cache directory:

• macOS: ~/Library/Caches/cacher/
• Linux: ~/.cache/cacher/
• Windows: C:\Users\{username}\AppData\Local\cacher\

Development

Running tests

cargo test

Building documentation

cargo doc --open

License

This project is licensed under the MIT License - see the LICENSE file for details.