snd-cli 0.1.0

Snapshot Diff: a lightweight filesystem time machine for folders

snd

Snapshot Diff: a lightweight filesystem time machine for folders.

snd is a small Python CLI tool that can snapshot a folder, compare the current state with an older snapshot, and restore files from backup-mode snapshots.

It is not a Git replacement. It is designed for quick local snapshots when Git is too much, unavailable, or inconvenient: downloaded archives, generated assets, datasets, configuration folders, temporary experiments, and risky refactors.

Features

• Snapshot any folder in seconds
• Compare current files with the latest or selected snapshot
• Detect added, deleted, and modified files
• Store metadata-only snapshots by default
• Optional backup mode with deduplicated file storage
• Restore one file, glob patterns, or the whole folder
• Dry-run restore preview
• Clean old snapshots and unused blobs
• Centralized storage outside the project folder
• No runtime dependencies

Installation

From source:

pip install .

After publication:

pip install snd-cli

Quick Start

Create a metadata-only snapshot:

snd snap . --name before\_changes

Create a restorable snapshot with file contents:

snd snap . --name before\_refactor --store-files

Show changes since the latest snapshot:

snd diff .

Show all snapshots for the folder:

snd list .

Restore one file from a snapshot:

snd restore . --from before\_refactor --file main.py

Restore Python files by pattern:

snd restore . --from before\_refactor --file "\*.py"

Preview a full restore without changing files:

snd restore . --from before\_refactor --all --dry-run

Restore the whole folder state:

snd restore . --from before\_refactor --all

Clean old snapshots and keep only the latest five:

snd clean . --keep 5

Storage

snd does not create service folders inside your project.

Snapshots are stored centrally:

• Linux: \~/.local/share/snd/
• macOS: \~/Library/Application Support/snd/
• Windows: %LOCALAPPDATA%\\\\snd\\\\

You can print the actual storage path:

snd where

You can override it with:

SND\_HOME=/custom/path snd snap .

Snapshot Modes

Metadata-only mode

Default mode:

snd snap .

Stores:

• file paths
• SHA-256 hashes
• sizes
• modification times
• file modes

This is lightweight and works well for diffing. It cannot restore file contents.

Backup mode

Enabled with:

snd snap . --store-files

or:

snd snap . --backup-mode

Stores file contents in a deduplicated blob storage. The same file content is stored only once even if it appears in multiple snapshots.

Use this mode when you want restore support.

Ignored Files

snd ignores common temporary and dependency folders by default:

• .git
• \_\_pycache\_\_
• node\_modules
• .venv
• venv
• dist
• build
• \*.pyc
• \*.log
• .DS\_Store

Add custom ignore patterns:

snd snap . --ignore "\*.png" --ignore "data/\*"

Example

Try it on the included demo project:

snd snap examples/demo\_project --name initial --store-files

Change a file:

echo "print('changed')" >> examples/demo\_project/app.py

Compare:

snd diff examples/demo\_project

Restore:

snd restore examples/demo\_project --from initial --file app.py

Commands

snd snap PATH \[--name NAME] \[--store-files]
snd diff PATH \[--with SNAPSHOT]
snd list PATH
snd restore PATH --from SNAPSHOT (--file PATTERN | --all) \[--dry-run]
snd clean PATH --keep N
snd where