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.
Follow these best practices to get the most value from git-snapshot while keeping your workflow clean and organized.
Naming snapshots
Good snapshot names make it easy to find and restore the right checkpoint later.
Use descriptive, context-rich names
Good names:
git-snapshot before-auth-refactor
git-snapshot working-feature-complete
git-snapshot pre-dependency-upgrade
git-snapshot clean-test-passing
git-snapshot temp
git-snapshot backup
git-snapshot asdf
git-snapshot test1
Snapshot names become part of the filename (e.g., before-refactor.a1b2c3d4.snapshot). Use names that will be meaningful days or weeks later.
Include context about why you’re snapshotting
The name should answer: “What state does this represent?”
# Captures intent
git-snapshot ready-for-review
# Captures state
git-snapshot all-tests-passing
# Captures timing
git-snapshot before-risky-change
# Captures experiment
git-snapshot try-new-approach
Use consistent naming patterns
Develop naming conventions for common scenarios:
# For experiments
git-snapshot try-<what>
git-snapshot experiment-<approach>
# For checkpoints
git-snapshot before-<action>
git-snapshot pre-<change>
# For work-in-progress
git-snapshot wip-<feature>
git-snapshot working-<state>
# For clean states
git-snapshot clean-<condition>
git-snapshot stable-<milestone>
Name snapshots by hash when appropriate
Sometimes a quick checkpoint doesn’t need a name:
# Create anonymous snapshot (hash only)
git-snapshot
# Output: Snapshot created: a1b2c3d4.snapshot
# Restore with: git-snapshot restore a1b2c3d4
- Very short-term checkpoints (next few minutes)
- Quick save before testing something
- Temporary safety net you’ll delete soon
Use named snapshots for:
- Anything you might need later in the session
- States you want to return to multiple times
- Checkpoints you might need tomorrow or next week
When to create snapshots
Before risky operations
Always snapshot before operations that might break your code:
# Before major refactoring
git-snapshot before-refactor
# Before dependency upgrades
git-snapshot before-npm-upgrade
npm upgrade
# Before complex merges
git-snapshot before-merge
git merge feature-branch
# Before applying patches
git-snapshot before-patch
git apply risky-changes.patch
When switching contexts
Snapshot before switching branches or starting different work:
# Preserves exact state including staging
git-snapshot wip-feature-x
git checkout hotfix-branch
At working checkpoints
Create snapshots when code works, even if not commit-ready:
# Tests passing but code needs cleanup
git-snapshot tests-passing-messy
# Feature works but incomplete
git-snapshot feature-working-partial
# Before attempting optimization
git-snapshot working-but-slow
Don’t wait for “commit-worthy” code. Snapshot whenever you have a state worth preserving, even if temporary.
Before experimenting
Snapshot before trying new approaches:
# Current approach works
git-snapshot current-approach
# Try different implementation
# ... make changes ...
# Didn't work? Restore easily
git-snapshot restore current-approach
When you have carefully staged changes
Snapshot to preserve exact staging configurations:
# After carefully staging specific hunks
git add -p src/app.js
git add -p src/utils.js
git-snapshot staged-for-atomic-commit
# Now safe to switch branches or make other changes
When NOT to create snapshots
Don’t snapshot instead of committing
If your code is commit-ready, commit it:
# Bad: Using snapshot for finished work
git-snapshot completed-feature # Don't do this
# Good: Commit finished work
git commit -m "Add user authentication feature"
Don’t snapshot clean working directories
If you have no changes, there’s nothing to save:
# git-snapshot will tell you:
No changes to save
Don’t snapshot before pulling
Use git stash instead - it’s designed for this:
# Bad: Using snapshot before pull
git-snapshot before-pull
git pull
git-snapshot restore before-pull
# Colleague's changes might be overwritten!
# Good: Use stash before pull
git stash
git pull
git stash pop
# Your changes are merged on top
Managing snapshot storage
Check snapshots regularly
List snapshots to see what you have:
# Snapshots for current repo
git-snapshot list
# All snapshots across all repos
git-snapshot list --all
Delete snapshots you no longer need
Clean up when experiments are done or features are committed:
# Delete specific snapshots
git-snapshot delete try-approach-a
git-snapshot delete experiment-1 experiment-2
# After committing, delete related snapshots
git commit -m "Implement feature"
git-snapshot delete wip-feature before-refactor
Prune old snapshots periodically
When a feature branch is complete and merged:
# Merged feature to main, no longer need snapshots
git-snapshot prune
# Deletes ALL snapshots for current repo
Set a reminder to review and clean snapshots monthly, especially for active projects.
Understand storage location
Snapshots are stored in ~/.local/share/git-snapshots/ (XDG-compliant):
# View snapshot files directly
ls -lh ~/.local/share/git-snapshots/
# Each snapshot is a compressed tarball
# Example: before-refactor.a1b2c3d4.snapshot
Storage characteristics
Snapshots store full file contents, not diffs:
- Advantage: Always works, even after commits
- Consideration: Larger files use more space
- Management: Delete old snapshots regularly
# Check snapshot storage size
du -sh ~/.local/share/git-snapshots/
Workflow integration
Make it part of your routine
Integrate snapshots into common workflows:
# Start of day: restore yesterday's work
git-snapshot restore friday-eod
# Before code review: snapshot your changes
git-snapshot before-review
# End of day: snapshot current state
git-snapshot friday-eod
Combine with git commands
Snapshots work alongside standard git operations:
# Snapshot, then commit what's ready
git-snapshot checkpoint
git add src/completed-feature.js
git commit -m "Add completed feature"
# Snapshot, experiment, restore if needed
git-snapshot working
# ... experiment ...
git-snapshot restore working
Use with pre-commit hooks
Snapshot before automated formatting changes:
# Before running formatter
git-snapshot pre-format
npm run format
# If formatting breaks something
git-snapshot restore pre-format
Renaming snapshots
Update snapshot names when context changes:
# Created with temporary name
git-snapshot temp
# Later decide it's important
git-snapshot rename temp stable-v1-working
# Output: Renamed: temp.a1b2c3d4.snapshot -> stable-v1-working.a1b2c3d4.snapshot
Troubleshooting tips
Snapshot from wrong repo
git-snapshot prevents restoring to wrong repositories:
# In project-a
git-snapshot my-feature
# In project-b
git-snapshot restore my-feature
# Error: Snapshot 'my-feature' belongs to a different repository
Multiple snapshots with same name
Use hash to specify exact snapshot:
# Created snapshots in different sessions
git-snapshot wip # Creates wip.a1b2c3d4
# ... later ...
git-snapshot wip # Creates wip.e5f6g7h8
# Restore specific one by hash
git-snapshot restore a1b2c3d4
Uncommitted changes warning
Restore warns before overwriting:
git-snapshot restore checkpoint
# Warning: You have uncommitted changes that will be overwritten!
# Are you sure you want to continue? [y/N]
If you’re unsure, create a new snapshot before restoring: git-snapshot before-restore && git-snapshot restore checkpoint
Summary checklist
Naming:
- ✓ Use descriptive, context-rich names
- ✓ Include why you’re snapshotting
- ✓ Use consistent patterns
- ✓ Hash-only for very short-term use
Creating:
- ✓ Before risky operations
- ✓ When switching contexts
- ✓ At working checkpoints
- ✓ Before experiments
- ✗ Don’t snapshot instead of committing
- ✗ Don’t snapshot before pulls (use stash)
Managing:
- ✓ List snapshots regularly
- ✓ Delete after experiments/commits
- ✓ Prune when branches complete
- ✓ Check storage size periodically