⏱️ git-chkpt

Lightweight, local checkpoint tool for Git worktrees, powered by Fossil.

English | 简体中文

Part of the git-odd suite — solving odd Git problems in odd ways.

Quickly save snapshots of your working tree files when you are not ready to commit, stash, or switch branches—and restore them completely whenever needed. Supports both the primary command git chkpt and its full alias git checkpoint.

---

✨ Why git-chkpt?

When working with AI coding assistants, performing large refactorings, or debugging complex issues, you often need to experiment rapidly:

• Powered by Fossil: Uses the rock-solid Fossil SCM engine under the hood for fast deduplication and local snapshots, completely isolated from your Git history.
• More flexible than git stash: Does not require a clean working tree, never conflicts with the index/staging area, and supports clear naming with a full version timeline.
• Cleaner than temporary commits: Leaves no messy "wip" commits in your Git history or commit log.
• Built-in regret safety net: Every restore automatically saves the current workspace state as a pre-restore checkpoint, so you can easily undo any restore operation.

---

🚀 Installation

Via Cargo (Recommended)

cargo install git-chkpt

Ensure ~/.cargo/bin is in your system PATH. Cargo will automatically install both git-chkpt and git-checkpoint.

From Git Repository

cargo install --git https://github.com/git-odd/git-chkpt.git

Pre-built Binaries from GitHub Releases

Download the pre-compiled archive for your OS from the Releases page and place the binaries in your system PATH. The archive includes the storage sidecar for zero-network, fully offline usage.

---

📖 Quick Start

Run directly inside any non-bare Git repository (git chkpt and git checkpoint are identical):

1. Save Workspace State (Save)

# Quick save (default command)
git chkpt

# Save with a descriptive message
git chkpt save "before parser refactor"

# Using the full alias
git checkpoint save "before parser refactor"

2. List Checkpoints (List)

git chkpt ls
# or: git chkpt list

Example output:

ID          CREATED                 SOURCE    MESSAGE
4f18ac932e  2026-08-16 10:21:13.052 manual    before parser refactor

3. View Workspace Diff (Diff)

Compare the current workspace against the latest (or specified) checkpoint:

# Compare latest checkpoint against current workspace
git chkpt diff

# Compare specific checkpoint against current workspace
git chkpt diff 4f18ac93

Example output:

M  src/parser.rs
A  tests/parser_cases.rs
D  notes/old-plan.md

4. Restore Workspace (Restore)

Restore files to the latest or a specified checkpoint:

# Restore to the latest checkpoint
git chkpt restore

# Restore to a specific checkpoint
git chkpt restore 4f18ac93

Safety Note: Before restoring, git-chkpt automatically saves your current workspace as a pre-restore checkpoint. If you accidentally restore or change your mind, simply run git chkpt restore again to return to where you were.

5. Inspect Checkpoint Details (Show)

# Show details of the latest checkpoint
git chkpt show

# Show details of a specific checkpoint
git chkpt show 4f18ac93

6. Delete Checkpoint (Delete)

git chkpt rm 4f18ac93
# or: git chkpt delete 4f18ac93

---

🔄 Typical Workflows

Scenario A: AI-Assisted Refactoring & Safe Experimentation

# 1. Take a snapshot before letting AI refactor code
git chkpt save "before AI refactor"

# 2. Run AI coding tools or write experimental changes
# ... review code, run test suite ...

# 3. Check summary of changes
git chkpt diff

# 4. If unsatisfied, roll back in one step
git chkpt restore

Scenario B: Undoing a Restore

# After restoring an older state, you realize you still need recent edits:
git chkpt ls
# Find the automatic pre-restore checkpoint and restore it:
git chkpt restore <pre-restore-id>

---

🛡️ Boundaries & Characteristics

• Included in Checkpoints:
  • All Git tracked files.
  • Non-ignored untracked files.
• Untouched & Preserved:
  • .git internal state (HEAD, branches, commit history, index / staging area remain intact).
  • .gitignore ignored files and directories (build artifacts, caches, etc. are not saved and never removed on restore).
  • Submodules and nested Git repositories.
• Worktree Isolation:
  • Each Git worktree (including linked worktrees created via git worktree add) has completely isolated checkpoint storage.

📚 Deep Dive & Documentation

For architecture design, storage mechanisms, and formal specifications, please refer to the docs/ directory:

• Technical Notes & Architecture
• Current Implementation Specification
• Product Specification Draft
• Product Spec Coverage Matrix
• Project Status
• Naming Evaluation

---

📄 License

Dual-licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)