Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

perf(list): cache ahead/behind counts SHA-keyed; skip the for-each-ref walk on warm runs (#2704)

Maximilian Roos0b088b579013
diff --git a/docs/content/faq.md b/docs/content/faq.md
index 21656c5fe..00cb5e796 100644
--- a/docs/content/faq.md
+++ b/docs/content/faq.md
@@ -118,7 +118,7 @@ Worktrunk stores small amounts of cache and log data in the repository's `.git/`
| Location | Purpose | Created by |
|----------|---------|------------|
| `git config worktrunk.*` | Cached default branch, switch history, branch markers, custom variables | Various commands |
-| `.git/wt/cache/{kind}/*.json` | Cached CI status and git command results (merge-tree, integration probes, diff stats, ancestry checks) | `wt list`, `wt merge`, `wt remove` |
+| `.git/wt/cache/{kind}/*.json` | Cached CI status and git command results (merge-tree, integration probes, diff stats, ancestry checks, ahead/behind counts) | `wt list`, `wt merge`, `wt remove` |
| `.git/wt/cache/summary/{branch}/{hash}.json` | Cached LLM branch summaries, content-addressed by diff hash | `wt list --full`, `wt switch` (when `[list] summary = true`) |
| `.git/wt/logs/{branch}/**/*.log` | Background hook output (nested per branch) | Hooks, background `wt remove` |
| `.git/wt/logs/commands.jsonl` | Command audit log (~2MB max) | Hooks, LLM commands |
diff --git a/skills/worktrunk/reference/faq.md b/skills/worktrunk/reference/faq.md
index f3a7e92ff..838e5ec18 100644
--- a/skills/worktrunk/reference/faq.md
+++ b/skills/worktrunk/reference/faq.md
@@ -111,7 +111,7 @@ Worktrunk stores small amounts of cache and log data in the repository's `.git/`
| Location | Purpose | Created by |
|----------|---------|------------|
| `git config worktrunk.*` | Cached default branch, switch history, branch markers, custom variables | Various commands |
-| `.git/wt/cache/{kind}/*.json` | Cached CI status and git command results (merge-tree, integration probes, diff stats, ancestry checks) | `wt list`, `wt merge`, `wt remove` |
+| `.git/wt/cache/{kind}/*.json` | Cached CI status and git command results (merge-tree, integration probes, diff stats, ancestry checks, ahead/behind counts) | `wt list`, `wt merge`, `wt remove` |
| `.git/wt/cache/summary/{branch}/{hash}.json` | Cached LLM branch summaries, content-addressed by diff hash | `wt list --full`, `wt switch` (when `[list] summary = true`) |
| `.git/wt/logs/{branch}/**/*.log` | Background hook output (nested per branch) | Hooks, background `wt remove` |
| `.git/wt/logs/commands.jsonl` | Command audit log (~2MB max) | Hooks, LLM commands |
diff --git a/src/commands/list/collect/mod.rs b/src/commands/list/collect/mod.rs
index 8248c8362..45449b0f7 100644
--- a/src/commands/list/collect/mod.rs
+++ b/src/commands/list/collect/mod.rs
@@ -151,6 +151,7 @@
//! | `is-ancestor/` | `git::repository::sha_cache` | `{base_sha}-{head_sha}.json` | Never — content-addressed |
//! | `has-added-changes/` | `git::repository::sha_cache` | `{branch_sha}-{target_sha}.json` | Never — content-addressed |
//! | `diff-stats/` | `git::repository::sha_cache` | `{base_sha}-{head_sha}.json` | Never — content-addressed |
+//! | `ahead-behind/` | `git::repository::sha_cache` | `{base_sha}-{head_sha}.json` | Never — content-addressed |
//! | `ci-status/` | `commands::list::ci_status::cache` | `{branch}.json` | TTL 30–60s + HEAD SHA check |
//! | `summary/{branch}/` | `summary` | `{diff_hash}.json` | Miss if no file exists for the current hash; siblings pruned on write |
//!
@@ -158,7 +159,7 @@
//!
//! - **SHA-pair**: pure function of two commit SHAs. Never stale, no TTL, no invalidation.
//! Used by all `sha_cache` kinds (merge-tree conflicts, merge-add probes, ancestry
-//! checks, file-change probes, diff stats).
+//! checks, file-change probes, diff stats, ahead/behind counts).
//! - **Branch + TTL + HEAD**: external mutable state (CI API, remote refs). TTL bounds
//! staleness; the HEAD check invalidates early when the branch moves.
//! - **Branch + content-addressed hash in filename**: content hash (SHA-256
@@ -177,6 +178,7 @@
//! | `IsAncestor` | `sha_cache` (is-ancestor) |
//! | `HasFileChanges` | `sha_cache` (has-added-changes) |
//! | `BranchDiff` | `sha_cache` (diff-stats, skipped when sparse checkout is active) |
+//! | `AheadBehind` | `sha_cache` (ahead-behind); on a cold base the snapshot pre-fills it from one `for-each-ref %(ahead-behind)` walk |
//! | `CiStatus` | `ci_status::cache` |
//! | `SummaryGenerate` | `summary` |
//!
@@ -184,8 +186,6 @@
//!
//! ### Already optimized (not cache candidates)
//!
-//! - `AheadBehind` — batch-optimized via single `git for-each-ref %(ahead-behind:main)`
-//! (~11ms for all branches); per-branch tasks read the in-memory cache
//! - `CommittedTreesMatch` — single `git rev-parse` resolving both tree SHAs (~1ms)
//! - `Upstream` — upstream names batch-fetched via single `git for-each-ref
//! %(upstream:short)`; per-branch tasks read the in-memory cache
@@ -1120,11 +1120,26 @@ pub fn collect(
let _ = previous_branch_cell.set(repo.switch_previous());
});
- // Capture ref state. One `for-each-ref refs/heads/ refs/remotes/`
- // plus (when default_branch is known) one `for-each-ref
- // %(ahead-behind:BASE)` batch. The snapshot replaces the prior
+ // Capture ref state: `for-each-ref refs/heads/ refs/remotes/`,
+ // plus — when default_branch is known and the per-base
+ // ahead-behind cache doesn't already cover the branches — one
+ // `for-each-ref %(ahead-behind:BASE)` walk (scoped to the cold
+ // subset; warm runs do neither). The snapshot replaces the prior
// `commit_shas` priming + `batch_ahead_behind` pair: tasks consume
// it by SHA, dodging ref→SHA cache staleness.
+ //
+ // TODO(ahead-behind-pool): the `%(ahead-behind)` walk that runs
+ // here on a cold cache is serial — it blocks this scope, and the
+ // big task pool can't open until it returns. Nothing downstream of
+ // work-item generation actually needs the ahead/behind *counts*
+ // (only the per-row `AheadBehindTask` reads them, and it has a
+ // per-SHA fallback) — only the cheap `for-each-ref refs/heads/
+ // refs/remotes/` ref scan gates work-item generation. So the walk
+ // could become a single work item in the pool, overlapping the
+ // other ~N workers, instead of a serial prelude. That needs an
+ // inter-task dependency (the per-row tasks would wait on it, or it
+ // would emit their results directly) — the work-item model has
+ // none today.
s.spawn(|_| {
let snap = match default_branch.as_deref() {
Some(db) => repo.capture_refs_with_ahead_behind(db).ok(),
diff --git a/src/commands/list/collect/tasks.rs b/src/commands/list/collect/tasks.rs
index 81244dd97..4acaa1566 100644
--- a/src/commands/list/collect/tasks.rs
+++ b/src/commands/list/collect/tasks.rs
@@ -811,6 +811,17 @@ impl Task for UpstreamTask {
// — for the upstream comparison we want the branch's actual tip,
// which `branch_ref.commit_sha` carries (snapshot tracks the same
// value for branch items via the for-each-ref scan).
+ //
+ // `ahead_behind_by_sha` is persistently cached (`ahead-behind/`
+ // SHA-keyed), so warm runs are pure reads. What's still missing is
+ // a *cold-start batch primer* like the one `RefSnapshot` runs for
+ // the `main↕` column (`for-each-ref %(ahead-behind:main)`):
+ // TODO(remote-ahead-behind-batch): on a cold cache, prime this
+ // column in one shot via `for-each-ref --format='%(refname)
+ // %(upstream:track,nobracket)' refs/heads/` (ahead/behind vs each
+ // branch's *own* upstream in a single walk), seed the
+ // `ahead-behind/` cache from it, and let this per-row call fall
+ // through to the read — mirroring `capture_ahead_behind`.
let upstream_sha = ctx
.resolve_sha(&upstream_branch)
.map_err(|e| ctx.error(Self::KIND, &e))?;
diff --git a/src/git/repository/diff.rs b/src/git/repository/diff.rs
index 5bcdcf164..3846f48b8 100644
--- a/src/git/repository/diff.rs
+++ b/src/git/repository/diff.rs
@@ -202,18 +202,25 @@ impl Repository {
/// SHA-keyed ahead/behind counts.
///
- /// Inputs are commit SHAs. Uncached — counts are typically primed in
- /// bulk by [`crate::git::RefSnapshot`]'s ahead/behind batch; this is
- /// the per-pair fallback for snapshot misses or callers that already
- /// hold SHAs. Returns `(ahead, behind)` where ahead is commits in
- /// head not in base; orphan branches (no common ancestor) yield
- /// `(0, 0)` — caller should distinguish via [`Self::merge_base_by_sha`].
+ /// Inputs are commit SHAs. Backed by the persistent SHA-keyed cache
+ /// (`ahead-behind/{base_sha}-{head_sha}.json`) — content-addressed, so
+ /// the entry is never stale. `wt list` populates this per branch (and
+ /// in bulk from a `for-each-ref %(ahead-behind)` batch when most
+ /// entries are cold); subsequent runs are pure cache reads. Returns
+ /// `(ahead, behind)` where ahead is commits in head not in base;
+ /// orphan branches (no common ancestor) yield `(0, 0)` — caller should
+ /// distinguish via [`Self::merge_base_by_sha`].
pub fn ahead_behind_by_sha(
&self,
base_sha: &str,
head_sha: &str,
) -> anyhow::Result<(usize, usize)> {
- self.compute_ahead_behind(base_sha, head_sha)
+ if let Some(cached) = super::sha_cache::ahead_behind(self, base_sha, head_sha) {
+ return Ok(cached);
+ }
+ let result = self.compute_ahead_behind(base_sha, head_sha)?;
+ super::sha_cache::put_ahead_behind(self, base_sha, head_sha, result);
+ Ok(result)
}
fn compute_ahead_behind(&self, base: &str, head: &str) -> anyhow::Result<(usize, usize)> {
diff --git a/src/git/repository/ref_snapshot.rs b/src/git/repository/ref_snapshot.rs
index 56e6f9225..ada9a9f17 100644
--- a/src/git/repository/ref_snapshot.rs
+++ b/src/git/repository/ref_snapshot.rs
@@ -18,8 +18,14 @@
//! [`Repository::capture_refs`] runs one `git for-each-ref refs/heads/`
//! plus one `git for-each-ref refs/remotes/` and parses both into a
//! single `RefSnapshot`. [`Repository::capture_refs_with_ahead_behind`]
-//! additionally runs `for-each-ref ... %(ahead-behind:BASE)` (git ≥ 2.36)
-//! to populate ahead/behind counts in the same snapshot.
+//! additionally populates ahead/behind counts: it reads them from the
+//! persistent SHA-keyed cache (`ahead-behind/` — content-addressed, so
+//! never stale) and only falls back to a `for-each-ref ...
+//! %(ahead-behind:BASE)` batch walk (git ≥ 2.36) when the cache is cold
+//! for this base, seeding the cache from the batch so later runs are pure
+//! reads. Branches that moved since the last run are left out of the
+//! snapshot map — the per-branch `AheadBehindTask` recomputes (and
+//! caches) those by SHA in the parallel pool.
//!
//! # Lifetime
//!
@@ -61,9 +67,11 @@ pub struct RefSnapshot {
/// Ahead/behind counts keyed by `(base, head)` ref names.
/// Populated only when constructed via
- /// [`Repository::capture_refs_with_ahead_behind`]; empty otherwise.
- /// On git < 2.36 the batch fails silently and this stays empty —
- /// callers that need ahead/behind must fall back to a per-pair query.
+ /// [`Repository::capture_refs_with_ahead_behind`], and even then it
+ /// may be partial: a branch that moved since its last cache write is
+ /// omitted (the per-branch task recomputes it by SHA). On git < 2.36
+ /// a cold base yields an empty map. Callers that need ahead/behind for
+ /// an absent key must fall back to a per-pair query.
ahead_behind: HashMap<(String, String), (usize, usize)>,
}
@@ -98,8 +106,10 @@ impl RefSnapshot {
/// Look up cached ahead/behind counts.
///
/// Returns `None` when the snapshot was constructed without ahead/behind
- /// (the default `capture_refs`) or when the requested pair is missing
- /// from the batch result.
+ /// (the default `capture_refs`) or when the requested pair is missing —
+ /// either uncomputed (git < 2.36 on a cold base) or omitted because the
+ /// branch moved since its last cache write. Callers fall back to a
+ /// per-pair query (`Repository::ahead_behind_by_sha`).
pub fn ahead_behind(&self, base: &str, head: &str) -> Option<(usize, usize)> {
self.ahead_behind
.get(&(base.to_string(), head.to_string()))
@@ -138,17 +148,166 @@ impl Repository {
/// Capture current ref state plus ahead/behind counts vs `base`.
///
- /// Runs the two ref scans plus one additional `for-each-ref
- /// --format='%(ahead-behind:BASE)'` pass (git ≥ 2.36). On older git
- /// the ahead/behind batch fails silently and the snapshot's
- /// [`RefSnapshot::ahead_behind`] returns `None` for every key —
- /// callers fall back to per-pair queries.
+ /// Ahead/behind for `(base, branch)` is content-addressed — a pure
+ /// function of the two commit SHAs — so the snapshot map is built from
+ /// the persistent `ahead-behind/` cache. When some branches aren't
+ /// cached (a fresh repo, after `wt config state clear`, or branches
+ /// that moved since their last write) the misses are filled by:
+ /// - a few misses → left out of the map; the per-branch
+ /// `AheadBehindTask` recomputes (and caches) them by SHA in the
+ /// parallel pool;
+ /// - everything cold → one unscoped `for-each-ref %(ahead-behind)
+ /// refs/heads/` walk, results written to the cache;
+ /// - many cold but not all → one `for-each-ref %(ahead-behind)` scoped
+ /// to the missed refnames, results written to the cache.
+ ///
+ /// The walk computes against `base`'s resolved SHA (not the refname,
+ /// which git could resolve to a different commit) and the cache is
+ /// keyed by the object SHA the batch reports for each branch, so the
+ /// stored value always agrees with what `ahead_behind_by_sha` would
+ /// recompute. Orphan branches (no common ancestor with `base`) are
+ /// normalized to `(0, 0)`, matching `compute_ahead_behind`. On git <
+ /// 2.36 the `%(ahead-behind)` walk yields nothing and the affected
+ /// keys stay absent — callers fall back to per-pair queries.
pub fn capture_refs_with_ahead_behind(&self, base: &str) -> anyhow::Result<RefSnapshot> {
let locals = scan_locals(self)?;
let remotes = scan_remotes(self)?;
- let ahead_behind = scan_ahead_behind(self, base);
+ let ahead_behind = self.capture_ahead_behind(base, &locals, &remotes);
Ok(build(locals, remotes, ahead_behind))
}
+
+ /// Build the `(base, refs/heads/X) -> (ahead, behind)` map for the
+ /// local branches, preferring the persistent SHA-keyed cache and
+ /// reaching for a `for-each-ref %(ahead-behind)` walk only for the
+ /// branches the cache doesn't cover. See
+ /// [`Self::capture_refs_with_ahead_behind`].
+ fn capture_ahead_behind(
+ &self,
+ base: &str,
+ locals: &[LocalBranch],
+ remotes: &[RemoteBranch],
+ ) -> HashMap<(String, String), (usize, usize)> {
+ let full_ref = |b: &LocalBranch| format!("refs/heads/{}", b.name);
+
+ // The cache is SHA-keyed; we need base's SHA, and it's a branch —
+ // so it's among the refs we just scanned. If somehow it isn't, the
+ // cache is unreachable for this run: run the batch against the
+ // refname (git resolves it), key the snapshot map by refname, and
+ // cache nothing.
+ let Some(base_sha) = resolve_sha_from_scan(base, locals, remotes).map(str::to_string)
+ else {
+ return scan_ahead_behind(self, base, None)
+ .into_iter()
+ .map(|(refname, (_obj, counts))| ((base.to_string(), refname), counts))
+ .collect();
+ };
+
+ let mut map = HashMap::new();
+ let mut missed: Vec<&LocalBranch> = Vec::new();
+ for b in locals {
+ match super::sha_cache::ahead_behind(self, &base_sha, &b.commit_sha) {
+ Some(counts) => {
+ map.insert((base.to_string(), full_ref(b)), counts);
+ }
+ None => missed.push(b),
+ }
+ }
+ if missed.is_empty() {
+ return map;
+ }
+
+ // How to fill the misses:
+ // - everything cold (fresh repo / after `state clear`) → one
+ // unscoped `for-each-ref %(ahead-behind:base_sha) refs/heads/`
+ // walk — a single shared traversal finds every merge-base —
+ // then seed the cache.
+ // - only a few cold → leave them out of the map; their
+ // per-branch task recomputes (and caches) by SHA in the
+ // parallel pool. That task's orphan check already primes the
+ // merge-base, so it's two cheap `rev-list --count` calls — no
+ // base-history walk to redo.
+ // - many cold but not all → one `for-each-ref
+ // %(ahead-behind:base_sha)` *scoped to the missed refnames*:
+ // same shared-traversal win, only over the cold subset.
+ //
+ // The threshold trades the per-pair path's parallelism (it runs
+ // in the pool) against the batch's lower total work (one shared
+ // base-history traversal). A batch here is serial — it blocks the
+ // pool from opening — so reach for it only once "many" cold
+ // branches make the amortization clearly worth the serial cost.
+ // The fully-parallel ideal is to run the batch as a *pool work
+ // item*; see `TODO(ahead-behind-pool)` in `collect/mod.rs`.
+ //
+ // Compute `%(ahead-behind)` against `base_sha`, not the refname:
+ // git resolving `base` itself could land on a different commit (a
+ // tag shadowing the branch), and we'd cache counts that disagree
+ // with `ahead_behind_by_sha(base_sha, ...)`. Key the cache by the
+ // *object SHA the batch saw* (`scan_ahead_behind` returns it) so a
+ // ref that moved between the initial scan and this batch can't
+ // poison the entry either. Orphan branches need normalizing: git's
+ // `%(ahead-behind)` reports the two disjoint history sizes, while
+ // `compute_ahead_behind` — what a cache *miss* recomputes —
+ // returns (0, 0) and signals orphan-ness separately. An orphan's
+ // `behind` is exactly the total commit count of base, so detect it
+ // with one `rev-list --count base_sha` and store (0, 0) instead.
+ let all_cold = missed.len() == locals.len();
+ if !all_cold && missed.len() <= AHEAD_BEHIND_SCOPED_BATCH_MIN_MISSES {
+ return map;
+ }
+ let scoped: Option<Vec<String>> =
+ (!all_cold).then(|| missed.iter().map(|&b| full_ref(b)).collect());
+ let base_total: Option<usize> = self
+ .run_command(&["rev-list", "--count", &base_sha])
+ .ok()
+ .and_then(|s| s.trim().parse().ok());
+ let fresh = scan_ahead_behind(self, &base_sha, scoped.as_deref());
+ // Stage the writes first, then hand them to `put_ahead_behind_bulk`
+ // — one `sweep_lru` at the end, not one per entry. The serial
+ // setup-scope path can't afford N×count_json_files() on a large
+ // branch list.
+ let mut writes: Vec<(&str, &str, (usize, usize))> = Vec::with_capacity(missed.len());
+ for b in &missed {
+ let Some((object_sha, (ahead, behind))) = fresh.get(&full_ref(b)) else {
+ continue;
+ };
+ let counts = if base_total == Some(*behind) {
+ (0, 0) // orphan — match compute_ahead_behind / a cache miss
+ } else {
+ (*ahead, *behind)
+ };
+ writes.push((base_sha.as_str(), object_sha.as_str(), counts));
+ map.insert((base.to_string(), full_ref(b)), counts);
+ }
+ super::sha_cache::put_ahead_behind_bulk(self, writes);
+ map
+ }
+}
+
+/// How many cache misses make a single (serial) `for-each-ref
+/// %(ahead-behind)` over the missed refs worth running here, versus
+/// letting that many per-branch tasks each recompute by SHA in the
+/// parallel pool. Below the threshold the per-pair path wins — it's
+/// parallel, and each task's orphan check has already primed the
+/// merge-base, so it skips re-walking base's history. Above it, one
+/// shared base-history traversal amortizes across the cold subset.
+const AHEAD_BEHIND_SCOPED_BATCH_MIN_MISSES: usize = 8;
+
+/// Resolve a ref name to a commit SHA using only refs already scanned into
+/// `locals`/`remotes` (no subprocess). Accepts short or qualified forms.
+fn resolve_sha_from_scan<'a>(
+ name: &str,
+ locals: &'a [LocalBranch],
+ remotes: &'a [RemoteBranch],
+) -> Option<&'a str> {
+ let local_short = name.strip_prefix("refs/heads/").unwrap_or(name);
+ if let Some(b) = locals.iter().find(|b| b.name == local_short) {
+ return Some(&b.commit_sha);
+ }
+ let remote_short = name.strip_prefix("refs/remotes/").unwrap_or(name);
+ remotes
+ .iter()
+ .find(|r| r.short_name == remote_short)
+ .map(|r| r.commit_sha.as_str())
}
fn scan_locals(repo: &Repository) -> anyhow::Result<Vec<LocalBranch>> {
@@ -184,29 +343,49 @@ fn scan_remotes(repo: &Repository) -> anyhow::Result<Vec<RemoteBranch>> {
Ok(branches)
}
-/// Best-effort ahead/behind batch via `for-each-ref %(ahead-behind:BASE)`.
+/// Best-effort ahead/behind batch via
+/// `for-each-ref %(refname) %(objectname) %(ahead-behind:BASE)` — one
+/// shared graph traversal that finds every requested ref's merge-base
+/// against `base` (a refname or, preferably for cache-keying, a SHA) and
+/// counts both sides.
///
-/// Failures (git < 2.36, invalid base) return an empty map — callers must
-/// tolerate missing keys.
-fn scan_ahead_behind(repo: &Repository, base: &str) -> HashMap<(String, String), (usize, usize)> {
- let format = format!("%(refname) %(ahead-behind:{base})");
- let output =
- match repo.run_command(&["for-each-ref", &format!("--format={format}"), "refs/heads/"]) {
- Ok(out) => out,
- Err(e) => {
- log::debug!("RefSnapshot ahead/behind batch failed for base {base}: {e}");
- return HashMap::new();
- }
- };
+/// `refs == None` walks all of `refs/heads/`; `Some(refnames)` scopes the
+/// walk to exactly those refs (still one traversal, just that subset).
+/// Returns `refname -> (object_sha, (ahead, behind))` — `object_sha` is
+/// the commit the counts were computed against, so a caller that caches
+/// by SHA keys on *it* rather than on a separately-scanned value a
+/// concurrent ref update could have made stale. Failures (git < 2.36,
+/// invalid base) return an empty map — callers must tolerate missing keys.
+fn scan_ahead_behind(
+ repo: &Repository,
+ base: &str,
+ refs: Option<&[String]>,
+) -> HashMap<String, (String, (usize, usize))> {
+ let format = format!("--format=%(refname) %(objectname) %(ahead-behind:{base})");
+ let mut args: Vec<&str> = vec!["for-each-ref", format.as_str()];
+ match refs {
+ Some(refs) => args.extend(refs.iter().map(String::as_str)),
+ None => args.push("refs/heads/"),
+ }
+ let output = match repo.run_command(&args) {
+ Ok(out) => out,
+ Err(e) => {
+ log::debug!("RefSnapshot ahead/behind batch failed for base {base}: {e}");
+ return HashMap::new();
+ }
+ };
output
.lines()
.filter_map(|line| {
- let mut parts = line.rsplitn(3, ' ');
+ // "<refname> <objectname> <ahead> <behind>" — refnames cannot
+ // contain spaces, so the leftmost chunk is exactly the refname.
+ let mut parts = line.rsplitn(4, ' ');
let behind: usize = parts.next()?.parse().ok()?;
let ahead: usize = parts.next()?.parse().ok()?;
- let full_ref = parts.next()?.to_string();
- Some(((base.to_string(), full_ref), (ahead, behind)))
+ let object_sha = parts.next()?.to_string();
+ let refname = parts.next()?.to_string();
+ Some((refname, (object_sha, (ahead, behind))))
})
.collect()
}
@@ -328,6 +507,211 @@ mod tests {
}
}
+ #[test]
+ fn ahead_behind_reads_persistent_cache_on_second_capture() {
+ let test = TestRepo::with_initial_commit();
+ test.run_git(&["checkout", "-b", "feature"]);
+ std::fs::write(test.root_path().join("a.txt"), "x\n").unwrap();
+ test.run_git(&["add", "a.txt"]);
+ test.run_git(&["commit", "-m", "feat"]);
+ test.run_git(&["checkout", "main"]);
+
+ // First capture: cold base → runs the batch walk, seeds the cache.
+ let repo = Repository::at(test.root_path()).unwrap();
+ let first = repo.capture_refs_with_ahead_behind("main").unwrap();
+ // Skip on git < 2.36 where the batch silently yields nothing.
+ let Some((1, 0)) = first.ahead_behind("main", "refs/heads/feature") else {
+ return;
+ };
+
+ // Tamper with the cached entry for (main, feature).
+ let dir = crate::cache::cache_dir(&repo, "ahead-behind");
+ let entries: Vec<_> = std::fs::read_dir(&dir)
+ .unwrap()
+ .filter_map(|e| e.ok())
+ .filter(|e| e.file_name().to_str().is_some_and(|s| s.ends_with(".json")))
+ .collect();
+ // One entry per local branch: main↔main and main↔feature.
+ let feature_sha = test.git_output(&["rev-parse", "feature"]);
+ let main_sha = test.git_output(&["rev-parse", "main"]);
+ let tampered_path = dir.join(format!("{main_sha}-{feature_sha}.json"));
+ assert!(
+ entries.iter().any(|e| e.path() == tampered_path),
+ "expected a cache entry for (main, feature)"
+ );
+ std::fs::write(&tampered_path, "[7,3]").unwrap();
+
+ // Second capture (fresh repo): every entry is cached → no batch
+ // walk → the map reflects the tampered value.
+ let repo2 = Repository::at(test.root_path()).unwrap();
+ let second = repo2.capture_refs_with_ahead_behind("main").unwrap();
+ assert_eq!(
+ second.ahead_behind("main", "refs/heads/feature"),
+ Some((7, 3)),
+ "second capture should read the (tampered) persistent cache"
+ );
+ }
+
+ #[test]
+ fn ahead_behind_omits_moved_branch_from_partial_snapshot() {
+ let test = TestRepo::with_initial_commit();
+ test.run_git(&["checkout", "-b", "feature"]);
+ std::fs::write(test.root_path().join("a.txt"), "x\n").unwrap();
+ test.run_git(&["add", "a.txt"]);
+ test.run_git(&["commit", "-m", "feat"]);
+ test.run_git(&["checkout", "main"]);
+
+ let repo = Repository::at(test.root_path()).unwrap();
+ let first = repo.capture_refs_with_ahead_behind("main").unwrap();
+ // Skip on git < 2.36.
+ if first.ahead_behind("main", "refs/heads/feature").is_none() {
+ return;
+ }
+
+ // Advance feature so its SHA (and thus its cache key) changes; main
+ // stays put, so its cache entry is still a hit.
+ test.run_git(&["checkout", "feature"]);
+ std::fs::write(test.root_path().join("b.txt"), "y\n").unwrap();
+ test.run_git(&["add", "b.txt"]);
+ test.run_git(&["commit", "-m", "feat2"]);
+ test.run_git(&["checkout", "main"]);
+
+ let repo2 = Repository::at(test.root_path()).unwrap();
+ let snap = repo2.capture_refs_with_ahead_behind("main").unwrap();
+ // Partial-warm path: feature moved → omitted from the snapshot map
+ // (its per-branch task recomputes by SHA); main is still present.
+ assert_eq!(snap.ahead_behind("main", "refs/heads/feature"), None);
+ assert_eq!(snap.ahead_behind("main", "refs/heads/main"), Some((0, 0)));
+ }
+
+ #[test]
+ fn ahead_behind_many_misses_uses_scoped_batch() {
+ let test = TestRepo::with_initial_commit();
+ // 10 feature branches, each one (empty) commit ahead of main —
+ // more than `AHEAD_BEHIND_SCOPED_BATCH_MIN_MISSES`.
+ for i in 0..10 {
+ test.run_git(&["checkout", "-b", &format!("feat{i}"), "main"]);
+ test.run_git(&["commit", "--allow-empty", "-m", &format!("c{i}")]);
+ }
+ test.run_git(&["checkout", "main"]);
+
+ // First capture: everything cold → unscoped batch seeds the cache.
+ let repo = Repository::at(test.root_path()).unwrap();
+ let first = repo.capture_refs_with_ahead_behind("main").unwrap();
+ if first.ahead_behind("main", "refs/heads/feat0").is_none() {
+ return; // git < 2.36 — %(ahead-behind) unsupported
+ }
+
+ // Advance every feature branch; main stays put. Now 10 of the 11
+ // local branches miss the cache (main still hits) → "many cold but
+ // not all" → the scoped `for-each-ref %(ahead-behind)` path over
+ // just the 10 missed refnames.
+ for i in 0..10 {
+ test.run_git(&["checkout", &format!("feat{i}")]);
+ test.run_git(&["commit", "--allow-empty", "-m", &format!("c{i}b")]);
+ }
+ test.run_git(&["checkout", "main"]);
+
+ let repo2 = Repository::at(test.root_path()).unwrap();
+ let snap = repo2.capture_refs_with_ahead_behind("main").unwrap();
+ for i in 0..10 {
+ assert_eq!(
+ snap.ahead_behind("main", &format!("refs/heads/feat{i}")),
+ Some((2, 0)),
+ "feat{i} is 2 ahead of main after the scoped re-walk"
+ );
+ }
+ // main never moved → still the (0,0) entry from the first capture.
+ assert_eq!(snap.ahead_behind("main", "refs/heads/main"), Some((0, 0)));
+ }
+
+ #[test]
+ fn ahead_behind_normalizes_orphan_to_zero_in_cache() {
+ let test = TestRepo::with_initial_commit();
+ // An orphan branch: its own root commit, no common ancestor with main.
+ test.run_git(&["checkout", "--orphan", "orphanbr"]);
+ test.run_git(&["rm", "-rfq", "."]);
+ std::fs::write(test.root_path().join("o.txt"), "y\n").unwrap();
+ test.run_git(&["add", "o.txt"]);
+ test.run_git(&["commit", "-m", "orphan root"]);
+ test.run_git(&["checkout", "main"]);
+
+ let repo = Repository::at(test.root_path()).unwrap();
+ let snap = repo.capture_refs_with_ahead_behind("main").unwrap();
+ // git < 2.36 — %(ahead-behind) unsupported, nothing seeded.
+ if snap.ahead_behind("main", "refs/heads/main").is_none() {
+ return;
+ }
+
+ // Git's batch reports the two disjoint history sizes for an orphan;
+ // we normalize to (0, 0) so the snapshot — and the persistent
+ // cache entry — agree with `compute_ahead_behind` / a cache miss.
+ assert_eq!(
+ snap.ahead_behind("main", "refs/heads/orphanbr"),
+ Some((0, 0))
+ );
+
+ let main_sha = test.git_output(&["rev-parse", "main"]);
+ let orphan_sha = test.git_output(&["rev-parse", "orphanbr"]);
+ let cached: (usize, usize) = serde_json::from_str(
+ &std::fs::read_to_string(
+ crate::cache::cache_dir(&repo, "ahead-behind")
+ .join(format!("{main_sha}-{orphan_sha}.json")),
+ )
+ .expect("orphan pair should be cached"),
+ )
+ .expect("cache entry is a (usize, usize)");
+ assert_eq!(cached, (0, 0));
+ }
+
+ #[test]
+ fn ahead_behind_base_resolves_via_remote_tracking_ref() {
+ let test = TestRepo::with_initial_commit();
+ // A remote-tracking ref with no local branch of the same name —
+ // the base SHA must be resolved from the remotes scan, not locals.
+ let trunk_sha = test.git_output(&["rev-parse", "main"]);
+ test.run_git(&["update-ref", "refs/remotes/origin/trunk", &trunk_sha]);
+ test.run_git(&["checkout", "-b", "feature"]);
+ std::fs::write(test.root_path().join("a.txt"), "x\n").unwrap();
+ test.run_git(&["add", "a.txt"]);
+ test.run_git(&["commit", "-m", "feat"]);
+
+ let repo = Repository::at(test.root_path()).unwrap();
+ let snap = repo.capture_refs_with_ahead_behind("origin/trunk").unwrap();
+ let Some((1, 0)) = snap.ahead_behind("origin/trunk", "refs/heads/feature") else {
+ // git < 2.36: batch silently empty; the cache is unreachable
+ // for it, but resolve-via-remote still ran without panicking.
+ return;
+ };
+ // Seeded the SHA cache keyed by the remote ref's SHA.
+ let feature_sha = test.git_output(&["rev-parse", "feature"]);
+ assert!(
+ crate::cache::cache_dir(&repo, "ahead-behind")
+ .join(format!("{trunk_sha}-{feature_sha}.json"))
+ .exists()
+ );
+ }
+
+ #[test]
+ fn ahead_behind_unresolvable_base_is_harmless() {
+ let test = TestRepo::with_initial_commit();
+ let repo = Repository::at(test.root_path()).unwrap();
+ // A base that resolves to nothing: no extra subprocess can key the
+ // cache, and the `for-each-ref %(ahead-behind:...)` walk fails too.
+ // The snapshot is still valid, just without ahead/behind.
+ let snap = repo
+ .capture_refs_with_ahead_behind("definitely-not-a-ref")
+ .unwrap();
+ assert_eq!(
+ snap.ahead_behind("definitely-not-a-ref", "refs/heads/main"),
+ None
+ );
+ assert_eq!(
+ snap.resolve("main"),
+ repo.capture_refs().unwrap().resolve("main")
+ );
+ }
+
#[test]
fn capture_refs_populates_local_branch_cache() {
// The local-branch inventory cache is populated as a side-effect
diff --git a/src/git/repository/sha_cache.rs b/src/git/repository/sha_cache.rs
index dfc4f02cd..769189633 100644
--- a/src/git/repository/sha_cache.rs
+++ b/src/git/repository/sha_cache.rs
@@ -9,10 +9,11 @@
//!
//! Layout: `.git/wt/cache/{kind}/{key}.json` where `kind` is one of
//! `merge-tree-conflicts`, `merge-add-probe`, `is-ancestor`,
-//! `has-added-changes`, or `diff-stats`. Symmetric kinds sort the SHA pair
-//! so `(A, B)` and `(B, A)` hit the same entry; asymmetric kinds preserve
-//! ordering. See [`crate::cache`] for read/write/clear mechanics,
-//! torn-write semantics, and the user-initiated clear error policy.
+//! `has-added-changes`, `diff-stats`, or `ahead-behind`. Symmetric kinds
+//! sort the SHA pair so `(A, B)` and `(B, A)` hit the same entry;
+//! asymmetric kinds preserve ordering. See [`crate::cache`] for
+//! read/write/clear mechanics, torn-write semantics, and the
+//! user-initiated clear error policy.
use super::Repository;
use super::integration::MergeProbeResult;
@@ -29,6 +30,7 @@ const KIND_MERGE_ADD_PROBE: &str = "merge-add-probe";
const KIND_IS_ANCESTOR: &str = "is-ancestor";
const KIND_HAS_ADDED_CHANGES: &str = "has-added-changes";
const KIND_DIFF_STATS: &str = "diff-stats";
+const KIND_AHEAD_BEHIND: &str = "ahead-behind";
/// All cache kind identifiers, used by [`clear_all`].
const ALL_KINDS: &[&str] = &[
@@ -37,6 +39,7 @@ const ALL_KINDS: &[&str] = &[
KIND_IS_ANCESTOR,
KIND_HAS_ADDED_CHANGES,
KIND_DIFF_STATS,
+ KIND_AHEAD_BEHIND,
];
/// Build a symmetric filename from a SHA pair (order-independent).
@@ -182,6 +185,56 @@ pub(super) fn put_diff_stats(repo: &Repository, base_sha: &str, head_sha: &str,
);
}
+// ahead-behind (asymmetric)
+
+/// Look up a cached `ahead_behind(base_sha, head_sha)` result `(ahead, behind)`.
+///
+/// Asymmetric: the counts are relative to `base_sha`, so swapping the
+/// arguments swaps `ahead` and `behind` — a different question, a
+/// different entry. Content-addressed and never stale: the two commit
+/// SHAs fix the merge-base and both rev-list counts.
+pub(super) fn ahead_behind(
+ repo: &Repository,
+ base_sha: &str,
+ head_sha: &str,
+) -> Option<(usize, usize)> {
+ cache::read(repo, KIND_AHEAD_BEHIND, &asymmetric_key(base_sha, head_sha))
+}
+
+/// Store an `ahead_behind(base_sha, head_sha)` result.
+pub(super) fn put_ahead_behind(
+ repo: &Repository,
+ base_sha: &str,
+ head_sha: &str,
+ value: (usize, usize),
+) {
+ cache::write_with_lru(
+ repo,
+ KIND_AHEAD_BEHIND,
+ &asymmetric_key(base_sha, head_sha),
+ &value,
+ MAX_ENTRIES_PER_KIND,
+ );
+}
+
+/// Bulk-write a sequence of `ahead_behind` entries, deferring the LRU
+/// sweep to a single pass at the end. Use this for batch seeding (one
+/// cache kind, many entries) — `put_ahead_behind` goes through
+/// `write_with_lru`, which scans the cache directory on *every* call, so
+/// N successive calls cost O(N · dir_size) wall (and on the serial setup
+/// path that's O(N²) before the worker pool even opens). The bulk form
+/// pays one final `sweep_lru` instead.
+pub(super) fn put_ahead_behind_bulk<'a, I>(repo: &Repository, entries: I)
+where
+ I: IntoIterator<Item = (&'a str, &'a str, (usize, usize))>,
+{
+ let dir = cache::cache_dir(repo, KIND_AHEAD_BEHIND);
+ for (base_sha, head_sha, value) in entries {
+ cache::write_json(&dir.join(asymmetric_key(base_sha, head_sha)), &value);
+ }
+ cache::sweep_lru(&dir, MAX_ENTRIES_PER_KIND);
+}
+
// Maintenance
/// Clear all cached SHA-keyed entries, returning the count removed. Called
@@ -528,6 +581,25 @@ mod tests {
assert_eq!(diff_stats(&repo, "bbbb", "aaaa"), None);
}
+ #[test]
+ fn test_ahead_behind_roundtrip() {
+ let test = TestRepo::with_initial_commit();
+ let repo = Repository::at(test.root_path()).unwrap();
+
+ assert_eq!(ahead_behind(&repo, "aaaa", "bbbb"), None);
+
+ put_ahead_behind(&repo, "aaaa", "bbbb", (3, 5));
+ assert_eq!(ahead_behind(&repo, "aaaa", "bbbb"), Some((3, 5)));
+
+ // Asymmetric: swapped args miss (the question "ahead/behind relative
+ // to bbbb" is distinct from "relative to aaaa")
+ assert_eq!(ahead_behind(&repo, "bbbb", "aaaa"), None);
+
+ // Overwrite with a new value
+ put_ahead_behind(&repo, "aaaa", "bbbb", (0, 0));
+ assert_eq!(ahead_behind(&repo, "aaaa", "bbbb"), Some((0, 0)));
+ }
+
// Cache consultation: is_ancestor, has_added_changes, branch_diff_stats
#[test]
@@ -588,6 +660,43 @@ mod tests {
assert!(!repo2.has_added_changes("feature", "main").unwrap());
}
+ #[test]
+ fn test_ahead_behind_reads_cache() {
+ let test = TestRepo::with_initial_commit();
+
+ test.run_git(&["checkout", "-b", "feature"]);
+ fs::write(test.root_path().join("new.txt"), "content\n").unwrap();
+ test.run_git(&["add", "new.txt"]);
+ test.run_git(&["commit", "-m", "Feature"]);
+
+ let main_sha = test.git_output(&["rev-parse", "main"]);
+ let feature_sha = test.git_output(&["rev-parse", "feature"]);
+
+ let repo = Repository::at(test.root_path()).unwrap();
+
+ // Real computation: feature is 1 ahead, 0 behind main
+ assert_eq!(
+ repo.ahead_behind_by_sha(&main_sha, &feature_sha).unwrap(),
+ (1, 0)
+ );
+
+ // Tamper with cache to return different counts
+ let dir = cache::cache_dir(&repo, KIND_AHEAD_BEHIND);
+ let entries: Vec<_> = fs::read_dir(&dir)
+ .unwrap()
+ .filter_map(|e| e.ok())
+ .filter(|e| e.file_name().to_str().is_some_and(|s| s.ends_with(".json")))
+ .collect();
+ assert_eq!(entries.len(), 1);
+ fs::write(entries[0].path(), "[9,8]").unwrap();
+
+ let repo2 = Repository::at(test.root_path()).unwrap();
+ assert_eq!(
+ repo2.ahead_behind_by_sha(&main_sha, &feature_sha).unwrap(),
+ (9, 8)
+ );
+ }
+
#[test]
fn test_branch_diff_stats_reads_cache() {
let test = TestRepo::with_initial_commit();
@@ -652,9 +761,10 @@ mod tests {
deleted: 0,
},
);
+ put_ahead_behind(&repo, "a", "b", (1, 0));
let cleared = clear_all(&repo).unwrap();
- assert_eq!(cleared, 5, "should clear one entry per kind");
+ assert_eq!(cleared, 6, "should clear one entry per kind");
// All kinds should be empty
assert_eq!(merge_conflicts(&repo, "a", "b"), None);
@@ -662,5 +772,6 @@ mod tests {
assert_eq!(is_ancestor(&repo, "a", "b"), None);
assert_eq!(has_added_changes(&repo, "a", "b"), None);
assert_eq!(diff_stats(&repo, "a", "b"), None);
+ assert_eq!(ahead_behind(&repo, "a", "b"), None);
}
}