gitback

GitBack

Simple, transparent GitHub repository and Gist backups.

GitBack discovers repositories and gists from GitHub, maintains local mirrors, and creates compressed snapshots for long-term storage. It is designed to run unattended while remaining easy to inspect, troubleshoot, and recover from.

Features

• Backup GitHub repositories
• Backup GitHub Gists
• Concurrent repository synchronization
• Compressed snapshots (tar + zstd)
• SHA256 checksum generation and verification
• Structured JSON logging
• Health reporting
• Environment diagnostics
• Snapshot retention
• No database
• No daemon
• No proprietary formats

Installation

Go Install

go install github.com/flarexes/gitback/cmd/gitback@latest

Build From Source

git clone https://github.com/flarexes/gitback.git

cd gitback

go build -o gitback ./cmd/gitback

Requirements

Required tools:

• git

• tar

• zstd

Verify your environment:

gitback doctor

Commands

Initialize

gitback init

Creates configuration and validates GitHub authentication.

Discover

gitback discover

Discovers repositories and gists accessible to the configured GitHub account.

Sync

gitback sync

Creates and updates local Git mirrors.

Snapshot

gitback snapshot

Creates a compressed archive containing all mirrored repositories, gists, and backup state.

Force mode:

gitback snapshot --force

Continues snapshot creation even if repository or gist synchronization previously failed.

Health

gitback health

Displays repository status, snapshot information, storage usage, and recommendations.

Doctor

gitback doctor

Performs environment and configuration checks. Recommendation after initialization, gitback init.

GitHub Token Permissions

GitBack supports either a Classic Personal Access Token or a Fine-Grained Personal Access Token.

Classic PAT

Scope:

repo

Fine-Grained PAT

Repository Access:

All repositories

Permissions:

Contents: Read-only
Metadata: Read-only

Any one token type is required.

Directory Layout

Configuration:

~/.config/gitback/
└── config.yaml

Data:

~/.local/share/gitback/
├── mirrors/
│   ├── repositories/
│   └── gists/
├── snapshots/
└── state/
    ├── github.token
    ├── repositories.txt
    ├── gists.txt
    └── mirrors.json

Runtime state:

~/.local/state/gitback/
└── gitback.log

/tmp/gitback.lock

Logging

GitBack produces structured JSON logs.

Example:

{
  "timestamp": "2026-06-07T10:00:00Z",
  "run_id": "7b3f4a1c",
  "level": "info",
  "event": "sync_completed"
}

Snapshots

Snapshots are stored as:

YYYY-MM-DDTHH-MM-SSZ.tar.zst

Each snapshot includes:

mirrors/
state/mirrors.json

Snapshot retention can be configured to automatically remove older snapshots.

Example:

snapshot_retention: 30

Retains the newest 30 snapshots. Retention is disabled by default (0 or < 1).

GitBack also generates SHA256 checksum files alongside snapshots.

Automation

Typical unattended workflow:

gitback discover
gitback sync
gitback snapshot --force

Can be scheduled using:

• cron

• systemd timers

• CI/CD pipelines

Roadmap

• Windows and macOS support

• Multi-worker synchronization

• Git retry and backoff support

• GitHub organization support

• Repository filtering

• Wiki backups

Contributing

Bug reports, feature requests, and pull requests are welcome.

Please keep contributions aligned with the project's core principles:

• Simplicity

• Transparency

• Reliability

License

BSD 3-Clause License.

See LICENSE for details.

Why GitBack?

GitBack is built to solve a straightforward problem: reliably backing up Git repositories without unnecessary complexity.

Many existing solutions provide hosted services, dashboards, integrations, and management platforms. Those tools provide real value and are often the right choice for teams that need them.

However, many individuals, open source maintainers, and small teams simply need dependable repository backups they can run themselves.

GitBack focuses on that use case using standard Git mirrors, standard archive formats, and straightforward recovery procedures.

If GitBack disappears tomorrow, your backups remain usable with standard tools.

The project is still young and will continue to evolve, but simplicity, reliability, and operational transparency will remain the primary design goals.