Back up Git repositories. go-git-em keeps a mirror of each repository and, when it changes, saves a snapshot that git clone can restore. Run it once, or as a daemon on a schedule.
go install github.com/alexycodes/go-git-em/cmd/gge@latestBuilding needs Go 1.27.3 or later. Running needs git, and ssh for ssh URLs. Your git and ssh configuration applies.
# go-git-em.yaml
defaults:
schedule: "0 3 * * *" # every day at 03:00
retention: 30 # keep the 30 latest snapshots
repositories:
- input: https://github.com/example/project.git
output: ./backups/project
- input: git@github.com:example/other.git
output: ./backups/other
schedule: "0 * * * *" # every hourIn the same directory:
gge check-config # check the config
gge backup # back up everything now, then exit
gge cron # back up on the schedules, until stoppedSet each key on a repository, or under defaults for all of them. Relative paths are relative to the config file. On Windows, don't put a path with backslashes in double quotes, where YAML reads \ as an escape: leave it unquoted, or use forward slashes.
| Key | Default | |
|---|---|---|
input |
required | Repository URL (https://, ssh://, git@host:path, file://) or local path |
output |
required | Directory for this repository's backups, one per repository |
schedule |
none | When gge cron backs it up: the 5 cron fields, in quotes, such as "0 3 * * *" (every day at 03:00) or "*/15 * * * *". In the local time zone, which TZ sets on Linux and macOS, such as TZ=Europe/Paris. Only gge cron needs it. |
retention |
keep all | How many snapshots to keep |
timeout |
30m |
Longest a backup may run |
ssh_key |
ssh's own | Private key for ssh URLs |
Commands:
| Command | |
|---|---|
gge backup |
Back up everything once, then exit |
gge cron |
Back up each repository on its schedule, until stopped |
gge check-config |
Check the config and print it, then exit. A repository without a schedule gets a warning. |
gge version |
Print the version |
Flags go after the command, and gge <command> -h lists them:
| Flag | Default | |
|---|---|---|
--config |
go-git-em.yaml |
Config file. By default, go-git-em.yaml in the current directory, unless --input is given. |
--input, --output |
Back up one repository without a config file. --schedule (not for backup) and --retention go with them. |
|
--parallel |
4 |
Backups at once (backup, cron) |
--run-on-start |
true |
Back up everything at startup (cron) |
--ssh-key |
Default ssh_key |
|
--log-level |
info |
debug, info, warn or error |
--log-format |
text |
text or json |
Every flag can also be set with an environment variable: GOGITEM_ and the flag's name, such as GOGITEM_LOG_LEVEL. A command ignores the variables of flags it doesn't take.
<output>/
mirror.git/ the mirror, updated on each run
snapshots/
20261101T030000.000Z.bundle the repository at that time (UTC)
- A snapshot is written only when something changed. With a
retention, the oldest ones are deleted. - Branches deleted or force-pushed upstream stay in the older snapshots.
- Each snapshot is a full copy, so plan for about
retention× the repository's size.
To restore, clone a snapshot:
git clone backups/project/snapshots/20261101T030000.000Z.bundle projectgge backupexits 1 if anything wasn't backed up. Use it from your system's cron, a systemd timer or a Kubernetes CronJob.gge cronruns until it's stopped, then exits 0. A failed backup is logged and tried again when it's next due.- Exit code 2 means a usage or configuration error, or no git.
- Logs go to stderr, one line per backup.
- Ctrl-C or SIGTERM (on Windows, closing the console too) stops the backups in progress. The snapshots already written stay.
- If two go-git-em processes use the same output, the second skips it. On a network file system that can't lock, go-git-em warns and goes on.
gge cron doesn't start itself at boot: run it as a systemd service, a container with a restart policy, or a Kubernetes Deployment. In a container, run it under an init, such as docker run --init.
- The host must already be in
known_hosts: go-git-em never prompts. - Your key file must be readable only by you (
chmod 600; on Windows, OpenSSH checks this itself). A key with a passphrase needs ssh-agent.
- Git LFS files aren't backed up, only their pointers. Restore with
GIT_LFS_SKIP_SMUDGE=1 git clone …. - Pull request refs (
refs/pull/*on GitHub) are backed up too, so a busy repository gets a new snapshot on almost every run. - Not backed up: submodules (add each one as its own repository), issues, wikis and other forge data.
- A local repository owned by another user is refused by git ("dubious ownership"). Run go-git-em as its owner, or add it to git's
safe.directory. - A broken mirror fails every run. Delete
<output>/mirror.git, and the next run clones it again. - Credentials in a URL are kept in
mirror.git/config. Prefer ssh keys or a credential helper. - Don't
kill -9it: git would keep running, and the next run could clash with it. On Windows, git is killed with it.
This project is developed with the help of AI coding tools. Much of the code, tests and documentation was AI-generated. Review it before you rely on it for your backups.
Licensed under the GNU General Public License v3.0 or later. See LICENSE.