Quick start

Create and restore your first snapshot in under 5 minutes

Quick start

This guide will walk you through creating, listing, and restoring snapshots. You’ll learn the essential workflow in under 5 minutes.

Prerequisites

Before starting, make sure you have:

• git-snapshot installed (see Installation)
• A Git repository to work with

Basic workflow

1. Navigate to a Git repository

   cd your-project
   

   git-snapshot only works inside Git repositories. You’ll see an error if you try to use it outside one.

2. Make some changes

   Create or modify files to have something to snapshot:

   # Edit an existing file
   echo "console.log('testing snapshots');" >> src/app.js
   
   # Create a new file
   echo "export const helper = () => {};" > src/helper.js
   
   # Stage some changes
   git add src/app.js
   

   Now you have:

   • Staged: src/app.js
   • Untracked: src/helper.js
3. Create your first snapshot

   Save the current state with a descriptive name:

   git-snapshot before-refactor
   

   Output:

   Snapshot created: before-refactor.a1b2c3d4.snapshot
   
     Staged files:    1
     Unstaged files:  0
     Untracked files: 1
   
   Restore with:
     git-snapshot restore before-refactor
   

   Your working directory is unchanged. The snapshot is saved, but you keep working normally.

4. Continue working

   Make more changes, try a risky refactor, or switch branches:

   # Modify files further
   echo "// Risky refactor" >> src/app.js
   echo "// More changes" >> src/helper.js
   
   # Check status
   git status
   
5. List your snapshots

   See all snapshots for the current repository:

   git-snapshot list
   

   Output:

   Snapshots for your-project:
   
     before-refactor (a1b2c3d4)
       branch: main | created: 2026-03-03 14:30:52
   
6. Restore the snapshot

   If things go wrong, restore your checkpoint:

   git-snapshot restore before-refactor
   

   Output:

   Warning: You have uncommitted changes that will be overwritten!
   
   Are you sure you want to continue? [y/N] y
   
   Restoring snapshot: before-refactor.a1b2c3d4
   
   Discarding current changes...
   Restoring 1 staged file(s)...
   Restoring 1 untracked file(s)...
   
   Snapshot restored successfully!
   

   Your working directory is now exactly as it was when you created the snapshot:

   • src/app.js is staged with the original changes
   • src/helper.js is untracked with the original content

Advanced usage

Create snapshots without names

If you don’t need a descriptive name, create a snapshot with just a hash:

git-snapshot

Output:

Snapshot created: a1b2c3d4.snapshot

Restore with:
  git-snapshot restore a1b2c3d4

View snapshot details

Inspect what’s saved in a snapshot before restoring:

git-snapshot show before-refactor

Output:

Snapshot: before-refactor.a1b2c3d4
Hash: a1b2c3d4
Name: before-refactor
Repo: your-project
Branch: main
Commit: e5f6g7h8
Created: 2026-03-03 14:30:52

Staged files:
  src/app.js

Unstaged files:
  (none)

Untracked files:
  src/helper.js

Selective restore

Restore only specific types of changes:

# Restore only staged changes
git-snapshot restore before-refactor --staged-only

# Restore only unstaged changes
git-snapshot restore before-refactor --unstaged-only

# Restore only untracked files
git-snapshot restore before-refactor --untracked-only

Selective restore is useful when you want to recover specific parts of your work without discarding everything.

Delete snapshots

Remove snapshots you no longer need:

# Delete a specific snapshot
git-snapshot delete before-refactor

# Delete multiple snapshots
git-snapshot delete snapshot1 snapshot2 snapshot3

# Delete all snapshots for current repo
git-snapshot prune

Deletion is permanent. Make sure you don’t need the snapshot before deleting.

Rename snapshots

Give a snapshot a better name:

git-snapshot rename old-name new-name

The hash remains the same, only the name changes:

Renamed: old-name.a1b2c3d4.snapshot -> new-name.a1b2c3d4.snapshot

List all snapshots across repositories

See snapshots from all your projects:

git-snapshot list --all

Output:

All snapshots:

  before-refactor (a1b2c3d4)
    repo: project-one
    branch: main | created: 2026-03-03 14:30:52

  wip (b2c3d4e5)
    repo: project-two
    branch: feature | created: 2026-03-03 15:45:21

Common workflows

Before a risky refactor

# Create checkpoint
git-snapshot before-refactor

# Try your risky changes
vim src/app.js
npm test

# If tests fail, restore
git-snapshot restore before-refactor

Switching branches with uncommitted work

# Save current work with preserved staging
git-snapshot wip

# Switch to another branch
git checkout hotfix-branch

# ... fix the bug ...
git commit -m "Fix critical bug"

# Return to original work
git checkout main
git-snapshot restore wip

# Continue where you left off - staging intact

Experimenting with multiple approaches

# Try approach A
git-snapshot approach-a
# ... make changes ...

# Try approach B instead
git-snapshot restore approach-a
git-snapshot approach-b
# ... make different changes ...

# Compare results by restoring each
git-snapshot restore approach-a  # see approach A
git-snapshot restore approach-b  # see approach B

Quick checkpoints during development

# Working on feature, stage what's ready
git add src/feature.js

# Snapshot the staged work
git-snapshot feature-staged

# Continue with unstaged experiments
vim src/feature.js

# Oops, experiments broke everything
git-snapshot restore feature-staged

# Back to the good state, staged file still staged

Understanding restore behavior

Important: Restoring a snapshot will overwrite your current working directory. Any uncommitted changes will be lost unless you create a snapshot first.

When you restore a snapshot:

1. Staged files are restored to the staging area
2. Unstaged files are restored as working tree modifications
3. Untracked files are restored as untracked
4. Current changes are discarded (you’ll be prompted to confirm)

# Always safe: create a snapshot before restoring
git-snapshot current-state
git-snapshot restore old-state

# If you don't like the old state, go back
git-snapshot restore current-state

Tips and best practices

• Use descriptive names: before-refactor is better than snapshot1
• Create snapshots before risky changes: Better safe than sorry
• Snapshots are cheap: Don’t hesitate to create many of them
• Clean up old snapshots: Use git-snapshot delete or prune to remove snapshots you don’t need
• Snapshots aren’t backups: They’re meant for temporary checkpoints, not long-term storage

Next steps

You now know the essentials of git-snapshot! To learn more:

Introduction

Deep dive into when to use snapshots vs stash

Installation

Alternative installation methods and troubleshooting