What are snapshots

Learn how git-snapshot creates restore points for your working directory, what they save, and how they work internally

A snapshot is a complete checkpoint of your Git working directory state. Unlike Git commits, snapshots are disposable restore points that live outside your repository and preserve your exact staging structure.

What snapshots save

Every snapshot captures three categories of changes:

Staged files

Files or hunks you’ve added with git add. The snapshot stores the staged version from the Git index, not the working tree.

# If you staged specific changes
git add -p src/app.js

# The snapshot saves what's in the index
git-snapshot checkpoint

Implementation detail: Staged content is retrieved using git show ":$file" which reads directly from the index.

Unstaged files

Modified tracked files that haven’t been staged. The snapshot stores the working tree version - your actual file on disk.

# Modified but not staged
echo "new code" >> src/utils.js

# Snapshot saves the working tree version
git-snapshot checkpoint

Implementation detail: Files are copied directly from the working tree using cp "$repo_path/$file".

Untracked files

New files not yet added to Git. The snapshot respects .gitignore - ignored files are never saved.

# New file, not in git yet
echo "export const helper = () => {}" > src/new-helper.js

# Snapshot includes it (unless gitignored)
git-snapshot checkpoint

Implementation detail: Untracked files are discovered using git ls-files --others --exclude-standard.

How snapshots work

When you create a snapshot:

1. Hash generation - An 8-character hash is generated from the current timestamp and random data
2. Metadata collection - Repository info, branch, commit, and file lists are gathered
3. File extraction - Full contents of all changed files are copied to a temporary directory
4. Tarball creation - Everything is compressed into a .snapshot file

Snapshot structure

Each snapshot is a gzipped tarball containing:

my-feature.a1b2c3d4.snapshot/
├── metadata.json          # Repository and snapshot metadata
├── staged/                # Full contents of staged files
│   └── src/
│       └── app.js
├── unstaged/              # Full contents of unstaged files
│   └── src/
│       └── utils.js
└── untracked/             # Full contents of untracked files
    └── src/
        └── new-helper.js

Each category is stored in its own directory with the full file path preserved.

Naming convention

Snapshots use the format: name.hash.snapshot

• With name: my-feature.a1b2c3d4.snapshot
• Without name: a1b2c3d4.snapshot

The hash is always included to ensure uniqueness. You can reference snapshots by name, hash, or the full filename.

Non-destructive creation

Creating a snapshot never changes your working directory:

• Your staged files remain staged
• Your unstaged changes remain unstaged
• Your untracked files stay untracked
• You can continue working immediately

# Create checkpoint
git-snapshot working-nicely
# Output: Snapshot created: working-nicely.a1b2c3d4

# Your working directory is unchanged - keep coding
echo "more changes" >> src/app.js

If there are no changes to save (no staged, unstaged, or untracked files), the snapshot command exits with “No changes to save”.

Full file storage

Snapshots store complete file contents, not diffs or patches. This design choice means:

• Restores always work, even after you’ve made commits
• No merge conflicts during restore
• Files are restored to their exact state
• Snapshots are independent of repository history

git-snapshot checkpoint
# Make commits
git add .
git commit -m "refactor"
git commit -m "more changes"

# Still works - restores exact file contents
git-snapshot restore checkpoint

Because snapshots store full file contents, restoring overwrites the current state completely. If you’ve pulled changes from colleagues, those changes will be lost on restore.

Repository awareness

Snapshots are tied to their source repository. The matching is done by:

1. Remote URL (if the repo has a remote)
2. Repository path (fallback if no remote)

This prevents you from accidentally restoring a snapshot to the wrong repository:

cd ~/project-a
git-snapshot my-feature

cd ~/project-b
git-snapshot restore my-feature
# Error: Snapshot 'my-feature' not found
# (filtered because it belongs to project-a)