gitback

GitBack

Simple, transparent GitHub repository backups.

GitBack discovers repositories 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 Public and private GitHub repository (can't choose one, for now)

• Local Git mirror synchronization

• Compressed snapshots (tar + zstd)

• SHA256 checksum for integrity check

• Structured JSON logging

• Health reporting

• Environment diagnostics

• Headless automation support (need improvements)

• 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 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.

Headless mode:

gitback snapshot --headless

Continues snapshot creation even if repository verification reports failures.

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/
├── snapshots/
└── state/
    ├── github.token
    ├── repositories.txt
    └── mirrors.json

Runtime state:

~/.local/state/gitback/
├── gitback.log
└── 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

GitBack also generates SHA256 checksum files alongside snapshots.

Automation

Typical unattended workflow:

gitback discover
gitback sync
gitback snapshot --headless

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

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.