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.

git-snapshot enables safer, more flexible development by creating restore points without cluttering your commit history. Here are the most common workflows you’ll use.

​
Branch switching while preserving work

When you need to quickly switch branches for a bug fix or code review but don’t want to lose your current work-in-progress state:
1

Create a snapshot

Save your current state with a descriptive name:
git-snapshot wip-new-feature
Your working directory remains unchanged - you can keep working if needed.
2

Switch branches

git checkout hotfix-branch
# or: git checkout -b review/pr-123
Make your changes, commit them, and finish your work on the other branch.
3

Return and restore

Switch back to your original branch and restore your exact state:
git checkout feature-branch
git-snapshot restore wip-new-feature
Everything returns exactly as it was - staged files remain staged, unstaged files remain unstaged.
Unlike git stash, git-snapshot preserves your staging area perfectly. If you had specific hunks carefully staged for a commit, they’ll be restored exactly as they were.

​
Creating checkpoints before risky refactoring

Before attempting a significant refactor or architectural change:
1

Create a safety checkpoint

git-snapshot before-refactor
Output:
Snapshot created: before-refactor.a1b2c3d4.snapshot

  Staged files:    3
  Unstaged files:  2
  Untracked files: 1

Restore with:
  git-snapshot restore before-refactor
2

Experiment freely

Attempt your refactor without fear:
# Move files around
# Rename functions
# Restructure modules
# Try different approaches
If things go wrong, you have an exact restore point.
3

Restore if needed

If your refactor doesn’t work out:
git-snapshot restore before-refactor
Your code returns to the exact state before you started - no partial changes, no confusion about what worked.

​
Experimenting safely with new approaches

When you have working code but want to try a different implementation approach:
1

Save the working state

git-snapshot working-nicely
This creates a checkpoint of code that works, even if it’s not commit-ready.
2

Try your experiment

# Rewrite using a different pattern
# Try a new library
# Refactor the architecture
Work freely knowing you can always get back to working code.
3

Commit or restore

If the experiment works:
git add .
git commit -m "Refactored using new approach"
git-snapshot delete working-nicely
If it doesn’t work:
git-snapshot restore working-nicely
Snapshots are disposable checkpoints, not permanent history. Don’t hesitate to create them liberally and delete them when no longer needed.

​
Testing changes across multiple scenarios

When you need to test different variations of a feature:
1

Create snapshots for each variation

# Implement approach A
git-snapshot approach-a

# Modify to approach B
git-snapshot approach-b

# Modify to approach C
git-snapshot approach-c
2

Compare and test each

git-snapshot restore approach-a
# Run tests, check performance

git-snapshot restore approach-b
# Run tests, check performance

git-snapshot restore approach-c
# Run tests, check performance
3

Keep the winner

Once you’ve decided on the best approach:
git-snapshot restore approach-b
git commit -am "Implement feature using approach B"

# Clean up unused snapshots
git-snapshot delete approach-a approach-c

​
Preserving staged hunks during interruptions

When you’ve carefully staged specific changes for a commit but get interrupted: 
# You've staged specific hunks from multiple files
git add -p src/app.js
git add -p src/utils.js

# Create a snapshot to preserve the exact staging
git-snapshot staged-for-commit

# Now you can switch branches or make other changes
git checkout hotfix-branch
# ... fix something ...
git checkout feature-branch

# Restore your carefully curated staged changes
git-snapshot restore staged-for-commit
This workflow is impossible with git stash because stash doesn’t preserve the staging area - everything becomes unstaged when you stash pop.

​
Working across sessions

Unlike stash, snapshots persist across terminal sessions and system reboots: 
# End of day Friday
git-snapshot weekend-pause

# Close laptop, go home, restart computer

# Monday morning
cd your-project
git-snapshot list
# Shows: weekend-pause (a1b2c3d4)

git-snapshot restore weekend-pause
# Exactly where you left off

​
Quick checkpoints during debugging

When hunting for a bug and trying different fixes: 
# Found potential issue in file A
git-snapshot try-fix-a
# ... make changes ...
# ... test ...
# Didn't work

# Try different approach in file B
git-snapshot try-fix-b
# ... make changes ...
# ... test ...
# This worked!

git commit -am "Fix: resolved issue in authentication flow"
git-snapshot delete try-fix-a try-fix-b

​
When to snapshot vs when to commit

Use snapshots when:
  • Code works but isn’t clean/complete enough to commit
  • You want to try something risky
  • You’re switching contexts temporarily
  • You’ve staged specific hunks you want to preserve
  • You need disposable checkpoints while exploring
Use commits when:
  • You’ve completed a logical unit of work
  • The code is ready for code review
  • You want to share changes with teammates
  • You’re creating permanent project history

Build docs developers (and LLMs) love

Get started for freeTalk to us