Skip to content

Use case: bi-temporal sidecar for git (history index, conflict help, later-learned facts) #34

Closed

Description

@adityamukho

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:

  1. 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.
  2. 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.
  3. Git tracks lines, not things. It has no concept of a function. Renames and moves are guessed with heuristics.
  4. Search is slow and text-only. log -S, log -L, --grep and blame rescan 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 rerere is 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 unsafe block, 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

Notes


Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions