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.
| Task | Command |
|---|---|
| Apply overlay | repoverlay apply <source> |
| Check status | repoverlay status |
| Remove overlay | repoverlay remove <name> |
| Remove all | repoverlay remove --all |
| Update from remote | repoverlay update |
| Restore after git clean | repoverlay restore |
| Create overlay | repoverlay create <name> |
| Create local overlay | repoverlay create --output <path> |
| Add files to overlay | repoverlay add <name> <files> |
| Sync changes back | repoverlay sync <name> |
| Switch overlays | repoverlay switch <source> |
| Browse available overlays | repoverlay browse |
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 withcache list, clean withcache remove --all. - File — an individual file within an overlay. Managed via
addandsync.
brew install tylerbutler/tap/repoverlaycurl --proto '=https' --tlsv1.2 -LsSf https://github.com/tylerbutler/repoverlay/releases/latest/download/repoverlay-installer.sh | shirm https://github.com/tylerbutler/repoverlay/releases/latest/download/repoverlay-installer.ps1 | iexcargo binstall repoverlay # pre-built binary
cargo install repoverlay # build from source# 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 namerepoverlay remove # Interactive selection
repoverlay remove my-overlay # Remove specific overlay
repoverlay remove --all # Remove all overlaysrepoverlay status # All applied overlays
repoverlay status --name my-overlay # Specific overlayrepoverlay update # Pull and apply updates
repoverlay update --dry-run # Preview changes
repoverlay update my-overlay # Update specific overlayrepoverlay restore # Re-apply overlays from backup
repoverlay restore --dry-run # Preview what would be restored# 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 --forcerepoverlay 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 # PreviewCopies files to the overlay source, replaces originals with symlinks, and auto-commits/pushes.
repoverlay sync my-overlay # Sync modified files back to source
repoverlay sync my-overlay --dry-runReplace all existing overlays with a new one:
repoverlay switch ~/overlays/typescript-ai
repoverlay switch https://github.com/user/ai-configs/tree/main/rustrepoverlay 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 reposCreate 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.
MIT