SnapBack

A command-line snapshot tool for capturing and restoring project states, independent of Git commits.

Overview

SnapBack allows developers to create instant snapshots of their project files, enabling easy rollback to previous states without manual copying or committing. Unlike Git, which only tracks changes after commits, SnapBack captures the exact state of your project directory at any moment.

Features

• 📸 Instant Snapshots: Capture project state in seconds
• 🔄 Easy Rollback: Restore to any previous snapshot
• 💾 Efficient Storage: Content-addressable storage with deduplication
• 🚫 Smart Ignoring: Automatically ignores node_modules, .git, and other common directories
• 🏷️ Named Snapshots: Give meaningful names to your snapshots
• 📋 Snapshot Listing: View all snapshots with timestamps and metadata
• 🗑️ Cleanup: Delete old snapshots and clean up unused storage
• 🔧 Cross-platform: Works on Linux, macOS, and Windows

Installation

From npm (Recommended)

# Install globally
npm install -g snapback-cli

# Or install locally in your project
npm install snapback-cli

From Source

# Clone the repository
git clone https://github.com/spacecypher/snapback.git
cd snapback

# Install dependencies
npm install

# Build the project
npm run build

# Link globally (optional)
npm link

Quick Start

Initialize SnapBack in your project

snapback init

Save a snapshot

# Save with auto-generated name
snapback save

# Save with custom name
snapback save "before-feature-x"

# Save with description
snapback save "initial-setup" --description "Project setup complete"

List snapshots

# Basic list
snapback list

# Detailed view
snapback list --verbose

Restore a snapshot

snapback restore "before-feature-x" --force

Delete a snapshot

snapback delete "old-snapshot" --force

Usage Examples

Basic Workflow

# Initialize SnapBack
$ snapback init
✓ SnapBack initialized successfully!

# Create initial snapshot
$ snapback save "initial-setup"
Creating snapshot...
✓ Snapshot 'initial-setup' saved at 2025-06-20T19:00:00Z
Files: 25, Size: 2.3 MB

# Work on your project...
# Make some changes...

# Save another snapshot before trying something risky
$ snapback save "before-refactor" --description "Before major refactoring"
Creating snapshot...
✓ Snapshot 'before-refactor' saved at 2025-06-20T20:15:00Z
Files: 28, Size: 2.8 MB

# Something went wrong? Restore easily
$ snapback restore "before-refactor" --force
Restoring snapshot 'before-refactor'...
✓ Restore complete. 28 files restored.

# View all snapshots
$ snapback list --verbose
Available snapshots:

1. before-refactor
   2025-06-20T20:15:00Z
   Files: 28, Size: 2.8 MB
   Description: Before major refactoring

2. initial-setup
   2025-06-20T19:00:00Z
   Files: 25, Size: 2.3 MB

# Clean up old snapshots
$ snapback delete "initial-setup" --force
Deleting snapshot 'initial-setup'...
✓ Snapshot 'initial-setup' deleted.

Command Reference

snapback init

Initialize SnapBack in the current directory. Creates .snapback/ folder and configuration.

snapback save [name] [options]

Create a new snapshot.

Options:

• -d, --description <description>: Add a description to the snapshot

Examples:

snapback save
snapback save "my-snapshot"
snapback save "feature-complete" --description "Feature X implementation done"

snapback restore <name> [options]

Restore files from a snapshot.

Options:

• -f, --force: Skip confirmation prompt

Examples:

snapback restore "my-snapshot" --force

snapback list [options]

List all available snapshots.

Options:

• -v, --verbose: Show detailed information including file count and size

Examples:

snapback list
snapback list --verbose

snapback delete <name> [options]

Delete a snapshot permanently.

Options:

• -f, --force: Skip confirmation prompt

Examples:

snapback delete "old-snapshot" --force

Configuration

SnapBack creates a .snapback/config.json file with default settings:

{
  "version": "1.0.0",
  "ignorePatterns": [
    ".snapback",
    "node_modules",
    ".git",
    "__pycache__",
    ".DS_Store",
    "*.log",
    ".env",
    ".env.local",
    ".env.*.local",
    "dist",
    "build",
    ".cache",
    ".tmp",
    ".temp"
  ]
}

You can customize the ignore patterns by editing this file.

How It Works

SnapBack uses a content-addressable storage (CAS) system:

1. File Hashing: Each file is hashed using SHA-256
2. Deduplication: Identical files across snapshots share the same storage blob
3. Manifests: Each snapshot stores a manifest mapping file paths to content hashes
4. Efficient Storage: Only unique file contents are stored, saving disk space

Directory Structure

your-project/
├── .snapback/
│   ├── blobs/              # Content-addressable file storage
│   │   ├── abc123...       # File content by hash
│   │   └── def456...
│   ├── snapshots/          # Snapshot manifests
│   │   ├── my-snapshot/
│   │   │   └── manifest.json
│   │   └── another-snapshot/
│   │       └── manifest.json
│   └── config.json         # Configuration and ignore patterns
├── src/
├── package.json
└── ...

Development

Build from Source

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Development mode
npm run dev save "test-snapshot"

Project Structure

src/
├── snapback.ts              # CLI entry point
├── core/
│   └── SnapBackManager.ts   # Core snapshot management logic
└── types/
    └── interfaces.ts        # TypeScript interfaces

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development

# Clone the repo
git clone https://github.com/spacecypher/snapback.git
cd snapback

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

Support

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Issues
• 💬 Questions: GitHub Discussions
• 📖 Documentation: README and Contributing Guide

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by the need for lightweight, Git-independent snapshots
• Built with TypeScript, Node.js, and Commander.js
• Thanks to all contributors and users