snapr

Version 0.1.0 · Open source · Command-line tool

Keep every state of your project. Go back to any of them.

Snapr saves snapshots of a project folder, exactly as it is. See what changed, return to an earlier version of your files, and check that everything you saved is still intact. Data that didn’t change is stored once, however many snapshots you keep.

Get started View on GitHub

Snapr today is a command-line tool that you build from source. There is no graphical app.

  1. #13 files

    first cut

     

    6 pieces stored

  2. #24 files

    slower intro, first render

    └─ from #1

    4 reused · 3 stored

  3. #33 files · current

    alternate cut

    └─ from #1

    5 reused · 1 stored

stored for this snapshot already stored, reused Three complete states of the sample project from the demo below. Their files are made of 19 pieces in total; Snapr stored 10.

01 — Why

A folder only remembers its latest state.

When you want to keep an earlier version of a project, the usual answer is to copy the folder. Then copy it again.

  • opening-sequence/
  • opening-sequence_v2/
  • opening-sequence_v2_final/
  • opening-sequence_v2_final_REAL/

Every copy stores everything again, including the large files that never changed. Nothing tells you what is different between two copies, going back means moving files around by hand, and you have no way to know whether an old copy is still intact.

What Snapr does instead

Snapr keeps the history inside the project folder. Each time you save, it records the complete state of the folder with a message you write, and stores only the data it has not seen before.

Later you can list those states, compare any two, and put the folder back the way it was.

Who it is for

Snapr is being built for people whose projects are folders of large, changing files: datasets and notebooks, model files, 3D scenes, edits and renders.

Where it stands today: you need to be comfortable in a terminal to use it. Making Snapr usable without one is a direction for the project, not something that exists yet.

Snapr is not a replacement for Git. Git is built for collaborating on source code. Snapr is built for reproducing whole working folders.

02 — What it does

Six things, all in version 0.1.0.

  • Save a recoverable state

    One command records every file in the folder as a numbered snapshot with your message. Files that have not changed since the last save are not read again.

    snapr save "first cut"

  • See what changed

    List the files added, modified, and removed since your last snapshot, or between any two snapshots. Two versions of a file are compared by their contents.

    snapr status snapr diff 1 2

  • Return to an earlier version

    Put the folder back exactly as it was in any snapshot. Only the files that differ are rewritten, and you can preview the result first.

    snapr restore 1 --dry-run

  • Store unchanged data once

    Files are stored as pieces. A piece that is already stored is never stored again, whether it comes from the same file, another file, or an older snapshot. Every piece is compressed.

  • Follow how the project evolved

    Each snapshot records the one it was saved from. Go back to an earlier state, continue in a different direction, and both lines of work are kept.

    snapr history

  • Check that your history is intact

    Snapr re-reads every stored piece that a snapshot depends on and confirms it is present and unaltered. Anything missing or damaged is listed.

    snapr verify

03 — Demo

A short session, start to finish.

This is unedited output from Snapr 0.1.0, run on a sample project folder: a 9 MB scene file, a 4 MB data file, and a page of notes. The file names are examples.

  1. Save the first state

    Start tracking the folder, then save. Everything is new, so everything is stored.

    $ snapr init
✓ Initialized Snapr workspace

$ snapr save "first cut"
✓ Snapshot 1 created
  "first cut"

────────────────────────────────────────

Workspace
  Files processed : 3
  Chunks processed: 6
  Size of processed files  : 13.20 MB

Object Store
  New chunks      : 6
  Reused chunks   : 0
  Additional Storage : 10.51 MB

Efficiency
  Chunk reuse     : 0.00%
  Compression saved : 20.33%

Snapshot complete 📸.

  2. Work, then see what changed

    More rows were added to the data file, the notes were edited, and a render was added.

    $ snapr status
Current Workspace Status
1 added · 2 modified

 Added
+ renders/frame_0001.exr

 Modified
~ data/takes.csv
~ notes.md

  3. Save again

    The scene file did not change, so it was not read at all. The data file grew at the end, so its first piece was reused and only the changed piece was stored. 

    $ snapr save "slower intro, first render"
✓ Snapshot 2 created
  "slower intro, first render"

────────────────────────────────────────

Workspace
  Files processed : 4
  Chunks processed: 4
  Size of processed files  : 6.83 MB

Object Store
  New chunks      : 3
  Reused chunks   : 1
  Additional Storage : 2.55 MB

Efficiency
  Chunk reuse     : 25.00%
  Compression saved : 62.73%

Snapshot complete 📸.

  4. Preview going back

    A dry run reports what a restore would do and changes nothing. Running the same command without --dry-run performs it. 

    $ snapr restore 1 --dry-run
Restore Preview — Snapshot 1

────────────────────────────────────────

Workspace Changes
  Would restore : 2 files
  Would remove: 1 files
  Unchanged: 1 files

No changes were made to the workspace.

  5. Look at the history

    After restoring snapshot 1 and saving a different version of the notes, there are two lines of work. Both start from snapshot 1, and both are kept. 

    $ snapr history
Snapshot history (3 snapshots)
────────────────────────────────────────────────────────────────
- #3  Oct 11, 8:42 PM
  alternate cut
  └─ from #1
  3 files · 58 B processed
  +1 chunks · +83 B storage

  #2  Oct 11, 8:42 PM
  slower intro, first render
  └─ from #1
  4 files · 6.83 MB processed
  +3 chunks · +2.55 MB storage

  #1  Oct 11, 8:42 PM
  first cut
  3 files · 13.20 MB processed
  +6 chunks · +10.51 MB storage

────────────────────────────────────────────────────────────────
Storage: 13.06 MB

- current snapshot

  6. Confirm it is all still there

    Three snapshots refer to 19 pieces of data. Ten are unique, and each one is read back, decompressed, and checked. 

    $ snapr verify
✓ Repository verified

────────────────────────────────────────

Snapshots
  Checked           : 3

File versions
  Checked           : 7

Chunks
  Unique            : 10
  Referenced        : 19
  Verified          : 10
  Issues            : 0

Data
  Content verified  : 15.83 MB

✓ No integrity issues found.

The sample files were generated for this demonstration: the scene file is random data, which does not compress, and the data file is text, which does. Your results depend on your files. This is an illustration of how Snapr reports its work, not a benchmark.

04 — How it works

The engineering, in plain terms.

You do not need any of this to use Snapr. It is here for anyone who wants to know what happens to their files.

  1. Files are split into pieces

    Each file is read in pieces of 4 MiB. Engineers call this chunking. A large file is never loaded into memory whole.

  2. Each piece is named by its content

    Snapr computes a SHA-256 fingerprint of every piece and stores the piece under that name. This is content-addressed storage: the name says what is inside.

  3. Identical pieces are stored once

    If a piece with the same fingerprint is already stored, nothing is written. This deduplication applies within a file, between files, and across every snapshot.

  4. Pieces are compressed

    Every stored piece is compressed with Zstandard. How much space that saves depends on the data; media that is already compressed gains little.

  5. A snapshot is a list, not a copy

    A snapshot records each file and the fingerprints of its pieces, in order, along with your message, the time, and the snapshot it was saved from. That last link is what lets history split into separate lines.

  6. Verification re-checks everything

    Because a piece is named by its fingerprint, Snapr can prove it is intact: read it, decompress it, fingerprint it again, and compare. snapr verify does this for every piece a snapshot uses.

One limit worth knowing

Pieces are cut at fixed positions. If you insert data near the start of a large file, everything after it shifts, and the rest of that file is stored again. Edits in place and data added at the end reuse well.

05 — Get started

Install it and take a first snapshot.

1 Install

Snapr is built from source. You need Git and a recent stable Rust toolchain, version 1.85 or newer. 

git clone https://github.com/LukoOG/Snapr.git
cd Snapr
cargo install --path .

This puts the snapr program in Cargo’s bin directory.

2 Use it

Open a terminal in the top level of your project folder and run every command from there.

snapr init
snapr save "initial"

Change some files, then:

snapr status
snapr restore 1 --dry-run

Before you restore

snapr restore changes your folder without asking for confirmation. Files that differ from the snapshot are overwritten, and files that are not in the snapshot are deleted, including new files you have never saved. Save first if you want to keep your current state, and use --dry-run to see what would happen.

All commands

snapr initStart tracking the current folder.
snapr save <message>Save a snapshot.
snapr statusChanges since the current snapshot.
snapr diff <old> <new>Changes between two snapshots.
snapr restore <id>Return the folder to a snapshot. Add --dry-run to preview, or --force to discard changes made since the current snapshot.
snapr historyList all snapshots.
snapr verifyCheck everything stored.

What to expect from 0.1.0

  • It is a command-line tool. There is no graphical interface.
  • Everything is kept on your machine, in a .snapr folder inside the project.
  • Snapr records the contents of regular files. It does not record permissions, timestamps, symbolic links, or empty folders.
  • Folders named .git, target, and .snapr, and files named .DS_Store, are skipped. This list cannot be changed yet.
  • Snapshots and stored data cannot be deleted yet.
  • Run one Snapr command at a time in a folder.

The full list is in the architecture document.

06 — Documentation

Read how it is built.

Try it on a copy of a project.

Snapr is early, open source, and built in the open. Make a copy of a folder you care about, take a few snapshots, and tell us where it falls short.

Get started View on GitHub Report an issue