📦 Snap (The Rust Edition)

A truly native, blazing-fast, and portable snapshot tool for Windows & Linux developers. Create efficient, versioned backups of your project folders with full cross-platform compatibility.

snap is a command-line utility that provides a simple way to capture point-in-time states of your projects. It uses the power and reliability of Git for its core operations but provides a simplified, focused workflow. It's perfect for quick, local backups before a major refactor, for archiving project milestones, or for any situation where you need a reliable "undo" button for your entire directory.

From Node.js to Native: The Quest for Speed

This project began its life as a Node.js application, packaged into an .exe for convenience. While functional, it had a noticeable startup delay inherent to the Node.js runtime. For a tool designed to be a quick, seamless part of a developer's workflow, this was a critical friction point.

The desire for instantaneous, native-level performance led to a complete rewrite in Rust. By compiling directly to a native binary, snap now launches as fast as git itself, eliminating all runtime overhead. This new version retains 100% of the original's features while providing the speed and responsiveness a command-line power tool deserves.

✨ Key Features

🚀 Truly Native Performance: Rewritten in Rust for instantaneous startup and execution. Feels as fast and responsive as git itself.
** Fully Portable**: The entire snapshot history, including all metadata, is stored inside the project's .git directory. Paths are always stored with forward slashes (/) internally, making your metadata 100% portable between Windows and Linux/WSL2 setups!
** dependable Git Core**: Leverages the rock-solid foundation of git for all file storage and versioning. Snapshots are lightweight, annotated Git tags.
⚡️ Efficient Storage: Benefits from Git's mature Content-Addressable Storage model. Identical files across hundreds of snapshots consume the space of just one file.
🎯 Smart Restores: snap restore intelligently checks for uncommitted local changes and prompts you to prevent accidental data loss. It also restores your project files and synchronizes metadata attributes and empty directories.
🐧 Multi-Platform Support: Fully supports Windows, Linux, and WSL2. It correctly preserves Windows Hidden status when on Windows, and uses POSIX-aware permissions on Unix, managing empty directories seamlessly across both.
✍️ Rich Metadata: Snapshots are tagged with a simple label and a more detailed description, which are stored directly in Git's annotated tags.
💻 User-Friendly CLI: Features an interactive menu, human-readable timestamps, a compact list view, and an (active) marker to show you exactly which version your project is on.
🚫 Zero Dependencies: The compiled snap is a standalone binary. No need for Node.js, Rust, or any other runtime on the user's machine.

⚙️ How It Works

snap manages your project as a standard Git repository but uses a simple, robust interaction model. It is now fully self-contained.

The Project Repository (.git) When you run snap init, your project folder becomes a standard Git repository. snap then acts as a user-friendly wrapper around git.exe.
The Internal Metadata Store Because Git doesn't natively track the "Hidden" attribute on Windows or empty directories, snap captures this information. Instead of using an external folder, it now does the following:
- It bundles the metadata (lists of hidden paths and empty directories) into a JSON string.
- It stores this JSON string as a native Git "blob" object inside your project's .git/objects directory using the git hash-object command.
- It then embeds a reference to this blob's hash directly into the annotated Git tag that represents the snapshot.

Visualized Structure:

// Your project folder contains the Git repository:
D:/Projects/MyUnityGame/
└── .git/
    └── objects/
        ├── ...
        ├── 8f/729c75...  <-- A Git Blob containing your metadata JSON
        └── ...

// The Git tag for your snapshot links everything together:
- Tag Name: "v1.0"
- Points to Commit: f4e5d6c...
- Tag Message:
  "Initial release.

   Snap-Metadata-Ref: 8f729c75..."

This elegant design keeps your project folder clean, standard, and 100% portable.

🔧 Prerequisites

Windows: Windows 10 or later
Linux/WSL2: Any modern distribution (Ubuntu, Debian, etc.)
Git must be installed and accessible in your system's PATH (git on Linux, git.exe on Windows). snap relies on it for all core operations.

📥 Installation

You can either download a pre-compiled binary or build it from the source yourself.

Download the Release
- Go to the Releases page of this repository.
- Download the latest snap.exe file.
Place it in your PATH
- Move snap.exe to a permanent location on your system (e.g., D:\Tools\).
- Add this directory (D:\Tools) to your Windows PATH environment variable. This allows you to run the snap command from any terminal.
Verify Open a new terminal window (so it loads the new PATH). Navigate to a project you want to back up and run snap init. It should initialize the repository instantly.

🚀 Usage

All commands are run from within your project's directory.

1. `snap init`

Initializes the current folder as a snap repository. Must be run once per project. This command is now non-interactive and much simpler.

D:\Projects\my-app>snap init
[snap] Initialized empty snap repository in D:\Projects\my-app

2. `snap new <label> [description...]`

Creates a snapshot of the current project state.

D:\Projects\my-app>snap new v1.0 "Initial release"

[snap] Step 1/4: Scanning for metadata (hidden files, empty dirs)...
[snap] Step 2/4: Staging all files...
[snap] Step 3/4: Creating the commit...
[snap] Step 4/4: Creating the annotated snapshot tag...

[snap] New snapshot created: [a1b2c3d] v1.0

3. `snap list` [limit]

Lists all available snapshots in a compact view, showing the active one.

D:\Projects\my-app>snap list 2

[snap] Snapshots for "my-app":

  Label           Description                   Timestamp
  --------------  ----------------------------  ----------------
  v1.1            Second public release         2025-06-16 09:15   (active)
  v1.0-hotfix     A quick fix for the release   2025-06-15 18:00
  ... and 1 more. Use 'snap list all' to see all snapshots.

If [limit] is omitted, it uses the default value from your configuration (changeable via snap options). Use snap list all to view all snapshots regardless of the configured limit.

4. `snap diff <snapshot-A> <snapshot-B>`

Compares two snapshots and shows a list of changes.

D:\Projects\my-app>snap diff v1.0 v1.1

[snap] Comparing snapshots a1b2c3d ("v1.0") ➜ f4e5d6c ("v1.1"):

  + src/auth/new-logic.js
  - config/old-settings.json
  ~ src/app.js
  ! .env (visibility changed)
  + assets/sounds/ (empty directory)

[snap] Summary: 1 added, 1 deleted, 1 modified, 1 visibility change, 1 empty dir added

5. `snap restore [id_or_label]`

Restores the project to a previous state. If run without arguments, it displays an interactive menu.

D:\Projects\my-app>snap restore v1.0

[snap] Restoring project files for snapshot "v1.0"...
[snap] Synchronizing metadata...
[snap] Restore complete. Your project is now at the state of this snapshot.

6. `snap delete [id_or_label]`

Permanently deletes a snapshot. The associated metadata blob is automatically cleaned up by Git's garbage collection later.

D:\Projects\my-app>snap delete v1.1-hotfix

[snap] You are about to delete snapshot:
  Label: v1.1-hotfix
? [snap] WARNING: This will permanently delete the snapshot tag. Continue? [y/N] y
[snap] Deleting tag "v1.1-hotfix"...
[snap] Snapshot "v1.1-hotfix" deleted successfully.

7. `snap edit [id_or_label]`

Edits the label and description of an existing snapshot.

D:\Projects\my-app>snap edit v1.0
? Select snapshot to edit: › v1.0
[snap] Editing snapshot "v1.0":
? Enter new label (tag name): v1.0-final
? Enter new description: Final version for initial release
...
[snap] Snapshot successfully updated to "v1.0-final".

8. `snap update`

Amends the active snapshot with the current state of the project.

D:\Projects\my-app>snap update

[snap] This command will replace the active snapshot...
  Target Snapshot:
    Label:       v1.1
? [snap] This will amend the commit for snapshot "v1.1". This action is hard to undo. [y/N] y
...
[snap] Update complete. Snapshot "v1.1" now points to new commit [b8c9d0e].

9. `snap options`

Allows you to configure global UI settings. These are stored in a .snapconfig file next to the executable.

D:\Projects\my-app>snap options
? Select option to change:
> showIds            - Controls if IDs are shown in lists (current: false)
  confirm_command    - Asks for y/N on destructive actions (current: true)
  orderBy            - Controls the sort order for 'snap list' (current: Timestamp)
  editUpdatesTimestamp - Controls if editing a snapshot updates its timestamp (current: false)
  listLimit          - Sets how many snapshots to show with 'snap list' (current: all)

🏗️ Building from Source

If you want to modify the tool or build it yourself, you'll need the Rust toolchain.

Install Rust: If you don't have it, get it from rustup.rs.

Clone the Repository:

git clone https://github.com/your-username/snap.git
cd snap

Build the Release Executable:
```
cargo build --release
```
Find the Executable: The final snap.exe will be in the target/release/ directory. You can then copy it to a location in your PATH.

🛠️ Troubleshooting

Error: Git is not installed or not in your system PATH.: snap requires git.exe to function. Install Git for Windows and ensure its bin and cmd directories are in your system's PATH.
'snap' is not recognized...: This means the directory containing snap.exe was not correctly added to your PATH, or you haven't opened a new terminal window since adding it.
Error: Not a snap repository...: You are trying to run a command (like list or new) inside a directory that has not been initialized. Run snap init first.

🤝 Contributing

Contributions are welcome!

Fork the repository.
Create your feature branch (git checkout -b feature/my-new-feature).
Make your changes to the .rs files within the src/ directory.
Test your changes by running cargo run -- <command> (e.g., cargo run -- list).
Rebuild the release executable by running cargo build --release.
Test the new snap.exe file thoroughly.
Commit your changes (git commit -am 'Add some feature').
Push to the branch (git push origin feature/my-new-feature).
Open a Pull Request.

📜 License

This project is licensed under the MIT License.

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.cargo		.cargo
doc		doc
src		src
wix		wix
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
Makefile.toml		Makefile.toml
Packager.toml		Packager.toml
README.md		README.md
README_INSTALLER.md		README_INSTALLER.md
build-installers.ps1		build-installers.ps1
snap-setup.exe		snap-setup.exe
snap.nsi		snap.nsi

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

📦 Snap (The Rust Edition)

From Node.js to Native: The Quest for Speed

📋 Table of Contents

✨ Key Features

⚙️ How It Works

🔧 Prerequisites

📥 Installation

🚀 Usage

1. `snap init`

2. `snap new <label> [description...]`

3. `snap list` [limit]

4. `snap diff <snapshot-A> <snapshot-B>`

5. `snap restore [id_or_label]`

6. `snap delete [id_or_label]`

7. `snap edit [id_or_label]`

8. `snap update`

9. `snap options`

🏗️ Building from Source

🛠️ Troubleshooting

🤝 Contributing

📜 License

About

Uh oh!

Releases 1

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

📦 Snap (The Rust Edition)

From Node.js to Native: The Quest for Speed

📋 Table of Contents

✨ Key Features

⚙️ How It Works

🔧 Prerequisites

📥 Installation

🚀 Usage

1. snap init

2. snap new <label> [description...]

3. snap list [limit]

4. snap diff <snapshot-A> <snapshot-B>

5. snap restore [id_or_label]

6. snap delete [id_or_label]

7. snap edit [id_or_label]

8. snap update

9. snap options

🏗️ Building from Source

🛠️ Troubleshooting

🤝 Contributing

📜 License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. `snap init`

2. `snap new <label> [description...]`

3. `snap list` [limit]

4. `snap diff <snapshot-A> <snapshot-B>`

5. `snap restore [id_or_label]`

6. `snap delete [id_or_label]`

7. `snap edit [id_or_label]`

8. `snap update`

9. `snap options`

Packages