git-overlay

Manage overlay files across git repositories. Move untracked files (configs, secrets, local overrides) into a central overlay repository and replace them with symlinks. The overlay repo is committed and pushed automatically so the files travel with you across machines.

Requires a Unix-like operating system (macOS, Linux).

Installation

From a local checkout:

cargo install --path .

Setup

Initialise the overlay repo. This clones the remote and writes the config file at ~/.config/git-overlay.yml:

git-overlay init git@github.com:you/overlay.git ~/overlay

The config file is a simple YAML file:

repo: ~/overlay

You can also set the GIT_OVERLAY_CONFIG environment variable to point to a different config file.

Usage

All commands are run from inside a project repository. The project's origin remote URL is used to derive the overlay subdirectory (e.g. myorg/myproject).

Add files to the overlay

git-overlay add config/local.yml
git-overlay add secrets/*.key

Each file is copied into the overlay repo, replaced with a symlink, and the path is added to .git/info/exclude. The overlay repo is committed and pushed automatically.

The overlay repo must be clean (no uncommitted changes) before running add or rm.

Apply overlay (create symlinks)

git-overlay apply

Re-creates symlinks for all overlay entries. Run this after cloning a project or after git-overlay pull.

List overlay entries

git-overlay ls

Shows all overlay entries for the current project. Modified and deleted entries are highlighted.

Remove files from the overlay

git-overlay rm config/local.yml

Copies the file back from the overlay, removes the symlink, and removes the entry from the overlay repo.

Clear overlay symlinks

git-overlay clear
git-overlay clear --remove

Removes all overlay symlinks from the current project. The files remain in the overlay repo so they can be re-applied later with git-overlay apply.

With --remove, the entries are also deleted from the overlay repository and the change is committed and pushed.

Save changes

git-overlay save

Commits and pushes any modifications to overlay files for the current project.

Pull / Push

git-overlay pull
git-overlay push

Pull or push the overlay repository.

Dry run

Most commands support --dry-run to preview what would happen without making any changes:

git-overlay add --dry-run config/local.yml
git-overlay rm --dry-run config/local.yml
git-overlay apply --dry-run
git-overlay save --dry-run

How it works

1. add copies files into <overlay-repo>/<org>/<project>/ and replaces the originals with symlinks pointing into the overlay.
2. Paths are added to .git/info/exclude so git ignores the symlinks.
3. The overlay repo is a regular git repository -- changes are committed and pushed automatically on add, rm, and save.
4. apply re-creates the symlinks (useful after a fresh clone or a pull).

License

MIT