repoverlay

Apply configuration files to git repositories without committing them.

Files are symlinked (or copied with --copy) from overlay sources and automatically excluded from git tracking via .git/info/exclude.

Quick Reference

Installation

Homebrew (macOS/Linux)

brew install tylerbutler/tap/repoverlay

Shell installer (macOS/Linux)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/tylerbutler/repoverlay/releases/latest/download/repoverlay-installer.sh | sh

PowerShell installer (Windows)

irm https://github.com/tylerbutler/repoverlay/releases/latest/download/repoverlay-installer.ps1 | iex

Cargo

cargo install repoverlay

From source

git clone https://github.com/tylerbutler/repoverlay
cd repoverlay
cargo install --path .

Usage

Apply an overlay

# From local directory
repoverlay apply /path/to/overlay

# From GitHub (uses default branch)
repoverlay apply https://github.com/owner/repo

# From GitHub with specific branch/tag
repoverlay apply https://github.com/owner/repo/tree/v1.0.0
repoverlay apply https://github.com/owner/repo --ref develop

# From a subdirectory within a repo
repoverlay apply https://github.com/owner/repo/tree/main/overlays/rust

# Options
repoverlay apply ./overlay --target /path/to/repo  # Apply to specific directory
repoverlay apply ./overlay --copy                   # Copy instead of symlink
repoverlay apply ./overlay --name my-config         # Custom overlay name

Remove overlays

repoverlay remove              # Interactive (lists applied overlays)
repoverlay remove my-overlay   # Remove specific overlay
repoverlay remove --all        # Remove all overlays

Check status

repoverlay status                  # Show all applied overlays
repoverlay status --name my-overlay # Show specific overlay

Update GitHub overlays

repoverlay update              # Check and apply updates to all GitHub overlays
repoverlay update --dry-run    # Check without applying
repoverlay update my-overlay   # Update specific overlay

Restore after git clean

repoverlay restore             # Restore overlays from external backup
repoverlay restore --dry-run   # Preview what would be restored

Create overlays from existing repos

repoverlay create --include .claude/ --include CLAUDE.md --output ~/overlays/my-ai-config
repoverlay create --include .envrc --output ~/overlays/env --name my-env-config
repoverlay create --include .claude/ --output ~/overlays/test --dry-run  # Preview

Switch overlays

Replace all existing overlays with a new one:

repoverlay switch ~/overlays/typescript-ai
repoverlay switch https://github.com/user/ai-configs/tree/main/rust
repoverlay switch ~/overlays/new-config --name my-config

Manage cache

repoverlay cache list           # List cached repositories
repoverlay cache path           # Show cache location
repoverlay cache clear          # Clear entire cache
repoverlay cache remove owner/repo  # Remove specific cached repo

Overlay Configuration

Create a repoverlay.toml in your overlay directory to configure it:

[overlay]
name = "my-config"
description = "Personal development configuration"

[mappings]
# Rename files when applying
".envrc.template" = ".envrc"
"vscode-settings.json" = ".vscode/settings.json"

Without a config file, all files in the overlay directory are symlinked with the same relative path.

License

MIT