Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/mubshrx/git-snapshot/llms.txt

Use this file to discover all available pages before exploring further.

​
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.
Featuregit stashgit-snapshot
PurposeShelve changes temporarilyCreate a restore point
Working directoryCleared (changes removed)Unchanged (keep working)
Preserves stagingNo - everything becomes unstagedYes - staged stays staged
Namingstash@{0}, stash@{1}my-feature.a1b2c3d4
StorageInside repo (.git/)External (~/.local/share/)
Best forPulling remote changesEverything 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

Build docs developers (and LLMs) love

Get started for freeTalk to us