Selective restore

Use selective restore flags to restore only specific parts of a snapshot

git-snapshot stores three types of changes separately: staged files, unstaged files, and untracked files. You can restore only specific types using selective restore flags.

Understanding the restore flags

git-snapshot provides three flags for selective restoration:

• --staged-only - Restore only staged changes
• --unstaged-only - Restore only unstaged changes
• --untracked-only - Restore only untracked files

What gets saved in each category

When you create a snapshot, files are categorized based on their git status:

Staged files - Files or hunks you’ve added with git add

git add src/app.js           # entire file staged
git add -p src/utils.js      # specific hunks staged

Unstaged files - Modified tracked files not yet staged

# src/helper.js has changes but hasn't been added

Untracked files - New files not yet added to git (respects .gitignore)

# src/new-feature.js exists but is not tracked

Use git-snapshot show <name> to see which files are in each category before restoring.

Restoring only staged changes

Use case: You want to restore the staging area without affecting your current working directory changes.

1. View snapshot contents

   git-snapshot show before-refactor
   

   Output:

   Snapshot: before-refactor.a1b2c3d4
   Hash: a1b2c3d4
   Name: before-refactor
   Repo: my-project
   Branch: main
   Commit: e5f6g7h8
   Created: 2026-01-26 14:30:52
   
   Staged files:
     src/app.js
     src/components/Header.js
   
   Unstaged files:
     src/utils.js
   
   Untracked files:
     src/new-helper.js
   
2. Restore only staged files

   git-snapshot restore before-refactor --staged-only
   

   This will:

   • Restore src/app.js and src/components/Header.js to staging
   • Leave current working directory changes untouched
   • Not restore src/utils.js or src/new-helper.js

Example scenario

You’re preparing a commit with carefully selected changes, but accidentally unstage everything:

# You had staged specific files
git add src/app.js src/utils.js

# Create safety snapshot
git-snapshot staged-changes

# Accidentally reset
git reset HEAD
# Oh no! Everything is unstaged

# Restore just the staging area
git-snapshot restore staged-changes --staged-only
# Your staged files are back, current work untouched

Restoring only unstaged changes

Use case: You want to restore working directory modifications without affecting what’s staged.

1. Create snapshot with mixed changes

   # Stage some files for commit
   git add src/feature.js
   
   # Have other unstaged changes
   # (src/helper.js is modified but not staged)
   
   git-snapshot mixed-state
   
2. Make more changes

   # Continue working
   # Modify src/helper.js further
   # Realize you want the previous version
   
3. Restore only unstaged files

   git-snapshot restore mixed-state --unstaged-only
   

   This will:

   • Restore src/helper.js to its unstaged state from snapshot
   • Keep src/feature.js staged with current changes
   • Preserve the staging area completely

Example scenario

You’re working on two separate concerns - one ready to commit (staged), one still experimental (unstaged):

# Bug fix is staged and ready
git add src/auth.js

# Experimental feature is unstaged
# (src/experimental.js has changes)

git-snapshot ready-to-commit

# Try different approach to experimental feature
# ... make changes to src/experimental.js ...
# Doesn't work, want to go back

git-snapshot restore ready-to-commit --unstaged-only
# Bug fix still staged, experimental changes reverted

Restoring only untracked files

Use case: You want to restore new files that were created but not yet tracked by git.

1. Work with new files

   # Create new files
   touch src/new-module.js
   touch src/new-test.js
   
   # Snapshot includes untracked files
   git-snapshot with-new-files
   
2. Delete or modify new files

   # Accidentally delete
   rm src/new-module.js
   
   # Or heavily modify src/new-test.js
   # and want original back
   
3. Restore only untracked files

   git-snapshot restore with-new-files --untracked-only
   

   This will:

   • Restore src/new-module.js and src/new-test.js
   • Not affect any tracked files (staged or unstaged)

Example scenario

You’re creating several new files as part of a feature, snapshot them, then accidentally delete one:

# Create new feature files
touch src/feature-a.js
touch src/feature-b.js
touch src/feature-c.js

git-snapshot new-feature-files

# Stage one of them
git add src/feature-a.js

# Accidentally delete another
rm src/feature-b.js

# Restore only untracked files
git-snapshot restore new-feature-files --untracked-only
# src/feature-b.js is back
# src/feature-a.js remains staged (not affected)

Combining with git commands

Selective restore works well with standard git operations:

# Restore staging, then amend commit
git-snapshot restore checkpoint --staged-only
git commit --amend

# Restore untracked files, then add them
git-snapshot restore checkpoint --untracked-only
git add src/new-files/

# Restore unstaged, then stage selectively
git-snapshot restore checkpoint --unstaged-only
git add -p src/

When to use selective restore

Use --staged-only when:

• You need to recover specific staging configurations
• You want to restore what was ready to commit
• You’re working on current changes but need the previous staging

Use --unstaged-only when:

• You want to revert working directory changes
• You need to recover in-progress modifications
• Your staging area should remain untouched

Use --untracked-only when:

• You need to recover deleted new files
• You want to restore original versions of new files
• Your tracked files (staged/unstaged) should remain unchanged

Use full restore (no flags) when:

• You want to restore everything to the exact snapshot state
• You’re switching between complete working states
• You want a complete “undo” to a specific checkpoint

Run git-snapshot show <name> before restoring to see exactly what files are in each category and make an informed decision about which restore flag to use.