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.

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)

Build docs developers (and LLMs) love

Get started for freeTalk to us