Metadata-Version: 2.4
Name: snd-cli
Version: 0.1.1
Summary: Snapshot Diff: a lightweight filesystem time machine for folders
Author: CodeViz Lab
License-Expression: MIT
Keywords: snapshot,diff,backup,cli,filesystem,developer-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: System :: Archiving :: Backup
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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:

```bash
pip install .
```

After publication:

```bash
pip install snd-cli
```

## Quick Start

Create a metadata-only snapshot:

```bash
snd snap . --name before\_changes
```

Create a restorable snapshot with file contents:

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

Show changes since the latest snapshot:

```bash
snd diff .
```

Show all snapshots for the folder:

```bash
snd list .
```

Restore one file from a snapshot:

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

Restore Python files by pattern:

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

Preview a full restore without changing files:

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

Restore the whole folder state:

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

Clean old snapshots and keep only the latest five:

```bash
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:

```bash
snd where
```

You can override it with:

```bash
SND\_HOME=/custom/path snd snap .
```

## Snapshot Modes

### Metadata-only mode

Default mode:

```bash
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:

```bash
snd snap . --store-files
```

or:

```bash
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:

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

## Example

Try it on the included demo project:

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

Change a file:

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

Compare:

```bash
snd diff examples/demo\_project
```

Restore:

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

## Commands

```text
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
```

## 

