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> |
| Edit overlay | repoverlay edit <name> --add <files> |
| Sync changes back | repoverlay sync <name> |
| Switch overlays | repoverlay switch <source> |
| Browse available overlays | repoverlay browse |
| Manage sources | repoverlay source add/list/remove |
| Shell completions | repoverlay completions <shell> |
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
editandsync.
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# Apply from a local directory
repoverlay apply /path/to/overlay
# Apply from GitHub
repoverlay apply https://github.com/owner/repo
# Remove an overlay
repoverlay remove my-overlayFor the full command reference with all options and flags, see docs/cli-reference.md.
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.
MIT