snap-vault-cli 0.1.0

Incremental smart backup CLI with content-addressed object storage

🗄️ snap-vault

Incremental smart backup CLI with content-addressed object storage

Zero dependencies · Pure Python stdlib · Blazing fast · Cross-platform

Installation · Usage · How It Works · Demo · Why snap-vault

---

🚀 What is snap-vault?

snap-vault is a command-line tool that takes incremental snapshots of any directory.

Instead of copying everything every time, it only stores what actually changed — using SHA-256 content hashing and a content-addressed object store (same strategy Git uses internally). Every snapshot is a full manifest, every object is stored exactly once, and you can restore any snapshot at any point in time.

Built entirely with Python's standard library. No external dependencies. No APIs. No cloud. Just fast, concurrent, local backup.

---

✨ Features

Feature	Description
📸 Incremental snapshots	Only changed files are stored — unchanged files are deduplicated automatically
🔐 Content-addressed storage	Files stored by SHA-256 hash, never duplicated on disk
⚡ Concurrent file I/O	ThreadPoolExecutor for fast parallel hashing and copying
🔍 Diff engine	See exactly what changed (added / modified / deleted) since the last snapshot
⏪ Point-in-time restore	Restore any snapshot by ID or default to the latest
📊 Snapshot history	Full timeline of snapshots with timestamps, file counts, and change stats
🎨 Beautiful terminal output	Colored progress bars, tables, and status icons
📦 Zero dependencies	Pure Python stdlib — works anywhere Python 3.9+ runs

---

📦 Installation

pip install snap-vault-cli

Or install from source:

git clone https://github.com/abdulrehman10raja/snap-vault-cli
cd snap-vault-cli
pip install -e .

Verify the install:

snap-vault --version
# snap-vault 0.1.0

---

🎬 Demo

$ snap-vault snap ./my-project ./my-vault

╭────────────────────────────────────────────────────────╮
│             SNAP-VAULT  ·  Taking Snapshot             │
╰────────────────────────────────────────────────────────╯

  → Source : /home/user/my-project
  → Vault  : ./my-vault
  ────────────────────────────────────────────────────────
  → Scanning source directory...
  → Found 42 file(s) — hashing concurrently...
  ████████████████████████████████ 100%
  ────────────────────────────────────────────────────────
  → Snapshot ID : 20260626_103000_123
  → Storing 5 new/modified object(s)...
  ████████████████████████████████ 100%
  ────────────────────────────────────────────────────────
  Added                          3
  Modified                       2
  Deleted                        0
  Unchanged                      37
  Objects stored                 5
  Deduplicated                   0
  Total size                     1.2 MB
  ────────────────────────────────────────────────────────
  ✓ Snapshot 20260626_103000_123 saved successfully.

---

🛠️ Usage

snap — Take an incremental snapshot

snap-vault snap <source> <vault>

snap-vault snap ./my-project ./my-vault

Scans the source directory, hashes all files concurrently, compares with the last snapshot, and stores only what changed. If nothing changed, it tells you instantly.

---

diff — See what changed since last snapshot

snap-vault diff <source> <vault>

snap-vault diff ./my-project ./my-vault

Shows every file that was added, modified, or deleted since the last snapshot — without taking a new one. Perfect for reviewing before committing a snapshot.

---

history — View all snapshots

snap-vault history <vault>

snap-vault history ./my-vault

Lists every snapshot in the vault with its timestamp, file count, and change statistics.

  20260626_014030_196
    Date                         2026-06-26  01:40:30
    Files                        42
    Added                        0
    Modified                     1
    Deleted                      0
    Total size                   1.2 MB

---

restore — Restore files from a snapshot

snap-vault restore <vault> <target> [--snap SNAPSHOT_ID]

# Restore latest snapshot
snap-vault restore ./my-vault ./restored-output

# Restore a specific snapshot by ID (point-in-time restore)
snap-vault restore ./my-vault ./restored-output --snap 20260626_103000_123

Restores all files from the chosen snapshot into the target directory. Creates the target if it doesn't exist.

---

⚙️ How It Works

snap-vault snap ./project ./vault
        │
        ▼
  Scan source directory
        │
        ▼
  Hash all files concurrently (SHA-256, ThreadPoolExecutor)
        │
        ▼
  Load previous manifest (if any)
        │
        ▼
  Compute diff (added / modified / deleted / unchanged)
        │
        ▼
  Store new/changed files as content-addressed objects
  (.snapvault/objects/ab/cdef1234...)
        │
        ▼
  Save new manifest with full file tree + stats
  (.snapvault/manifests/20260626_103000_123.json)

Vault Structure

my-vault/
└── .snapvault/
    ├── config.json                     ← vault metadata
    ├── manifests/
    │   ├── 20260626_103000_123.json    ← snapshot 1
    │   └── 20260626_120000_456.json    ← snapshot 2
    └── objects/
        ├── ab/
        │   └── cdef1234...             ← stored file content (by hash)
        └── 7f/
            └── 9a2b3c...

Objects are stored by the first 2 characters of their SHA-256 hash as a subdirectory — the same content-addressing strategy used by Git.

---

📊 Why snap-vault?

Feature	snap-vault	cp -r	rsync
Incremental (only changed files)	✅	❌	✅
Content deduplication	✅	❌	❌
Snapshot history	✅	❌	❌
Point-in-time restore	✅	❌	❌
Zero dependencies	✅	✅	❌
Cross-platform	✅	⚠️	⚠️
Colored CLI output	✅	❌	❌
Works offline	✅	✅	✅

---

🧱 Project Structure

snap-vault-cli/
├── snap_vault/
│   ├── __init__.py     ← version info
│   ├── __main__.py     ← entry point
│   ├── cli.py          ← argument parsing
│   ├── core.py         ← snap / diff / restore / history logic
│   ├── display.py      ← terminal colors, progress bars, tables
│   └── manifest.py     ← vault structure, object store, manifests
├── pyproject.toml
└── README.md

---

📋 Requirements

• Python 3.9+
• No external packages — stdlib only

---

📄 License

MIT © Abdul Rehman

---

👨💻 Author

Built by Abdul Rehman — BSCS student at FAST-NUCES Islamabad, AI Engineering Intern at Prime Innovators Global.

---

If you found this useful, please ⭐ star the repo — it helps a lot!