git-mirror/README.md

81 lines
2.7 KiB
Markdown
Raw Permalink Normal View History

2019-11-06 13:47:23 +01:00
# Git mirror
Run this script to synchronize a repository once.
2022-05-23 14:35:29 +02:00
## 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
```
2019-11-06 13:47:23 +01:00
## Dependencies
* bash
* git
* Tor and torify (see section "Tor")
## Usage
```
./git-mirror.sh <workdir> <leader> <follower...>
```
2022-05-23 14:35:29 +02:00
## How to use
2019-11-06 13:47:23 +01:00
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
```
2020-09-15 12:16:22 +02:00
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
2022-05-23 14:35:29 +02:00
#!/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
2020-09-15 12:16:22 +02:00
```
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`.
2019-11-06 13:47:23 +01:00
2022-05-23 14:35:29 +02:00
## Caveat
If a branch has diverged, it will not be updated. Update it manually in that case.
2019-11-06 13:54:41 +01:00
## 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).
2019-11-06 13:47:23 +01:00
## Tor
2020-09-15 12:06:33 +02:00
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
```
2019-11-06 13:47:23 +01:00
## 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.