https://github.com/tylerbutler/repoverlay
A tool to overlay files on top of a git repo without committing them.
https://github.com/tylerbutler/repoverlay
ai-agents cli configuration sync
Last synced: 3 months ago
JSON representation
A tool to overlay files on top of a git repo without committing them.
- Host: GitHub
- URL: https://github.com/tylerbutler/repoverlay
- Owner: tylerbutler
- License: mit
- Created: 2026-01-06T22:25:49.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-03-21T23:33:19.000Z (4 months ago)
- Last Synced: 2026-03-22T12:37:02.542Z (4 months ago)
- Topics: ai-agents, cli, configuration, sync
- Language: Rust
- Homepage: https://repoverlay.tylerbutler.com
- Size: 1.52 MB
- Stars: 6
- Watchers: 0
- Forks: 0
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# repoverlay
[](https://github.com/tylerbutler/repoverlay/actions/workflows/ci.yml)
[](https://crates.io/crates/repoverlay)
[](https://codecov.io/gh/tylerbutler/repoverlay)
[](LICENSE)
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
| Task | Command |
|------|---------|
| **Browse & apply overlays** | **`repoverlay browse`** |
| Apply overlay (scripting) | `repoverlay apply ` |
| Check status | `repoverlay status` |
| Remove overlay | `repoverlay remove ` |
| Remove all | `repoverlay remove --all` |
| Update from remote | `repoverlay update` |
| Restore after git clean | `repoverlay restore` |
| Create overlay | `repoverlay create ` |
| Create local overlay | `repoverlay create --output ` |
| Edit overlay | `repoverlay edit --add ` |
| Sync changes back | `repoverlay sync ` |
| Switch overlays | `repoverlay switch ` |
| Manage sources | `repoverlay source add/list/remove` |
| Shell completions | `repoverlay completions ` |
## 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 or local directory) 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 `edit` and `sync`.
## Installation
### Homebrew (macOS/Linux)
```bash
brew install tylerbutler/tap/repoverlay
```
### Shell installer (macOS/Linux)
```bash
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/tylerbutler/repoverlay/releases/latest/download/repoverlay-installer.sh | sh
```
### PowerShell installer (Windows)
```powershell
irm https://github.com/tylerbutler/repoverlay/releases/latest/download/repoverlay-installer.ps1 | iex
```
### Cargo
```bash
cargo binstall repoverlay # pre-built binary
cargo install repoverlay # build from source
```
## Usage
The easiest way to get started is with `browse`, which interactively lists available overlays and lets you select which to apply:
```bash
# Add a source, then browse and apply interactively
repoverlay source add owner/repo
repoverlay browse
# Or browse an ephemeral source directly
repoverlay browse ./path/to/overlays
repoverlay browse owner/repo
```
For scripting or power-user workflows, use `apply` directly:
```bash
# 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-overlay
```
For the full command reference with all options and flags, see [docs/cli-reference.md](docs/cli-reference.md).
## 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