gitbak

package module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 15, 2025 License: MIT Imports: 0 Imported by: 0

README

gitbak logo

Tests Coverage Go Reference CodeRabbit Reviews

gitbak - Automatic Commit Safety Net

Automated checkpoint commits during programming sessions.

🎯 Purpose

When programming (with humans or AI assistants alike), the conversation and code changes can move quickly.

gitbak provides safety by:

  • Allowing you to focus on coding without worrying about losing changes
  • Creating automatic commits at regular intervals
  • Making a clean history of your pairing session progress
  • Providing recovery points if something goes wrong

This helps you avoid common pitfalls like the:

  • "I forgot to commit" panic
  • "I thought that git command did something else" confusion
  • "I lost my changes" frustration
  • "I wish we could go back to that thread we pulled on thirty minutes ago" regret

🌟 Features

  • Automatic Commits - Set and forget checkpoints at regular intervals
  • Branch Management - Creates a dedicated branch or uses current one
  • Session Continuation - Resume sessions with sequential commit numbering
  • Robust Error Handling - Smart retry logic and signal handling
  • Platform Support - Available for macOS and Linux systems

📦 Installation

# Option 1: Install with Homebrew (macOS and Linux)
brew install bashhack/gitbak/gitbak
# Note: Homebrew automatically adds gitbak to your PATH, so it's ready to use immediately

# Option 2: Install using Go (requires Go 1.24+)
go install github.com/bashhack/gitbak/cmd/gitbak@latest
# Note: Ensure your Go bin directory (typically $HOME/go/bin) is in your PATH
# You can add this to your shell profile (~/.bashrc, ~/.zshrc, etc.):
# export PATH=$PATH:$HOME/go/bin

# Option 3: Download pre-built binary
# Visit: https://github.com/bashhack/gitbak/releases

⚠️ Note: While a shell script implementation exists in the repository for historical reasons, it is unsupported and not recommended for use. The Go version provides better reliability, performance, and ongoing support.

🚀 Quick Start

# Navigate to your Git repository
cd /path/to/your/repo

# Start gitbak with default settings (5-minute commits)
gitbak

# Press Ctrl+C to stop when finished

💡 Best Practice: Manual + Automatic Workflow

A powerful workflow pattern with gitbak is combining automatic safety checkpoints with manual milestone commits:

# Start gitbak on your current branch
gitbak -no-branch

# While gitbak creates automatic commits, you can still:
git add <files>
git commit -m "Implement login feature"

# gitbak continues creating safety checkpoints while you create
# meaningful commits for important milestones

This gives you both a detailed safety net AND a clean, meaningful commit history - the best of both worlds!

💪 See Comparison with Alternatives for why this approach is superior to IDE auto-save features.

🔄 After Your Session

# Squash all checkpoint commits into one
git checkout main
git merge --squash gitbak-TIMESTAMP 
git commit -m "Complete feature implementation"

⚙️ Configuration

# Custom interval (2 minutes)
gitbak -interval 2

# Custom branch name
gitbak -branch "feature-work-backup"

# Continue a previous session
gitbak -continue

# Use the current branch
gitbak -no-branch

# Full options list
gitbak -help

📚 Documentation

📋 Implementation Details

Feature Details
Dependencies Git only
Platform macOS and Linux
Configuration Command-line flags and environment variables
Resource usage ~5-6 MB

Development

# Clone the repository
git clone https://github.com/bashhack/gitbak.git
cd gitbak

# Run tests
make test

# Run tests in Ubuntu container (simulates GitHub Actions environment)
./scripts/test-all.sh

# Test specific packages in Ubuntu container
./scripts/ubuntu-test.sh ./internal/lock/...

# Build for development
make build

# Install locally
make install

See the scripts README for more information on testing in Ubuntu containers to catch platform-specific issues before they reach CI.

📄 License

MIT

Documentation

Overview

Package gitbak is an automatic commit safety net

gitbak automatically commits changes to git at regular intervals, providing a safety net for programming sessions. It's especially valuable for pair programming, long coding sessions, or exploratory coding where you want to focus on the work rather than remembering to commit. It runs as a background process that monitors your repository and creates sequential, numbered commits.

While gitbak creates automatic checkpoint commits, you can still make your own meaningful manual commits at important milestones. This powerful combination gives you both a detailed safety net AND a clean, meaningful commit history - the best of both worlds.

Quick Start 

# Navigate to your Git repository
cd /path/to/your/repo

# Start gitbak with default settings (5-minute commits)
gitbak

# Press Ctrl+C to stop when finished

Key Features

  • Automatic Commits: Creates commits at regular intervals (default: 5 minutes)
  • Branch Management: Creates a dedicated branch or uses the current one
  • Session Continuation: Resume sessions with sequential numbering
  • Robust Error Handling: Smart retry logic and graceful signal handling

Documentation Structure

The gitbak documentation is organized into several sections:

Module Structure

The module is organized into these packages:

  • cmd/gitbak: Command-line interface
  • internal/git: Git operations and commit logic
  • internal/config: Configuration and flag parsing
  • internal/lock: File-based locking mechanism
  • internal/logger: Logging facilities
  • internal/errors: Error handling utilities
  • internal/constants: ASCII art and fixed values

Common Configuration Options 

# Run with 2-minute intervals
gitbak -interval 2

# Use a custom branch name
gitbak -branch "my-backup-branch"

# Continue a previous session
gitbak -continue

# Use the current branch instead of creating a new one
gitbak -no-branch

After Your Session

When your session is complete, you can squash all checkpoint commits into one: 

# Switch back to your main branch
git checkout main

# Combine all gitbak commits into a single change set
git merge --squash gitbak-TIMESTAMP

# Create a single, meaningful commit with all changes
git commit -m "Complete feature implementation"

Design Philosophy

gitbak is designed with the following principles in mind:

  • Simple Usage: Provide a straightforward interface for common use cases
  • Robustness: Handle errors gracefully and recover when possible
  • Non-Intrusion: Stay out of the way of the developer's primary workflow
  • Safety: Avoid data loss and never push to remote repositories
  • Transparency: Make it clear what operations are being performed

Platform Support

gitbak is available for:

  • macOS (Intel and Apple Silicon)
  • Linux (x86_64, ARM64)
  • Unix-like systems with a POSIX-compliant shell

Implementation Notes

gitbak uses the command-line Git executable rather than a Go Git library to ensure compatibility with all Git features and repository configurations. Commands are executed through an abstracted interface that can be replaced for testing.

The application handles signals (such as SIGINT, SIGTERM, and SIGHUP) to ensure proper cleanup and summary display even when terminated unexpectedly.

Source Files

View all Source files

Directories

Path Synopsis
cmd
gitbak command
Package main implements gitbak, an automatic commit safety net
 Package main implements gitbak, an automatic commit safety net
internal
config
Package config provides configuration handling for the gitbak application.
 Package config provides configuration handling for the gitbak application.
constants
Package constants provides application-wide constant values for the gitbak application.
 Package constants provides application-wide constant values for the gitbak application.
errors
Package errors provides error handling utilities for the gitbak application.
 Package errors provides error handling utilities for the gitbak application.
git
Package git provides Git operations for the gitbak application.
 Package git provides Git operations for the gitbak application.
lock
Package lock provides file-based locking for the gitbak application.
 Package lock provides file-based locking for the gitbak application.
logger
Package logger provides logging facilities for the gitbak application.
 Package logger provides logging facilities for the gitbak application.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.