Best practices

Guidelines for naming snapshots, when to create them, and managing snapshot storage effectively

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

Poor names:

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

Use hash-only snapshots for:

• 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"

Snapshots are for checkpoints, commits are for history.

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

See git-snapshot vs git stash for detailed differences.

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