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

Installation

Pre-built Binaries

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

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.yaml 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_

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

How it works

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

Checks if the command is already cached in memory
If not found in memory, checks if it's cached on disk
If not found or if cache is expired (based on TTL), executes the command
Stores the result in both memory and disk cache

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.

cacher 0.2.2