{"id":26455091,"url":"https://github.com/open-technology-foundation/checkpoint","last_synced_at":"2026-04-09T09:55:20.724Z","repository":{"id":282212013,"uuid":"947840562","full_name":"Open-Technology-Foundation/checkpoint","owner":"Open-Technology-Foundation","description":"A simple, reliable utility for creating codebase snapshots (checkpoints) during development.","archived":false,"fork":false,"pushed_at":"2025-03-13T10:32:10.000Z","size":17,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-13T11:31:50.679Z","etag":null,"topics":["backup-tool","bash","linux","macos"],"latest_commit_sha":null,"homepage":"https://yatti.id/","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Open-Technology-Foundation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-13T10:30:28.000Z","updated_at":"2025-03-13T10:34:05.000Z","dependencies_parsed_at":"2025-03-13T14:00:33.855Z","dependency_job_id":null,"html_url":"https://github.com/Open-Technology-Foundation/checkpoint","commit_stats":null,"previous_names":["open-technology-foundation/checkpoint"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fcheckpoint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fcheckpoint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fcheckpoint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Open-Technology-Foundation%2Fcheckpoint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Open-Technology-Foundation","download_url":"https://codeload.github.com/Open-Technology-Foundation/checkpoint/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244301005,"owners_count":20430847,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backup-tool","bash","linux","macos"],"created_at":"2025-03-18T20:29:57.918Z","updated_at":"2026-04-09T09:55:20.717Z","avatar_url":"https://github.com/Open-Technology-Foundation.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Checkpoint\n\nA powerful cross-platform utility for creating, managing, and restoring timestamped snapshots of directories. Designed specifically for developers, system administrators, and DevOps engineers who need reliable recovery points during iterative development and system configuration changes.\n\n## Overview\n\nCheckpoint bridges the gap between informal backup practices and enterprise-grade snapshot management by providing simple commands for complex operations. Create recovery points before risky changes, track development progress through organized snapshots, and quickly restore when needed—all while maintaining security and automation compatibility.\n\n### Key Benefits\n\n- **Development Safety**: Create quick recovery points before risky code changes\n- **Visual Change Tracking**: Compare differences between snapshots to understand evolution\n- **Flexible Recovery**: Restore entire directories or specific file patterns\n- **Cross-Platform**: Consistent behavior on Linux and macOS systems\n- **Automation Ready**: Works reliably in CI/CD pipelines and scripts\n- **Non-Root Friendly**: Works seamlessly for regular users with smart directory defaults\n\n## Core Features\n\n- **Smart Snapshots**: Creates timestamped backups with automatic exclusions\n- **Intelligent Defaults**: Automatically selects appropriate backup directories based on user privileges\n- **Atomic Operations**: Ensures backup integrity with temporary directories and atomic rename\n- **Concurrency Protection**: Lockfile mechanism prevents data corruption from parallel operations\n- **Powerful Comparison**: Visualizes differences between snapshots with color-coded output\n- **Flexible Restoration**: Supports complete or selective file recovery with preview mode\n- **Space Optimization**: Uses hardlinking between versions to minimize disk usage\n- **Backup Rotation**: Manages history by count or age for automatic cleanup\n- **Automation Support**: Non-interactive operation with timeout safeguards\n- **Smart Privilege Handling**: Only escalates privileges when necessary, works without sudo\n\n## Installation\n\n### One-Line Install\n\n```bash\n# Install with automatic dependency installation\ncurl -fsSL https://raw.githubusercontent.com/Open-Technology-Foundation/checkpoint/main/install.sh | bash\n\n# Or with wget\nwget -qO- https://raw.githubusercontent.com/Open-Technology-Foundation/checkpoint/main/install.sh | bash\n\n# Install to custom location (no sudo required)\ncurl -fsSL https://raw.githubusercontent.com/Open-Technology-Foundation/checkpoint/main/install.sh | INSTALL_DIR=~/.local/bin bash\n```\n\nThe installer also:\n- Creates a `chkpoint` symlink for convenience\n- Installs the man page (`man checkpoint`)\n- Installs bash completion for tab completion\n\n### Manual Install\n\n```bash\n# Download script and make executable\ncurl -fsSL https://raw.githubusercontent.com/Open-Technology-Foundation/checkpoint/main/checkpoint -o checkpoint\nchmod +x checkpoint\nsudo cp checkpoint /usr/local/bin/\n\n# Install man page\ncurl -fsSL https://raw.githubusercontent.com/Open-Technology-Foundation/checkpoint/main/checkpoint.1 -o checkpoint.1\nsudo cp checkpoint.1 /usr/local/share/man/man1/\nsudo mandb\n\n# Install bash completion\ncurl -fsSL https://raw.githubusercontent.com/Open-Technology-Foundation/checkpoint/main/checkpoint.bash_completion -o checkpoint.bash_completion\nsudo cp checkpoint.bash_completion /usr/share/bash-completion/completions/checkpoint\n\n# Optional: Install hardlink for space efficiency\nsudo apt install hardlink  # Ubuntu/Debian\n# or\nbrew install hardlink       # macOS\n```\n\n### Requirements\n\n**Core Dependencies** (required):\n- `rsync` - File synchronization\n- `find` - File discovery\n- `stat` - File metadata\n\n**Optional Dependencies**:\n- `hardlink` - Space-efficient backup storage\n- `delta` or `colordiff` - Enhanced diff visualization\n\n## Quick Start\n\n### For Non-Root Users\n\n```bash\n# Create checkpoint of current directory (backs up to ~/.checkpoint/)\ncheckpoint\n\n# Backup a specific directory\ncheckpoint ~/my-project\n\n# Use custom backup location\ncheckpoint -d ~/backups/project ~/my-project\n\n# Set default backup directory for all operations\nexport CHECKPOINT_BACKUP_DIR=~/my-backups\ncheckpoint ~/my-project\n```\n\n### Basic Operations\n\n```bash\n# Create checkpoint of current directory\ncheckpoint\n\n# Create checkpoint with descriptive name\ncheckpoint -s \"before-refactor\"\n\n# List all checkpoints\ncheckpoint --list\n\n# Restore latest checkpoint\ncheckpoint --restore\n\n# Compare current files with checkpoint\ncheckpoint --restore --diff\n```\n\n## Usage Examples\n\n### Development Workflow\n\n```bash\n# Before major changes\ncheckpoint -s \"pre-api-refactor\"\n\n# Compare with previous state\ncheckpoint --restore --diff\n\n# Restore if needed\ncheckpoint --restore --from 20250430_091429\n```\n\n### System Administration\n\n```bash\n# Backup configuration before updates\nsudo checkpoint -d /var/backups/system /etc\n\n# Web server configuration checkpoint\ncheckpoint -s \"ssl-optimization\" /etc/nginx\n\n# Compare configuration changes\ncheckpoint --from 20250430_091429 --compare-with 20250430_101530 --detailed\n```\n\n### Selective Operations\n\n```bash\n# Restore only specific files\ncheckpoint --restore --files \"*.js\" --files \"docs/*.md\"\n\n# Dry run to preview changes\ncheckpoint --restore --dry-run\n\n# Custom backup location\ncheckpoint -d ~/backups/myproject\n\n# Exclude specific patterns\ncheckpoint --exclude \"node_modules/\" --exclude \"*.log\"\n```\n\n### Backup Management\n\n```bash\n# Automatic rotation: keep only 5 most recent\ncheckpoint --keep 5\n\n# Age-based rotation: remove backups older than 30 days\ncheckpoint --age 30\n\n# Prune without creating new backup\ncheckpoint --prune-only --keep 3\n```\n\n### Concurrency Protection\n\nCheckpoint includes a lockfile mechanism to prevent data corruption from concurrent operations:\n\n```bash\n# Normal operation (locking enabled by default)\ncheckpoint\n\n# Disable locking (DANGEROUS - allows concurrent operations)\ncheckpoint --no-lock\n\n# Set custom lock timeout (default: 300 seconds)\ncheckpoint --lock-timeout 60\n\n# Force removal of stale locks\ncheckpoint --force-unlock\n```\n\nThe locking mechanism:\n- Prevents multiple checkpoint instances from operating on the same backup directory\n- Automatically detects and removes stale locks from crashed processes\n- Can be disabled for special use cases (use with caution)\n\n## Command Reference\n\n### Core Options\n\n| Option | Description |\n|--------|-------------|\n| `-d, --backup-dir DIR` | Custom backup location (default: context-dependent) |\n| `-s, --suffix SUF` | Add descriptive suffix to checkpoint name |\n| `-n, --no-hardlink` | Do not hardlink to previous backup |\n| `--hardlink` | Hardlink to previous backup (default if available) |\n| `-q, --quiet` | Minimal output (just backup path) |\n| `-v, --verbose` | Detailed output with progress (default) |\n| `-l, --list` | List existing checkpoints with sizes |\n| `-x, --exclude PATTERN` | Additional exclusion pattern (repeatable) |\n| `-V, --version` | Print version and exit |\n| `-h, --help` | Display help |\n\n### Backup Management\n\n| Option | Description |\n|--------|-------------|\n| `--keep N` | Keep only N most recent backups |\n| `--age DAYS` | Remove backups older than DAYS days |\n| `-p, --prune-only` | Only prune backups without creating new one |\n| `--no-sudo` | Never attempt privilege escalation |\n| `--no-lock` | Disable lockfile mechanism (DANGEROUS) |\n| `--lock-timeout N` | Lock acquisition timeout in seconds (default: 300) |\n| `--force-unlock` | Force removal of stale locks |\n\n### Restore and Compare\n\n| Option | Description |\n|--------|-------------|\n| `-r, --restore` | Restore from checkpoint |\n| `-f, --from ID` | Source checkpoint (defaults to most recent) |\n| `-t, --to DIR` | Target restore directory (defaults to original) |\n| `--dry-run` | Preview changes without making them |\n| `--diff` | Show differences between current files and checkpoint |\n| `--compare-with ID` | Compare two checkpoints |\n| `--detailed` | Show file content differences in comparison |\n| `--files PATTERN` | Select specific files/patterns (repeatable) |\n\n## Automation Integration\n\n### Environment Variables\n\n```bash\n# Set default backup directory for all operations\nexport CHECKPOINT_BACKUP_DIR=~/my-backups\n\n# Skip interactive prompts\nexport CHECKPOINT_AUTO_CONFIRM=1\n```\n\n### CI/CD Examples\n\n```bash\n# GitHub Actions / GitLab CI\n- name: Create Checkpoint\n  run: CHECKPOINT_AUTO_CONFIRM=1 checkpoint -s \"build-${GITHUB_RUN_NUMBER}\"\n\n# Jenkins Pipeline\nstage('Backup') {\n    steps {\n        sh 'CHECKPOINT_AUTO_CONFIRM=1 checkpoint -s \"build-${BUILD_NUMBER}\"'\n    }\n}\n\n# Cron job for regular backups\n0 2 * * * CHECKPOINT_AUTO_CONFIRM=1 /usr/local/bin/checkpoint -d /var/backups/nightly /home/user/project\n```\n\n### Timeout Protection\n\nAll interactive prompts have built-in timeouts:\n- Directory creation: 30 seconds\n- Restore confirmation: 30 seconds  \n- Checkpoint selection: 60 seconds\n\n## Backup Directory Locations\n\n### Smart Directory Selection\n\nCheckpoint intelligently selects backup directories based on your user context:\n\n| User Type | Default Location | Example |\n|-----------|------------------|---------|\n| Root/sudo | `/var/backups/FULL/PATH/` | `/var/backups/home/user/myproject/` |\n| Regular user | `~/.checkpoint/FULL/PATH/` | `~/.checkpoint/home/user/myproject/` |\n| Custom | `$CHECKPOINT_BACKUP_DIR/FULL/PATH/` | `~/backups/home/user/myproject/` |\n\nThe full canonical source path (with leading `/` stripped) is used as the subdirectory, preventing collisions when backing up different directories with the same basename.\n\n### Privilege Management\n\n- **Automatic Detection**: Checkpoint only requests sudo when the backup directory requires it\n- **Non-Root Friendly**: Regular users can backup to any writable directory without sudo\n- **Explicit Control**: Use `--no-sudo` to prevent any privilege escalation\n- **Smart Escalation**: If a directory needs privileges and sudo is available, checkpoint will automatically escalate\n\n```bash\n# Force non-root operation\ncheckpoint --no-sudo ~/myproject\n\n# Let checkpoint decide (recommended)\ncheckpoint ~/myproject\n```\n\n## Default Exclusions\n\nThese patterns are automatically excluded from all backups:\n- Backup directory itself (prevents recursion)\n- `.gudang/`, `temp/`, `.temp/`, `tmp/` directories\n- Temporary files: `*~` and `~*`\n- `.tmp.*` directories (atomic operation temporaries)\n- `.checkpoint.lock/` directories (concurrency locks)\n\n## Storage and Performance\n\n### Space Efficiency\n\nWith hardlinking enabled, checkpoint can achieve 90%+ space savings between similar versions by sharing identical files. Example:\n\n```bash\n# First backup: 100MB\ncheckpoint -s \"v1.0\"\n\n# Second backup: Only changed files use additional space\ncheckpoint -s \"v1.1\"  # Might only use 5MB additional space\n```\n\n### Atomic Operations\n\nCheckpoint uses atomic operations to ensure backup integrity:\n\n- **Temporary Directory**: Backups are created in a `.tmp.*` directory first\n- **Atomic Rename**: Only after all operations succeed is the backup renamed to its final name\n- **Automatic Cleanup**: Temporary directories are removed on interruption or failure\n- **No Partial States**: You'll never see incomplete or corrupted backups\n\nThis means:\n- Interrupted backups leave no trace\n- Concurrent operations are safe (with locking enabled)\n- Backup directories appear instantaneously when complete\n- Failed operations are automatically cleaned up\n\n### Performance Characteristics\n\n- **Backup Speed**: Limited by rsync performance and storage I/O\n- **Comparison Speed**: Optimized with size-based verification for large datasets\n- **Scalability**: Handles projects from small configs to large codebases\n- **Memory Usage**: Minimal footprint, primarily shell variables\n\n## Development\n\n### Testing\n\n```bash\n# Lint code (must pass without errors)\nshellcheck checkpoint\n\n# BCS compliance check\nbcscheck checkpoint\n\n# Run all test suites with summary\n./run_all_tests.sh\n\n# Run all test suites\nbats tests/*.bats\n\n# Run individual test suites\nbats tests/test_checkpoint.bats    # Core functionality (28 tests)\nbats tests/test_locking.bats       # Concurrency protection (10 tests)\nbats tests/test_atomic.bats        # Atomic operations (6 tests)\nbats tests/test_nonroot.bats       # Non-root user operations (9 tests)\n\n# Run specific test by name\nbats tests/test_checkpoint.bats -f \"backup creation\"\n\n# Verbose testing\nbats -v tests/test_checkpoint.bats\n```\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make changes following existing code style:\n   - 2-space indentation (never tabs)\n   - `set -euo pipefail` error handling\n   - Use `[[` for conditionals, `(( ))` for arithmetic\n   - `UPPER_CASE` for global variables, `lowercase` for local variables\n   - Comprehensive function documentation headers\n   - BATS tests for new functionality\n   - End all scripts with `#fin` marker\n4. Run `shellcheck checkpoint` (must pass without errors)\n5. Run `bats tests/*.bats` (all tests must pass)\n6. Submit pull request\n\n## Troubleshooting\n\n### Common Issues\n\n**Permission Denied**: Use `--no-sudo` for user-accessible directories or ensure sudo access.\n\n**Insufficient Disk Space**: Check available space in backup directory before large operations.\n\n**Command Not Found**: Ensure all required dependencies (`rsync`, `find`, `stat`) are installed.\n\n**Failed to Acquire Lock**: Another checkpoint process may be running. Use `--force-unlock` to remove stale locks from crashed processes, or wait for the other operation to complete.\n\n### Comparing with Checkpoints\n\n```bash\n# Compare with source to check differences\ncheckpoint --restore --diff\n```\n\n## Security\n\n- **Input Validation**: Strict pattern matching prevents injection attacks\n- **Path Protection**: Prevents directory traversal attacks\n- **Privilege Management**: Optional sudo with explicit bypass option\n\n## License\n\nThis project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details.\n\n## Version\n\nCurrent version: **1.7.1**\n\n### Recent Features\n\n#### v1.7.1 - BCS Compliance and Bug Fixes\n- **UPPER_CASE globals**: All 23 global configuration variables renamed to UPPER_CASE convention for clear distinction from local variables\n- **Stream separation**: Status messages now routed to stderr via messaging functions; only data output (backup paths, list output) goes to stdout\n- **New `success()` function**: Completes the messaging system (`info`, `success`, `warn`, `error`)\n- **Bug fix**: Fixed `backup_timestamp` unreachable guard in `prune_backups()` under `inherit_errexit`\n- **Performance**: Replaced 6 external `basename` calls with `${var##*/}` parameter expansion\n- **Arithmetic fix**: Replaced `-gt` in `[[ ]]` with `(( ))` for BCS0501 compliance\n\n#### v1.7.0 - Simplification\n- **Removed unused features**: Removed `--debug`, `--verify`, `--metadata`, and `--remote` options\n- **Reduced codebase**: Cut ~970 lines of unused code for easier maintenance\n- **Simplified CLI**: Fewer options, clearer purpose\n\n#### v1.6.1 - Documentation and Tooling\n- **Comprehensive manpage**: Full Unix manpage with all 35+ options documented\n- **Enhanced bash completion**: Dynamic checkpoint ID completion for restore/compare operations\n- **Script documentation**: All scripts updated with headers, usage docs, and #fin markers\n- **Installer improvements**: Now installs manpage and bash completion automatically\n- **Fixed test scripts**: Corrected corrupted shebangs and BCS compliance issues\n\n#### v1.6.0 - Code Quality and Standards Compliance\n- **Full BASH-CODING-STANDARD.md compliance**: Refactored entire codebase to meet strict coding standards\n- **Enhanced messaging system**: New standardized output functions with visual indicators (✓ for success, ✗ for errors)\n- **Improved variable handling**: Proper type declarations for all variables (integers, arrays, strings)\n- **Better error handling**: Consistent error codes and messaging throughout\n- **Verification improvements**: Fixed file exclusion handling during backup verification\n- **Code modernization**: Updated arithmetic operations, fixed shellcheck warnings, improved quoting\n\n#### v1.5.0 - Atomic Operations\n- Implemented atomic backup operations using temporary directories\n- Added automatic cleanup of interrupted operations\n- Ensured backup integrity with atomic rename after completion\n- Applied atomic pattern to both local and remote operations\n\n#### v1.4.0 - Concurrency Protection\n- Added lockfile mechanism to prevent concurrent operations\n- Implemented PID-based lock ownership verification\n- Added stale lock detection and automatic cleanup\n- Introduced --no-lock, --lock-timeout, and --force-unlock options\n\nFor detailed version history, see the commit log or check `checkpoint --version`.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-technology-foundation%2Fcheckpoint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-technology-foundation%2Fcheckpoint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-technology-foundation%2Fcheckpoint/lists"}