git-overlay 0.1.0

Manage overlay files across git repositories
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

# git-overlay

[![Crates.io](https://img.shields.io/crates/v/git-overlay)](https://crates.io/crates/git-overlay)
[![CI](https://github.com/sudoremo/git-overlay/actions/workflows/ci.yml/badge.svg)](https://github.com/sudoremo/git-overlay/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

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:

```sh
cargo install --path .
```

## Setup

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

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

The config file is a simple YAML file:

```yaml
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

```sh
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)

```sh
git-overlay apply
```

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

### List overlay entries

```sh
git-overlay ls
```

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

### Remove files from the overlay

```sh
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

```sh
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

```sh
git-overlay save
```

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

### Pull / Push

```sh
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:

```sh
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