Snapshots and Git
How Git commits and eve snapshots work together.
eve is built beside Git, not above it.
Git remains the source of truth for implementation history. eve adds the product record that Git does not try to model.
Commit versus snapshot
Commit
A code checkpoint.
Best for diffs, merges, authorship, and implementation history.
Snapshot
A completed product change.
Best for product meaning, evidence, relationships, and agent context.A snapshot can correspond to one commit, several commits, or a working state that is later committed. The important boundary is conceptual: snapshots describe completed product work, not every implementation checkpoint.
Git facts eve derives
When a snapshot is committed, eve derives implementation facts from the repository:
- Current branch
- Resolved Git state
- Base commit, when available
- Commit list
- Dirty state
Humans and agents provide the product meaning. eve derives the implementation facts.
Clean working tree by default
eve commit expects the implementation working tree to be clean by default. This keeps the product record aligned with a reviewable Git state.
Use --allow-dirty only when the workflow intentionally records a dirty state and the snapshot explains why.
Why this boundary matters
Keeping the two histories separate makes each one better. Git can stay focused on code. eve can stay focused on the shipped result, verification, and context that would otherwise be scattered across tools.
Relationship fields
Snapshots can point at other snapshots with structured relationships:
correctssupersedesrevertsdependsOnrelated
These fields let product history form a graph instead of a flat log.