git-mirror/README.md

# Git mirror

Run this script to synchronize a repository once.

## Quick start
Clone git-mirror somewhere on your system. Create a script like the following in the directory of
the repository you want to keep mirrored, and configure the variables:
```bash
#!/bin/sh

mirror="$HOME/path/to/git-mirror/git-mirror.sh"
leader="github" # Name of the leader remote
followers="origin" # Space separated list of names of follower remotes

exec "$mirror" --notor "$(dirname "$0")" $leader $followers
```

## Dependencies
* bash
* git
* Tor and torify (see section "Tor")

## Usage
```
./git-mirror.sh <workdir> <leader> <follower...>
```

## How to use
Create a git repo, add remotes for the leader and the followers:
```bash
mkdir ~/git-mirror-my-repo; cd ~/git-mirror-my-repo
git init
git remote add github https://github.com/interesting/repo
git remote add gitea ssh://git@git.example.org/me/interesting-repo
git remote add gitlab ssh://git@git.example.com/myself/interesting-repo
```

Make sure Tor is running (see section "Tor"). Then run the mirroring script:
```bash
cd
git clone https://git.zeus.gent/midgard/git-mirror.git; cd git-mirror
./git-mirror.sh ~/git-mirror-my-repo github gitea gitlab
```
The first remote, `github` in this case, is the leader. The others are followers that are updated.

If you want to do this conveniently every now and then, you can create a script like this in your
repository's directory:
```bash
#!/bin/sh

mirror="$HOME/path/to/git-mirror/git-mirror.sh"
leader="github" # Name of the leader remote
followers="origin" # Space separated list of names of follower remotes

exec "$mirror" --notor "$(dirname "$0")" $leader $followers
```

Make sure to make it executable, and gitignore it when relevant. A good idea may be to choose an
arcane name, like `update--.sh`, and add it to a global gitignore file in `~/.gitignore`.

## Caveat
If a branch has diverged, it will not be updated. Update it manually in that case.

## Automate
To automate mirroring, run it periodically, for example once every 30 minutes. On a *NIX you could
use cron for this, or write a system service definition for your system supervisor (such as
systemd, OpenRC or runit).

## Tor
Unless the option `--notor` is used, the leader is fetched over Tor through torify. Make sure Tor
is running, or pass `--notor` to the script, like so:
```bash
./git-mirror.sh ~/git-mirror-my-repo github gitea gitlab
```

## Motivation
GitHub has always been hypocritical, promoting open source while keeping its own stack closed. When
GitHub was bought by Microsoft, the author decided to stop using it. Unfortunately a lot of
software still only has a presence on GitHub. To make it easier to work with those, this simple
mirror script was written.