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.
These are complementary tools, not replacements for each other. Both have their place in a Git workflow.
Quick comparison
| 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 |
When to use git stash
# 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
- Pull remote changes while preserving local work
- Merge your changes on top of updated code
Stash applies your changes as a patch - this is specifically useful when you need to incorporate others’ changes alongside yours.
When to use git-snapshot
# 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
- Switch branches while preserving exact staging state (staged hunks stay staged)
- Create a safety checkpoint before risky changes
- Keep working while having a restore point
- Maintain named checkpoints across sessions
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”
How they handle concurrent changes
This is a critical difference to understand:
Stash stores diffs (patches)
# You edit file-a lines 1-10, stage them
git stash
# Colleague's changes to lines 30-40 come in via pull
git pull
git stash pop
# Result: BOTH changes are kept (yours merged on top)
Snapshot stores full file contents
# You edit file-a lines 1-10, stage them
git-snapshot checkpoint
# Discard, pull colleague's changes to lines 30-40
git checkout -- . && git pull
git-snapshot restore checkpoint
# Result: File restored to YOUR exact state - colleague's changes are gone
Restoring a snapshot replaces files with their exact saved state. Any changes made since the snapshot (including pulled changes from colleagues) will be overwritten.
- Stash applies your changes relative to current state - good for temporary shelving while collaborating
- Snapshot restores files to an exact checkpoint - good for “undo everything since this point”
Staging preservation
One of the most important differences is how they handle the staging area.
git stash
# Carefully stage specific hunks
git add -p src/app.js # stage only lines 10-20
# Stash it
git stash
# Pop it back
git stash pop
# Result: Everything is unstaged - your careful staging is lost
git-snapshot
# Carefully stage specific hunks
git add -p src/app.js # stage only lines 10-20
# Snapshot it
git-snapshot feature-wip
# Switch branches, do other work...
# Restore it
git-snapshot restore feature-wip
# Result: Lines 10-20 are staged, other changes unstaged - exactly as before
Snapshots preserve three separate states: staged files, unstaged files, and untracked files. Each is restored to its original category.
Working directory behavior
git stash clears your workspace
# Before stash
echo "changes" >> app.js
git status # Modified: app.js
git stash
git status # nothing to commit, working tree clean
# Your working directory is now clean
git-snapshot keeps you working
# Before snapshot
echo "changes" >> app.js
git status # Modified: app.js
git-snapshot checkpoint
git status # Modified: app.js
# Your working directory is unchanged
Storage location
git stash
- Stored inside
.git/refs/stash
- Tied to the repository
- Deleted if you delete the repository
git-snapshot
- Stored in
~/.local/share/git-snapshots/
- Lives outside the repository
- Survives even if you delete the repository
- Can be backed up independently
Bottom line
Need to pull remote changes? Use stash.
For everything else (branch switching, checkpoints, preserving staged hunks, safety nets before experiments) use snapshot.
They complement each other:
# Typical workflow combining both
# Create safety checkpoint before risky refactor
git-snapshot before-refactor
# Work on refactor...
# Need to pull team's changes
git stash
git pull
git stash pop
# Continue working...
# If things go wrong, go back to checkpoint
git-snapshot restore before-refactor