Checkpoints
Checkpoints are Semantica's snapshot system. Every checkpoint is a point-in-time record of your repository that you can inspect, compare, and restore from, without touching Git history.
How checkpoints are created
Automatic checkpoints are created on every commit via the pre-commit and post-commit hooks. This happens transparently and never slows down your commit.
Manual checkpoints can be created at any time:
semantica checkpoint -m "before big refactor"
semantica checkpoint -m "before merging upstream"
Safety checkpoints are created automatically before any rewind operation, giving you a way to undo the restore if needed.
Listing checkpoints
semantica list # Last 20 checkpoints
semantica list -n 50 # Last 50
semantica list --json # JSON output
Output shows the checkpoint ID, timestamp, kind (auto/manual/safety), associated commit hash, and commit subject:
chk_def456 2026-03-23 14:22 auto abc1234 add authentication module
chk_abc123 2026-03-23 11:05 baseline (no commit) (baseline)
Inspecting a checkpoint
semantica show chk_def456
semantica show chk_def456 --json
semantica show def4 --jsonl # metadata + one file per line
The show command displays the full file manifest: every file in the snapshot, its blob hash, and its size. This tells you exactly what the repository contained at that checkpoint.
Checkpoint IDs are prefix-matchable, semantica show def4 works as long as the prefix is unambiguous.
Rewinding to a checkpoint
Rewind restores your working tree to the state captured in a checkpoint. It does not rewrite Git history or create any commits.
semantica rewind chk_abc123
Before restoring, Semantica creates a safety checkpoint so you can get back to where you were:
Creating safety checkpoint... chk_safety789
Restoring 12 files to chk_abc123...
Done. Rewound to chk_abc123. Safety checkpoint: chk_safety789
To undo a rewind, rewind to the safety checkpoint:
semantica rewind chk_safety789
Exact rewind
By default, rewind only restores files that are tracked in the checkpoint. Files that exist in your working tree but were not in the checkpoint are left untouched.
Use --exact to also delete those extra files:
semantica rewind chk_abc123 --exact
This restores the working tree to exactly what the checkpoint recorded, no more, no less.
Skipping the safety checkpoint
If you're certain you don't need a safety checkpoint (for example, in a scripted workflow), you can skip it:
semantica rewind chk_abc123 --no-safety
Checkpoint kinds
| Kind | When created |
|---|---|
baseline | When semantica enable runs for the first time |
auto | After every commit (by the post-commit hook) |
manual | When you run semantica checkpoint explicitly |
safety | Automatically before every rewind |
What checkpoints store
Each checkpoint stores a manifest: a list of every tracked file in the repository at that moment, along with the SHA-256 hash of each file's content. The file contents themselves are stored in .semantica/objects/ as a content-addressed blob store (compressed with zstd).
Because the store is content-addressed, identical files across multiple checkpoints share a single blob. The storage footprint grows proportionally to the number of unique file versions, not the number of checkpoints.
Checkpoint trailers in commits
Every commit that creates a checkpoint includes a Semantica-Checkpoint trailer in the commit message:
add authentication module
Semantica-Checkpoint: chk_def456
This trailer is always added and cannot be disabled (though the attribution and diagnostics trailers can be). It creates a durable link between any commit and its corresponding Semantica data, even if the .semantica/ directory is later removed.