Git worktrees support

[mpes]

I could not find anywhere if code-review-graph supports working with worktrees? I.e. separated branches under subfolders within the main projects. Because if multiple agents work on the different codebase the graph should be aware of that and keep separate graphs too.
Many thanks for answers.

[tirth8205]

Worktrees status, honestly:

• What works today: each worktree is treated as its own repo — build inside it and you get a separate .code-review-graph/ graph, which matches your "keep separate graphs" expectation. The registry (register/repos) plus crg-daemon can track multiple worktrees side by side.
• What was broken until now: install silently skipped git hooks in worktrees because .git is a file there, so graphs went stale on commit with no warning. Fixed in PR feat: custom languages, PR-review GitHub Action, honest benchmarks, FAQ, community infra + verified Windows/hygiene fixes #541 (git rev-parse --git-path hooks, with worktree regression tests).
• What doesn't exist yet: branch-aware sharing (one graph that understands multiple worktrees of the same repo and diffs between them). That's a genuinely interesting design — if you'd sketch your ideal workflow (e.g. compare impact across two worktrees?), it would help shape it.

docs/FAQ.md (also #541) now documents the worktree setup.

[lavaxun]

Posting the design sketch this discussion invited, from the shape of one real (large,
monorepo-style) team's worktree usage. Numbers below are measured, and each is dated so it's
clear which are fresh and which are carried forward from an earlier pass.

Our setup, in one paragraph

We run one large monorepo (dozens of services under a single projects/* tree) and put every
in-flight branch — human or AI-agent-driven — in its own git worktree, often several at once.
A worktree is git worktree add ../feat-x -b feat-x: a separate checkout sharing one .git,
branched from the same history as every sibling worktree. We already treat "per-worktree
resource that should really be shared or copy-on-write" as a known problem class — our local
Postgres tooling clones a golden base into a copy-on-write branch DB per worktree specifically
to avoid N full copies of a mostly-identical dataset, at ~0 marginal disk and instant clone
time. code-review-graph (CRG) is the one per-worktree resource we have not been able to
apply that pattern to, because there's no branch-aware primitive to apply it with.

The measured cost

Each worktree builds and keeps its own full graph.db. Measured during our 2026-08-13 CRG
adoption pass and carried forward here as still-representative (the graph's structure hasn't
changed in kind since): one graph measured ~3.3 GB per worktree, essentially all of it
irreducible structure rather than trimmable noise — 1.57M edges plus their six indexes
accounted for ~3.0 GB of that. We also checked whether an ignore-file convention could shrink
it: out of roughly 144,000 nodes in that same graph, exactly 1 matched a generated-file
pattern, because CRG already indexes only git-tracked files. So there is no low-hanging fruit on
our side; the size is the graph doing its job on a large tracked tree, multiplied by however
many worktrees are open.

The registry cost — same shape, and a fresh number

That multiplication is not a corner case for us — it's the common case, and we have measurements
from three points in time.

Steady state, measured 2026-08-30 after our own orphan sweep ran: one developer's machine
holds 11 registry rows, 9 of them live, and the graphs that have actually been built come to
19.1 GB across 6 worktrees — median 3.36 GB, largest 3.51 GB. That is a floor, not a ceiling:
3 of the 9 live rows had not built a graph yet at snapshot time, so a fully warm machine at this
worktree count lands nearer 30 GB. This is the number that matters for this discussion — we
checked, and all 6 of those checkouts report the same git rev-parse --git-common-dir. One
.git, six full graphs, 19.1 GB, indexing overwhelmingly the same tracked tree.

Before that sweep, same day: the registry held 69 rows with only 11 live — 58 orphans
from worktrees deleted without unregistering. An earlier snapshot on 2026-08-13 found the
identical shape at a different scale: 97 entries, 9 live, 19 orphaned graph.db files totalling
22.6 GB with no worktree left at all. We have since built the sweep described below, which is
why the orphan count is now 2 rather than 58 — so the orphan half of this is a problem we have
handled on our side, and we mention it only to show the shape. The steady-state half above is
the part we cannot fix ourselves.
git worktree remove has no teardown hook of its own, so a graph (and its registry row)
outlives the worktree it was built for until something notices and reaps it. We've since built
our own sweep for this — a script that unregisters any registry row whose directory no longer
exists on disk, keyed strictly on path existence, never on "absent from git worktree list" (our own registry legitimately holds rows for other repositories too, not only
worktrees of this one, so diffing against git worktree list would delete unrelated repos'
rows). That sweep cleans up the orphans, but it does nothing about the steady-state cost of
every worktree that is still live, each carrying a full independent copy of a graph over
largely the same tree.

Why "branch-aware" is the right frame, not "smaller graphs"

Two worktrees off the same base commit — the overwhelmingly common case right after
git worktree add, and still mostly true for any worktree whose branch hasn't drifted far —
share nearly all of their tracked-file content by construction (that's what git worktree
is: one .git, divergent working directories). Building two ~3 GB graphs for that pair is
redoing nearly-identical work twice over, not indexing genuinely different code. A
generated-file ignore convention can't touch this, because the duplication isn't in what gets
indexed per file — it's in indexing the same file's structure once per worktree instead of
once per unique blob/tree state.

The two directions that seem most promising, from the outside (we haven't looked at CRG's
internals enough to say which is more tractable against the current storage model):

1. A shared base graph plus per-worktree overlay. Build once against a shared ancestor
   (e.g. the merge-base with the repo's trunk, or a designated "warm" commit), and let each
   worktree's incremental update apply only the diff between that base and its own HEAD (plus
   uncommitted changes) as a thin overlay. Query resolution reads base-then-overlay. This is the
   closest analogue to what our Postgres CoW branching already does for us, and it's the shape
   we'd most want, if the incremental-update machinery CRG already has (2.3.8's confidence-field
   work suggests the incremental path is actively maintained) can be pointed at a shared base
   instead of only at "this worktree's own prior graph."
2. Content-addressed node/edge storage shared across worktrees, keyed by blob/tree hash rather
   than by worktree path. More invasive, but would let any two worktrees (not just
   ancestor-descendant pairs) dedupe identical file structure, which a base+overlay model can't
   do once two branches have diverged from each other as well as from trunk.

Either way, the registry (~/.code-review-graph/registry.json today) would need to become
branch/commit-aware rather than purely path-aware, since "one row per worktree path" is
precisely the model that makes today's storage per-worktree in the first place.

What we're NOT asking for

Not asking for a smaller graph, a slower index, or an ignore mechanism — we measured (2026-08-13)
that our graph has no fat to trim: 1 node out of roughly 144,000 matched a generated-file
pattern. This is specifically a "the same structural information is being stored once per
worktree when the worktrees mostly overlap" problem, and we'd rather describe our actual usage
shape than guess at upstream's preferred design — happy to test a prototype against our repo
(dozens of services, a large tracked tree, and 9 concurrently live registered worktrees carrying
19.1 GB of built graph as of the 2026-08-30 snapshot above) if that's useful data for scoping
this.