Skip to content

Snapshots & Recovery

Jump to bottom
FlareXes edited this page Jun 19, 2026 · 1 revision

Snapshots are the primary recovery mechanism in GitBack. A snapshot captures the current backup state and stores it as a compressed archive suitable for long-term retention and off-site storage.

Creating a Snapshot

Create a snapshot:

gitback snapshot

Force snapshot creation even if previous synchronization failures exist:

gitback snapshot --force

Snapshot Contents

Each snapshot contains:

mirrors/
state/

The mirrors directory contains Git repositories and Gists.

mirrors/
├── repositories/
└── gists/

The state directory contains inventory and synchronization state.

state/
├── repositories.txt
├── gists.txt
└── mirrors.json

Together these files provide enough information to inspect and recover a backup.

Snapshot Format

Snapshots are stored as:

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

Example:

2026-06-17T14-30-00Z.tar.zst

GitBack uses:

  • tar for archive creation
  • zstd for compression

No proprietary formats are used.

Integrity Verification

GitBack generates a SHA256 checksum alongside every snapshot.

Example:

2026-06-17T14-30-00Z.tar.zst
2026-06-17T14-30-00Z.tar.zst.sha256

Verify integrity:

sha256sum -c 2026-06-17T14-30-00Z.tar.zst.sha256

Expected result:

2026-06-17T14-30-00Z.tar.zst: OK

Always verify checksums after transferring snapshots to another system or storage provider.

Snapshot Retention

GitBack can automatically remove older snapshots.

Configuration:

snapshot_retention: 30

Behavior:

Keep newest 30 snapshots
Delete older snapshots

Retention is disabled by default:

snapshot_retention: 0

Restoring a Snapshot

Extract a snapshot:

tar --zstd -xf 2026-06-17T14-30-00Z.tar.zst

Result:

mirrors/
state/

The extracted mirrors can be inspected using standard Git tools.

Example:

git --git-dir mirrors/repositories/FlareXes/gitback.git log --oneline

No GitBack-specific tooling is required to access backup data.

Recovering After Data Loss

If the local GitBack data directory is lost:

  1. Restore the latest snapshot.
  2. Extract the archive.
  3. Place the restored files under the GitBack data directory.
  4. Run:
gitback health
  1. Run:
gitback sync

to update mirrors from GitHub.

Off-Site Storage

Snapshots are designed to be copied elsewhere.

Common destinations:

  • External drives
  • NAS devices
  • Object storage
  • Backup servers
  • Cloud storage

A backup stored only on the same machine is not a complete backup strategy.

Recovery Testing

Backups should be tested periodically.

Recommended procedure:

  1. Select a recent snapshot.
  2. Verify the checksum.
  3. Extract the archive.
  4. Inspect several repositories.
  5. Confirm commit history is present.

Example:

git --git-dir mirrors/repositories/FlareXes/gitback.git show HEAD

A backup is only valuable if recovery has been tested.

Common Questions

Can I access repositories without GitBack?

Yes.

GitBack stores standard Git mirrors.

Use standard Git commands against the mirrored repositories.

Can I move snapshots between systems?

Yes.

Snapshots are standard tar archives compressed with zstd.

Can I keep snapshots forever?

Yes.

Set:

snapshot_retention: 0

to disable automatic cleanup.

Next Step

Continue with:

Clone this wiki locally