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.

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us