repoverlay

Overlay config files into git repositories without committing them. Files are symlinked (or copied with --copy) from overlay sources and automatically excluded via .git/info/exclude.

Quick Reference

Concepts

repoverlay manages four kinds of objects:

• Overlay — a set of config files applied to a repo. Lifecycle: create → apply → update → remove.
• Source — a configured location (GitHub repo) to find overlays. Lifecycle: source add → source list → source remove.
• Cache — local clones of GitHub repos used by overlays. Managed automatically on apply; inspect with cache list, clean with cache remove --all.
• File — an individual file within an overlay. Managed via add and sync.

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 binstall repoverlay  # pre-built binary
cargo install repoverlay   # build from source

Usage

Apply an overlay

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

# From GitHub (default branch, specific ref, or subdirectory)
repoverlay apply https://github.com/owner/repo
repoverlay apply https://github.com/owner/repo/tree/v1.0.0
repoverlay apply https://github.com/owner/repo --ref develop
repoverlay apply https://github.com/owner/repo/tree/main/overlays/rust

# From overlay repository
repoverlay apply org/repo/overlay-name

# 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 selection
repoverlay remove my-overlay   # Remove specific overlay
repoverlay remove --all        # Remove all overlays

Check status

repoverlay status                  # All applied overlays
repoverlay status --name my-overlay # Specific overlay

Update remote overlays

repoverlay update              # Pull and apply updates
repoverlay update --dry-run    # Preview changes
repoverlay update my-overlay   # Update specific overlay

Restore after git clean

repoverlay restore             # Re-apply overlays from backup
repoverlay restore --dry-run   # Preview what would be restored

Create overlays

# Detect org/repo from git remote
repoverlay create my-overlay

# Explicit path
repoverlay create microsoft/vscode/ai-config

# Include specific files
repoverlay create my-overlay --include .claude/ --include CLAUDE.md

# Local output (no overlay repo)
repoverlay create --output ./output --include .envrc

# Preview / overwrite
repoverlay create my-overlay --dry-run
repoverlay create my-overlay --force

Add files to an existing overlay

repoverlay add my-overlay newfile.txt              # Single file
repoverlay add my-overlay file1.txt file2.txt      # Multiple files
repoverlay add my-overlay config.json --dry-run    # Preview

Copies files to the overlay source, replaces originals with symlinks, and auto-commits/pushes.

Sync changes back

repoverlay sync my-overlay          # Sync modified files back to source
repoverlay sync my-overlay --dry-run

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

Manage cache

repoverlay cache list              # List cached repositories
repoverlay cache path              # Show cache location
repoverlay cache remove owner/repo # Remove specific cached repo
repoverlay cache remove --all      # Remove all cached repos

Overlay Configuration

Create a repoverlay.ccl in your overlay directory:

overlay =
  name = my-config

/= Rename files when applying
mappings =
  .envrc.template = .envrc
  vscode-settings.json = .vscode/settings.json

/= Symlink entire directories as a unit
directories =
  = .claude
  = scratch

mappings — Rename files during apply (source = destination).

directories — Directories to symlink (or copy) as a unit rather than walking individual files. Useful for directories like .claude/ that should be managed atomically.

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

License

MIT