Skip to content

Getting Started

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

Getting Started

This guide walks through creating your first GitBack backup.

1. Initialize GitBack

Run:

gitback init

Initialization:

  • Creates the configuration
  • Stores your GitHub token
  • Validates GitHub API access
  • Creates required directories

Expected output:

✓ configuration created
✓ GitHub authentication verified

2. Discover Assets

Discover repositories and Gists accessible to your GitHub account:

gitback discover

GitBack stores the discovered inventory locally:

~/.local/share/gitback/state/
├── repositories.txt
└── gists.txt

3. Synchronize Mirrors

Create or update local Git mirrors:

gitback sync

GitBack performs incremental updates when mirrors already exist.

Example:

[SYNC] FlareXes/gitback
[SYNC] FlareXes/assets

[GIST] 9565facfb6541360f7f7aeb2eeceb258

Mirrors are stored in:

~/.local/share/gitback/mirrors/
├── repositories/
└── gists/

4. Create a Snapshot

Create a compressed backup archive:

gitback snapshot

Snapshot files are stored in:

~/.local/share/gitback/snapshots/

Example:

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

To continue snapshot creation even if assets failed during the last sync:

gitback snapshot --force

5. Check Backup Health

Review backup status:

gitback health

Example:

{
  "status": "healthy",
  "repositories": {
    "total": 42,
    "healthy": 42
  },
  "gists": {
    "total": 12,
    "healthy": 12
  }
}

Health reports include:

  • Repository status
  • Gist status
  • Snapshot information
  • Storage usage
  • Recommendations

Typical Backup Workflow

A common backup workflow is:

gitback discover
gitback sync
gitback snapshot --force
gitback health

For unattended environments:

  • Run discover periodically
  • Run sync regularly
  • Run snapshot --force after sync
  • Monitor health

Automatic Recovery

GitBack automatically recreates missing runtime directories when possible:

mirrors/
snapshots/
state/
tmp/

This helps recover from accidental directory deletion without manual intervention.

Verify Your Backup

Confirm mirrors exist:

find ~/.local/share/gitback/mirrors

Confirm snapshots exist:

ls ~/.local/share/gitback/snapshots

Verify snapshot integrity:

sha256sum -c snapshot.tar.zst.sha256

Expected result:

snapshot.tar.zst: OK

Next Step

Continue with:

Clone this wiki locally