Repository navigation
Description
Summary
Add a use case: a bi-temporal sidecar for git repositories. It sits beside git, keyed by commit hash, and adds what git lacks: history by code entity instead of by line, facts learned after a commit, a durable record of branch moves, and help with merge and rebase conflicts.
This is an idea for others to build. There is no official tool. It is also the shared base for several other use cases: #27, #29, #30 and #32 all attach facts to commits.
Why a sidecar, not a new VCS
Git's strength is its network: forges, CI, IDEs and habits. Technically strong alternatives (Pijul, Fossil) stayed niche. Jujutsu is gaining ground because it uses git as its storage backend. The lesson: do not replace git, work beside it. The sidecar needs no new workflow and works with any git host.
Git's real blind spots
Git is not simply "uni-temporal". Its history is a graph of snapshots, and each commit already has an author date and a committer date. The gaps are elsewhere:
- The history of the history is lost. Branches are mutable pointers. After a force-push or rebase, the old state of a branch is gone from the shared repo. The reflog keeps it on one machine only, and it expires.
- Facts learned later have no good home. "This commit introduced bug X" or "this release shipped a vulnerable library" are learned after the commit exists. Git notes can hold them, but are rarely pushed and have no history of their own.
- Git tracks lines, not things. It has no concept of a function. Renames and moves are guessed with heuristics.
- Search is slow and text-only.
log -S,log -L,--grepandblamerescan history on every query, cannot be combined, and lose functions that move between files.
Part 1: conflict help (lead with this, it is the daily pain)
A sidecar cannot change git's merge algorithm. It can plug in through merge drivers, git mergetool, client hooks and server hooks, and supply the knowledge that conflict resolution lacks.
- Early conflict warnings. Index every pushed branch and the entities it touches. Warn when two open branches change the same function.
- Semantic conflicts. Branch A renames a function, branch B adds a call to the old name. No textual conflict, both pass CI alone, the merged build breaks. With a call graph per branch, this is one query.
- Shared resolution memory. Git's
rerereis local and opaque. Store each conflict (base and both sides) and its resolution, keyed by content hash, shared across the team and CI. If a resolution later proves wrong, record that so it is no longer offered, while keeping the history. - Reviewable resolutions. Code written while resolving a conflict hides in the merge commit and is rarely reviewed. Record what each resolution changed beyond picking a side. Later: "which bugs trace back to a conflict resolution?"
- Cross-file moves. Syntax-aware merge drivers such as Mergiraf already handle many per-file cases. The sidecar adds identity across files, so an edit can follow a function that moved.
Out of scope: rebasing long stacks. Jujutsu solves this properly with first-class conflicts. The sidecar can soften it with shared resolutions and can work alongside jj.
Part 2: queryable history index (the foundation)
Build the index once, incrementally per commit. Example questions:
- Every change to this function, across renames and moves between files.
- When did this function's signature last change, and which callers were updated in the same commit? Which were not?
- Which files or functions always change together (hidden coupling)?
- Which commits added an
unsafeblock, a new dependency, or a new public API? - When did this error message or config key first appear, and where is it used now?
- Whose changes still survive in this code (real ownership, not last touch)?
- Which commits touched auth code, were written by an agent, and merged without review? (joins with Use case: AI code provenance #30 and forge data)
Prior art: MergeStat (SQL over git history), Sourcegraph (diff and commit search), CodeQL (deep analysis, one snapshot at a time). None combine entity identity, history and later-learned facts.
Part 3: knowledge layer
- Facts learned later about commits: bugs introduced, reverts and their reasons, advisories, review status. Valid time is the commit; transaction time is when the fact was learned.
- Ref history from server hooks, so force-pushes stop erasing shared history.
Where the code facts come from
Use three layers, and record which tool produced each fact:
- Tree-sitter for all of history. Cheap, works on code that no longer builds, good for structure and entity boundaries.
- SCIP indexers in CI for main-branch commits. SCIP (and LSIF before it) was built to index commits for code navigation. Indexers exist for Rust (
rust-analyzer scip), Java, TypeScript, Python, C and C++, and more. They give compiler-quality references, call graphs and stable symbol IDs. - The developer's live language server for their own branch. It is already running and warm. An editor plugin or git hook pushes facts for the branch on commit or push. This is what makes early conflict warnings possible.
Why not drive a live LSP over history: it works on one checkout, needs a warm-up per commit, needs the project to build (old commits often do not), and results vary by server version and config.
Bi-temporal bonus: re-indexing an old commit with a better tool adds facts with the same valid time and a later transaction time. Queries use the best answer, but the earlier answer stays queryable. An indexer upgrade becomes a correction, not a silent rewrite.
Why Minigraf fits
- Datalog joins across commits, entities, people, branches, PRs and issues.
- Recursive rules for callers, transitive dependencies and reachability.
- Bi-temporal data keeps the code's history separate from what was learned about it later.
- One file per repo, built in CI and shared.
Design issues to state honestly
- Scale. Storing a snapshot per commit explodes. Store only changes: each entity version is valid from one commit until the next change. A large monorepo may still reach billions of facts, which is where the v3 scale target matters.
- History is a graph, valid time is a line. Branches and merges do not map to one timeline. A practical start: use the main branch's first-parent history as the valid-time axis and treat other branches as overlays. This needs real design work.
- Symbol identity. LSP and SCIP IDs are stable only while names stay the same. Renames and moves need matching (for example by body similarity), stored with a confidence score so wrong matches can be corrected.
- Never replay a resolution blindly. Code around it may have changed. Offer it, run tests, never apply silently.
- Server-side indexing. Watching all pushed branches means running next to the git host, not only on laptops.
- Not everything needs two time axes. Early warnings and cross-file merges mostly need the graph. Shared resolutions, later-learned facts and ref history are where bi-temporal data earns its place.
Suggested content
- The pitch: a git sidecar that knows what your code is, what everyone is changing now, and what the team has learned over time
- Git's blind spots, stated fairly
- Conflict help first, then the index, then the knowledge layer
- The three-layer fact sources (tree-sitter, SCIP, live LSP) with provenance
- A fact schema sketch (commit, entity, entity version, calls, branch, touches, conflict, resolution, learned fact)
- Example queries: function history across moves, semantic conflict between two branches, "known at ship time" for a later-learned fact
- The design issues above
- Prior art: Jujutsu, Fossil, Pijul, Unison, Mergiraf, MergeStat, Sourcegraph and SCIP, CodeQL
- Links to Use case: supply chain history (what did we know when we shipped?) #27, Use case: test impact analysis and flaky test history #29, Use case: AI code provenance #30, Use case: large migration tracker #32 as use cases that build on this base
Notes
- Place it in the developer tooling ideas section proposed in Use case: history store for formal verification results #25.
Generated by Claude Code
Activity