Introduction to git-snapshot

A checkpoint tool for your Git working directory. Save your current state, keep working, restore if things go wrong.

Introduction to git-snapshot

A checkpoint tool for your Git working directory. Save your current state, keep working, restore if things go wrong.

What is git-snapshot?

git-snapshot is a lightweight CLI tool that creates restore points for your Git working directory without affecting your actual workflow. Unlike git commits, snapshots are disposable checkpoints that preserve your exact working state—including staged hunks, unstaged changes, and untracked files.

# You're working on a feature, things are looking good
git-snapshot working-nicely

# Keep experimenting...
# Try a risky refactor...
# Oh no, it's broken

# Get back to your checkpoint
git-snapshot restore working-nicely

# Your code is back exactly as it was - staged files still staged

Why use git-snapshot?

Preserve staging state

Keep your carefully curated staged hunks intact. Staged files restore as staged, unstaged as unstaged.

Non-destructive checkpoints

Creating a snapshot doesn’t touch your working directory. Keep coding while having a safety net.

Named restore points

Use descriptive names like before-refactor instead of cryptic stash@{0} references.

External storage

Snapshots are stored in ~/.local/share/git-snapshots/, separate from your repository.

When to use git-snapshot vs git stash

These are complementary tools, not replacements for each other.

Feature	git stash	git-snapshot
Purpose	Shelve changes temporarily	Create a restore point
Working directory	Cleared (changes removed)	Unchanged (keep working)
Preserves staging	No - everything becomes unstaged	Yes - staged stays staged
Naming	stash@{0}, stash@{1}	my-feature.a1b2c3d4
Storage	Inside repo (.git/)	External (~/.local/share/)
Best for	Pulling remote changes	Everything else

Use git stash when:

# You have local changes but need to pull remote updates
git stash
git pull
git stash pop
# Your changes are merged with the pulled changes

Stash applies your changes as a patch—specifically useful when you need to incorporate others’ changes alongside yours.

Use git-snapshot when:

# Switching branches for a quick fix
git-snapshot wip
git checkout other-branch
# ... fix something ...
git checkout -
git-snapshot restore wip

# Or: checkpoint before risky refactor
git-snapshot before-refactor
# ... experiment freely ...
git-snapshot restore before-refactor  # if things go wrong

The key difference: Stash says “Hold this while I pull, then merge it back.” Snapshot says “Remember this exact state in case I need to come back.”

Important: Stash stores diffs (patches) and merges changes. Snapshot stores full file contents and restores to an exact checkpoint. When you restore a snapshot after pulling colleague’s changes, those changes will be overwritten.

What gets saved

Every snapshot captures three types of changes:

• Staged files - Full contents of files/hunks you’ve git added
• Unstaged files - Full contents of modifications to tracked files not yet staged
• Untracked files - New files not yet added to git (respects .gitignore)

Each is stored separately and restored to its original state.

Key features

• Always works - Stores full file contents, not patches. Restores work even after commits.
• Repo-aware - Snapshots are tied to their repository. Cannot accidentally restore to wrong repo.
• Non-destructive - Creating a snapshot doesn’t touch your working directory.
• Preserves staging - Staged files restore as staged, unstaged as unstaged.
• XDG-compliant - Storage location follows the XDG Base Directory specification.

Get started

Installation

Install git-snapshot with a single curl command

Quick start

Create and restore your first snapshot in under 5 minutes

Why not just commit?

You could use commits for checkpoints, but:

• Sometimes you’re not at a commit-worthy point—code works but isn’t clean/complete
• Commits are permanent history; snapshots are disposable checkpoints
• You might have carefully staged specific hunks for a future commit—committing now loses that curation
• You want to try something without polluting your branch with “WIP” or “temp” commits

Storage format

Snapshots are stored in ~/.local/share/git-snapshots/ (XDG-compliant).

File format: name.hash.snapshot (e.g., my-feature.a1b2c3d4.snapshot)

Each .snapshot file is a tarball containing:

metadata.json       # snapshot info (repo, branch, commit, timestamp, file lists)
staged/             # full contents of staged files
unstaged/           # full contents of unstaged files
untracked/          # full contents of untracked files