Configuration

GitBack is configured using a single YAML configuration file.

Location:

~/.config/gitback/config.yaml

You can generate the initial configuration using:

gitback init

Example Configuration

data_dir: ~/.local/share/gitback

repository_workers: 4

snapshot_retention: 30

minimum_free_disk_percent: 10

log_level: info

Configuration Reference

data_dir

Directory used to store mirrors, snapshots, and backup state.

Example:

data_dir: ~/.local/share/gitback

Default:

~/.local/share/gitback

Contents:

data_dir/
├── mirrors/
├── snapshots/
└── state/

---

sync_workers

Number of concurrent workers used during repository synchronization.

Example:

sync_workers: 8

Default:

sync_workers: 4

Increasing this value may improve sync performance for accounts containing many repositories.

Consider GitHub API limits and available system resources when increasing worker counts.

---

snapshot_retention

Automatically removes older snapshots after a new snapshot is created.

Example:

snapshot_retention: 30

Behavior:

Keep newest 30 snapshots
Delete older snapshots

Default:

snapshot_retention: 0

Meaning:

Retention disabled

---

minimum_free_disk_percent

Minimum acceptable free disk space percentage.

Used by:

gitback health

Example:

minimum_free_disk_percent: 20

Default:

minimum_free_disk_percent: 20

If available disk space falls below this threshold, health status becomes:

critical

Runtime Directories

GitBack automatically manages runtime directories.

These directories are created automatically when missing:

mirrors/
snapshots/
state/
tmp/

Accidental deletion of these directories does not require reinitialization.

GitBack recreates them when needed and records recovery events in logs.

GitHub Token

GitHub credentials are stored separately from the configuration file.

Location:

~/.local/share/gitback/state/github.token

GitBack supports:

• Classic Personal Access Tokens
• Fine-Grained Personal Access Tokens

See Installation for required permissions.

Recommended Configuration

Small personal account:

repository_workers: 4
snapshot_retention: 14
minimum_free_disk_percent: 10

Adjust values based on:

• Number of repositories
• Available storage
• Network bandwidth
• Snapshot frequency

Configuration Changes

After modifying the configuration:

gitback doctor

to validate the environment and ensure the new settings are recognized correctly.

Next Step

Continue with:

• Commands
• Automation
• Snapshots & Recovery
• Troubleshooting