GitBack v0.5.5

A logging overhaul. GitBack logs are now structured, actionable, and ready for production use — whether you're feeding them into a SIEM, automated analysis, or reviewing an incident manually.

What's New

🧾 Structured, Actionable Logging

Every log entry now explains what happened, when it happened, why it happened, and what to do next.

🔄 Daily Log Rotation

GitBack no longer writes to a single ever-growing log file.

Logs are now rotated daily using your local time:

gitback-2026-09-05-saturday.log

Retention is configurable:

[logging]
retention_days = 30   # Delete log files older than this many days
min_keep = 10          # Always retain at least the 10 most recent files

min_keep protects infrequent schedules. If GitBack only runs weekly or monthly, older logs won't all disappear during a single retention cleanup.

🤖 Machine-Parseable Log Entries

Every log entry now contains stable, machine-friendly fields, including:

• A stable event code
• Fixed severity
• The affected asset
• A fixed failure category where applicable

Failure categories such as auth_failure and corruption remain consistent across GitBack versions, making logs suitable for reliable SIEM rules, dashboards, and automated analysis without depending on fragile text matching.

🖥️ Machine and Account Context

Every log entry now identifies the machine and account that produced it.

This is particularly useful when GitBack runs across multiple servers or under different system accounts, making it immediately clear where an event originated.

⚙️ Complete Configuration Example

Run:

gitback config example

to see a fully documented example configuration containing every available setting, including defaults and notes about important edge cases.

Upgrade Notes

This release changes the on-disk log format.

Existing log files are left untouched, but newly generated logs use the new format.

Configuration Compatibility

No changes to config.toml are required.

The new [logging] settings have sensible defaults and are only needed when you want to customize retention behavior.

Full Changelog

Full Changelog: v0.5.4...v0.5.5

GitBack v0.5.4

A reliability-focused update with safer runtime behavior, stronger diagnostics, and better protection against unexpected failures.

🛠️ What's Fixed

Sync no longer silently succeeds with zero assets.
If a repository or gist list couldn't be read (permissions issue, corrupted file), GitBack used to log a quiet warning and report a successful sync of zero repos. It now fails loudly instead, so a real problem can't be mistaken for "nothing to back up."

gitback init is safer.
Existing configurations, tokens, or sync data are no longer overwritten accidentally. Re-running initialization requires explicit --force when an existing setup is detected.

gitback discovery now respects the global lock.
GitBack operations are serialized consistently, preventing discovery from running alongside sync or snapshot operations.

Shutdown is handled cleanly.
Ctrl+C and systemctl stop now trigger graceful shutdown, release the lock, and avoid abrupt termination during active work.

Git failures now include useful diagnostics.
Clone and update failures now preserve Git's actual error output in the logs instead of producing empty or misleading error entries.

doctor and health reports now provide a complete picture.
Previously, one failed check (like a missing config) could stop the rest of the diagnostics from running. Both commands now check everything they can and show all of it at once. Making operational problems easier to identify in one run.

Additional reliability fixes.

• Fixed a rare case where GitBack's git credentials could be read inconsistently by git subprocesses.
• Fixed a file handle leak when another GitBack process is already running.

🔄 Upgrade

No configuration or storage layout changes are required.

Update the GitBack binary and continue using your existing installation.

Full Changelog

v0.5.3...v0.5.4

GitBack v0.5.3

🛠️ Issue Fix

GitBack could fail with a generic permission denied error when creating runtime directories, particularly on minimal Linux installations or when directory permissions or ownership had changed after installation.

Directory creation is now handled consistently across the application with improved error reporting, making permission-related failures easier to diagnose and recover from.

Full Changelog

v0.5.2...v0.5.3

GitBack v0.5.2

This release improves unattended backup workflows and makes credential management more flexible while including internal cleanup and reliability improvements.

✨ Highlights

New run command

GitBack now includes a unified run command for unattended backups.

The command performs the complete backup workflow in a single invocation:

1. Discover repositories and gists
2. Synchronize mirrors
3. Create a snapshot

The entire workflow executes under a single process lock, making it the recommended entry point for scheduled backups via cron or systemd while retaining the existing standalone commands for manual use and debugging.

GitHub token via environment variable

GitBack now supports reading the GitHub Personal Access Token from the GITBACK_TOKEN environment variable.

When set, the environment variable takes precedence over the stored token file, making it easy to integrate GitBack with:

• Systemd services
• CI/CD pipelines
• Secret management tools

Existing token file support remains unchanged for backwards compatibility.

🔧 Improvements

• Removed duplicate health command from help menu.
• Updated initialization to use more restrictive file permissions for improved security.
• Refactored command execution into shared workflow helpers, reducing duplicated runtime initialization, locking, and logging logic.

Upgrade Notes

No configuration changes are required.

Users who wish to avoid storing credentials on disk can now provide their GitHub token through the GITBACK_TOKEN environment variable:

export GITBACK_TOKEN=ghp_your_token_here
gitback run

Full Changelog

Full Changelog: v0.5.1...v0.5.2

GitBack v0.5.1

GitBack v0.5.1 focuses on improving mirror reliability and operational visibility. This release introduces self-healing recovery, quarantine management for corrupt mirrors, and enhanced health reporting.

✨ Highlights

Self-healing mirror recovery

When a corrupt mirror is detected, GitBack will:

1. Quarantine the corrupt mirror.
2. Clone a fresh replacement.
3. Validate the replacement.
4. Replace the corrupt mirror with the validated replacement.
5. Remove the quarantined copy after a successful recovery.

If automatic recovery fails, the quarantined mirror is retained for manual inspection.

Automatic quarantine cleanup

GitBack now retries recovery during subsequent synchronization runs. Successfully recovered mirrors are automatically removed from the quarantine directory, ensuring quarantine only contains unresolved recovery failures.

Enhanced health reporting

The health command has been expanded to provide better operational visibility.

New improvements include:

• Reporting quarantined mirrors.
• Improved storage health reporting across configured storage locations.

Upgrade Notes

No configuration changes are required.

The quarantine directory is created automatically alongside the configured mirror_root under config. Existing installations will continue to function without modification.

Full Changelog

v0.5.0...v0.5.1

GitBack v0.5.0

This release (v0.4.7 + v0.5.0) is a major step toward making GitBack a production-ready GitHub backup solution. While there are no new end-user features, a significant amount of work has gone into improving reliability, consistency, maintainability, and the project's internal architecture.

✨ Highlights

⚙️ Configuration Overhaul

• Migrated configuration from YAML to TOML.
• Removed internal runtime paths from the configuration file.
• Simplified configuration validation to focus only on user-configurable settings.

🔒 Atomic File Operations

• Introduced atomic writes for state and configuration files.
• Prevents partial writes and reduces the risk of data corruption during crashes or unexpected shutdowns.

📝 Improved Logging

• Expanded structured logging throughout the application.
• Improved log consistency and event categorization.

📦 Snapshot Improvements

• Removed assumptions about filesystem layout.
• Improved snapshot creation for configurable storage locations.

🧹 Internal Improvements

• Simplified runtime path management with centralized helper functions.
• Removed duplicated filesystem path logic across packages.
• Cleaned up and simplified several internal APIs.
• Improved separation of concerns between configuration, runtime state, and diagnostics.
• General refactoring and consistency improvements across the codebase.

💥 Breaking Changes

• Configuration files must be migrated from YAML to TOML.
• Runtime path configuration options have been removed.
• Existing installations will require a new configuration file before upgrading.

🚀 What's Next

The next development cycle will focus on improving backup resilience through mirror self-healing, allowing GitBack to automatically detect and recover from corrupted Git mirrors while preserving data integrity.

GitBack v0.4.6

This release focuses on synchronization improvements, version reporting, and operational polish.

Added

Concurrent Gist Synchronization

GitBack now synchronizes GitHub Gists using the same worker pool model used for repositories.

Benefits:

• Faster gist synchronization
• Better utilization of available workers
• Improved scalability for accounts with large numbers of gists

Improved

Version Reporting

GitBack now reports versions using Go build metadata when no release version is injected.

This improves version visibility for:

• go install github.com/flarexes/gitback/cmd/gitback@latest
• Local development builds
• Source builds between tagged releases

Release binaries continue to report the explicitly injected release version.

Upgrade Notes

No configuration changes are required.

Existing repository mirrors, gist mirrors, snapshots, and state files remain fully compatible.

GitBack v0.4.4

GitBack 0.4.x expands beyond repository backups and introduces GitHub Gist support, concurrent sync for repositories, improved operational visibility, backup correctness fixes, and self-healing filesystem recovery.

Highlights

1. GitHub Gist Backups

GitBack now backs up GitHub Gists alongside repositories.

2. Concurrent Repository Sync

Repository synchronization now runs using multiple workers, significantly improving sync performance for larger accounts.

3. Improved Health Reporting

• Healthy / Warning / Critical status levels
• Gist health metrics
• Better diagnostics and recommendations

4. Sync Visibility

Synchronization now includes:

• Improved CLI output
• Sync summaries
• Repository and gist statistics
• Better operational visibility

5. Backup Correctness Bug Fixes

Repository mirrors are now stored using unique owner/repository paths.

Before:

repositories/lawbot-api.git

Now:

repositories/FlareXes/legal-api.git
repositories/john/legal-api.git

This prevents collisions between repositories with identical names owned by different users or organizations.

6. Recovery Improvements

GitBack now automatically recovers from:

• Missing runtime directories
• Missing repository inventories
• Missing gist inventories

Recovery events are reported through logs and warnings instead of causing backup failures.

Upgrade Notes

Repository mirrors now use owner/repository paths.

Users upgrading from earlier versions should verify existing repository mirror locations before removing legacy mirrors.

GitBack v0.3.1

GitBack v0.3.1 focuses on operational usability, CLI experience, and clearer recovery guidance.

Highlights

1. Improved CLI Experience

Commands now provide clearer progress output, making it easier to understand what GitBack is doing during long-running operations.

Examples:

[SYNC] FlareXes/check-breach

[1/5] Verifying mirrors
[2/5] Creating archive
[3/5] Compressing snapshot

2. Better Error Messages

Configuration and runtime failures now provide clearer guidance and avoid exposing internal implementation details.

Example:

gitback is not initialized

Run: gitback init

3. Snapshot Force Mode

The snapshot bypass mirror state check flag has been renamed from:

--headless

to:

--force

This better reflects the actual behavior.

Example:

gitback snapshot --force

Improved Mirror Verification

Snapshot verification failures now include:

• List failed repository names
• Recommended recovery actions

Example:

mirror verification failed

Failed repositories:
 - FlareXes/check-breach

Recommended:
  gitback sync

Or create a snapshot anyway:
  gitback snapshot --force

Installation

go install github.com/flarexes/gitback/cmd/gitback@v0.3.1

GitBack v0.3.0

GitBack v0.3.0 focuses on reliability, retention management, and operational visibility.

Highlights

1. Retry & Backoff

Git operations now automatically retry on transient failures with backoff between attempts.

2. Snapshot Retention

Automatic snapshot retention is now available.

• Retention is disabled by default
• Old snapshots can be removed automatically
• Matching SHA256 checksum files are removed together with snapshots
• Retention actions are logged for auditing

3. Snapshot Collision Detection

GitBack now detects snapshot filename collisions before archive creation.

Existing snapshots are preserved and collisions are reported through structured logging.

4. Health Reporting

Improved gitback health command:

gitback health

Reports:

• Repository health
• Snapshot inventory
• Snapshot storage usage
• Disk availability
• Sync timestamps
• Retention configuration
• Warnings and recommendations

Output is JSON and suitable for automation.

Installation

go install github.com/flarexes/gitback/cmd/gitback@v0.3.0