Vog

A lightweight, platform-agnostic CLI version control tool designed for high-frequency snapshots. Vog functions as a "shadow" system to preserve clean Git history while allowing rapid state saves.

Features

• Cross-Platform – Works on Linux, macOS, and Windows
• Content-Addressable Storage – Uses SHA-256 hashing with zlib compression for efficient blob storage
• Watcher Mode – Auto-save on file changes with a 5-second debounce
• Orphan Management – Safely stores untracked files during clean restores
• SQLite Database – Reliable snapshot metadata storage

Installation

Prerequisites

• Go 1.21 or later

Build from Source

cd vog
go build -o vog ./cmd/vog

The binary can be moved to your $PATH for global access:

sudo mv vog /usr/local/bin/

Quick Start

# Initialize vog in your project
vog init

# Save a snapshot
vog save -m "Initial snapshot"

# List recent snapshots
vog list

# Restore a specific snapshot
vog restore <snapshot_id>

Commands

vog init

Initializes vog in the current directory by creating a .vog/ hidden directory structure.

vog init

Output:

Initialized empty vog repository in .vog/

---

vog save -m "<message>"

Creates a snapshot of the current project state.

vog save -m "Added new feature"

Options:

• -m "<message>" – Required. A message describing the snapshot.

Output:

Saved snapshot 17e8f3a2b4c5d6e7: Added new feature (15 files)

---

vog list [--limit <n>]

Displays recent snapshots with their IDs, timestamps, and messages.

vog list
vog list --limit 10

Options:

• --limit <n> – Optional. Number of snapshots to display (default: 5)

Output:

ID                   | Time                 | Message
------------------------------------------------------------
17e8f3a2b4c5d6e7     | 04 Feb 25 10:30 IST | Added new feature
17e8f3a2b4c5d6e6     | 04 Feb 25 10:15 IST | Initial snapshot

---

vog restore <snapshot_id> [--clean]

Restores a previous snapshot.

vog restore 17e8f3a2b4c5d6e7
vog restore 17e8f3a2b4c5d6e7 --clean

Options:

• --clean – Optional. Moves untracked files (not in the snapshot) to the orphanage instead of leaving them.

Behavior:

• Files from the snapshot are restored to their original locations
• Existing files are overwritten
• With --clean, untracked files are moved to .vog/orphans/

---

vog watch

Starts a watcher that auto-saves snapshots when files change. Uses a 5-second debounce to batch rapid changes.

vog watch

Press Ctrl+C to stop.

Output:

Starting vog watcher... (Press Ctrl+C to stop)
Vog watcher started...
Change detected: main.go
Debounce expired, saving...
Auto-saving snapshot...
Saved snapshot 17e8f3a2b4c5d6e8: Auto-save by watcher (15 files)

---

vog orphans <subcommand>

Manages orphaned files created during clean restores.

vog orphans list

Lists all orphaned files.

vog orphans list

Output:

Event ID             | Time                 | Original Path                  | Trigger Snapshot
----------------------------------------------------------------------------------------------------
evt_17e8f3a2         | 04 Feb 25 10:30 IST | temp_file.go                   | 17e8f3a2b4c5d6e7

vog orphans restore <event_id> <file_path>

Restores a specific orphaned file.

vog orphans restore evt_17e8f3a2 temp_file.go

vog orphans clean [options]

Cleans up orphaned files.

vog orphans clean                        # Interactive prompt
vog orphans clean --force                # Remove all without prompt
vog orphans clean --id evt_17e8f3a2      # Remove specific event
vog orphans clean --older-than 7d        # Remove orphans older than 7 days

Options:

• --force – Skip interactive confirmation
• --id <event_id> – Remove orphans from a specific event
• --older-than <duration> – Remove orphans older than duration (supports d for days, or standard Go durations like 24h)

---

Storage Structure

Vog stores all data in the .vog/ directory:

.vog/
├── vog.db                 # SQLite database for snapshot metadata
├── objects/                # Content-addressable blob storage
│   └── <sha256-hash>       # Compressed file contents
├── orphans/                # Orphaned file storage
│   └── <sha256-hash>       # Compressed orphan contents
└── orphans_index.json      # Index of orphaned files

How It Works

1. Save: Each file's content is SHA-256 hashed and compressed using zlib. If the blob doesn't exist, it's stored in objects/.
2. Snapshots: A manifest of file paths and their blob hashes is stored in the SQLite database.
3. Restore: Blobs are decompressed and written to their original locations.
4. Orphans: During --clean restores, files not in the snapshot are moved to orphans/ with metadata for later recovery.

Ignored Directories

Vog automatically skips:

• .vog/ – Vog's own data directory
• .git/ – Git repository data

Dependencies

• fsnotify – Cross-platform file system notifications
• go-sqlite3 – SQLite driver for Go

Use Cases

• Rapid Prototyping: Save state frequently while experimenting without polluting Git history
• AI-Assisted Development: Create checkpoints during AI code generation sessions
• Learning Projects: Track progress without committing every small change
• Hot Reloading Development: Use watcher mode to auto-snapshot during active development

License

MIT License

---

Vog – Log your progress, not your Git history.