Frequently asked questions

Common questions about git-snapshot functionality and usage

How is this different from git stash?

git-snapshot and git stash serve similar purposes but with key differences:

Persistence:

• Snapshots are stored as files in ~/.local/share/git-snapshots and persist indefinitely
• Stashes are stored in the git repository and can be lost if the repository is deleted

Naming:

• Snapshots support custom names for easy identification: git-snapshot my-feature
• Stashes require remembering stash indices or using less intuitive naming

Organization:

• Snapshots automatically track which repository they belong to
• Stashes are repository-specific but don’t prevent accidental application

Selective restore:

• Snapshots support restoring only staged, unstaged, or untracked files separately
• Stashes restore everything at once

Use git-snapshot when: you want long-term storage with meaningful names
Use git stash when: you need quick, temporary storage during workflow interruptions

Can I use snapshots across different repositories?

No, snapshots are repository-specific and cannot be restored across different repositories.

Why this restriction exists:

• Snapshots contain file paths relative to the repository root
• Different repositories have different structures and histories
• Preventing cross-repository restores avoids conflicts and data corruption

How repository matching works:

Snapshots match repositories using:

1. Remote URL (primary): If both the snapshot and current repository have a remote origin, they must match
2. Repository path (fallback): The absolute path to the repository root

If you try to restore a snapshot from a different repository, you’ll see:

Error: Snapshot 'name' belongs to a different repository

Workaround:

To view snapshots from all repositories:

git-snapshot list --all

What happens to snapshots when I delete a repository?

Snapshots persist independently of their source repository.

After deleting a repository:

• Snapshot files remain in ~/.local/share/git-snapshots
• They continue to occupy disk space
• You cannot restore them to a new repository (even with the same name)

Cleanup:

Snapshots are not automatically deleted. To remove orphaned snapshots:

1. View all snapshots:

   git-snapshot list --all
   

2. Delete specific snapshots:

   git-snapshot delete snapshot-name
   

3. Or manually clean the snapshots directory:

   rm ~/.local/share/git-snapshots/*.snapshot
   

Best practice:

Before deleting a repository, prune its snapshots:

cd /path/to/repo
git-snapshot prune

Are snapshots affected by commits?

No, snapshots are completely independent of git commits and branch changes.

What snapshots capture:

• Staged changes (files in the index)
• Unstaged changes (modified tracked files)
• Untracked files (new files not yet tracked by git)
• Metadata: branch name, commit hash, timestamp

What happens after you commit:

Creating a commit does not affect existing snapshots:

• Snapshots store the full file contents at the time of creation
• They remain unchanged regardless of future commits
• You can still restore the snapshot to see the exact state from when it was created

Example workflow:

# Make changes
git-snapshot create before-refactor

# Continue working and commit
git add .
git commit -m "Refactor code"

# Later, restore the pre-refactor state
git-snapshot restore before-refactor

The snapshot preserves your work exactly as it was, independent of git history.

Can I restore only part of a snapshot?

Yes, git-snapshot supports selective restoration using command-line flags.

Available options:

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

Examples:

# Restore only staged files
git-snapshot restore my-feature --staged-only

# Restore only untracked files
git-snapshot restore my-feature --untracked-only

# Restore only unstaged changes
git-snapshot restore my-feature --unstaged-only

Default behavior:

Without flags, all three categories are restored together.

Use case:

This is useful when you want to:

• Review staged changes without affecting your working directory
• Recover untracked files without overwriting current work
• Restore unstaged modifications while keeping your index clean

What happens to my current changes when I restore a snapshot?

Restoring a snapshot will overwrite your current changes.

Warning behavior:

If you have uncommitted changes and restore a snapshot (with default or --staged-only/--unstaged-only flags), git-snapshot will:

1. Detect uncommitted changes
2. Display a warning: Warning: You have uncommitted changes that will be overwritten!
3. Ask for confirmation: Are you sure you want to continue? [y/N]

What gets overwritten:

• --staged-only or --unstaged-only: Current staged/unstaged changes are discarded
• Default (no flags): All uncommitted changes are discarded
• --untracked-only: Only adds untracked files, doesn’t affect existing changes

Best practice:

Create a snapshot of your current state before restoring:

git-snapshot create current-state
git-snapshot restore previous-snapshot

This lets you switch between different states safely.

How do I find a snapshot if I forgot its name?

Use the list command to see all snapshots for your repository.

Basic listing:

git-snapshot list

This shows:

• Snapshot name and hash
• Branch it was created on
• Creation timestamp

View all snapshots:

git-snapshot list --all

Shows snapshots from all repositories, with repository information included.

Inspect snapshot contents:

git-snapshot show <name-or-hash>

Displays:

• Snapshot metadata (hash, branch, commit, timestamp)
• List of staged files
• List of unstaged files
• List of untracked files

Search flexibility:

You can restore using:

• Full name: git-snapshot restore my-feature
• Hash only: git-snapshot restore a1b2c3d4
• Partial match: If multiple matches exist, you’ll be prompted to choose

Can I rename a snapshot after creating it?

Yes, use the rename command to change a snapshot’s name.

Syntax:

git-snapshot rename <old-name> <new-name>

Example:

git-snapshot rename temp-work final-feature

How it works:

• The hash remains the same
• Only the name portion changes
• The snapshot file is recreated with updated metadata

Limitations:

• Cannot rename to a name that already exists
• If multiple snapshots match the old name, you must specify the hash
• Both old and new names are required

Error handling:

If the new name already exists:

Error: Snapshot 'new-name.hash.snapshot' already exists

Solution: Choose a different name or delete the conflicting snapshot first.

Where are snapshots stored and how much space do they use?

Snapshots are stored as compressed tar archives in your local filesystem.

Storage location:

• Default: ~/.local/share/git-snapshots/
• Custom: $XDG_DATA_HOME/git-snapshots/ (if XDG_DATA_HOME is set)

File format:

• Extension: .snapshot
• Compression: gzip (tar.gz)
• Contents: Full file contents + metadata JSON

Naming convention:

• With name: name.hash.snapshot
• Without name: hash.snapshot
• Hash: 8-character identifier (e.g., a1b2c3d4)

Space usage:

Each snapshot contains:

• Complete copies of all staged files
• Complete copies of all unstaged files
• Complete copies of all untracked files
• Small metadata file (JSON)

Space usage depends on:

• Number and size of changed files
• Compression ratio (text files compress well)

Check snapshot size:

du -sh ~/.local/share/git-snapshots/

Cleanup:

# Delete all snapshots for current repo
git-snapshot prune

# Delete specific snapshots
git-snapshot delete name1 name2