Skip to content

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

perf(list): cold-start primer for the Remote⇅ column, per-upstream-group (#2718)

Maximilian Roosc7403f4f0565
diff --git a/src/commands/list/collect/mod.rs b/src/commands/list/collect/mod.rs
index 45449b0f7..220f1ba4a 100644
--- a/src/commands/list/collect/mod.rs
+++ b/src/commands/list/collect/mod.rs
@@ -178,7 +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 |
+//! | `AheadBehind`, `Upstream` | `sha_cache` (ahead-behind); on a cold cache both columns are pre-filled from `for-each-ref %(ahead-behind:SHA)` walks — one against the default branch (`main↕`, in `RefSnapshot::capture_ahead_behind`) and one per unique upstream SHA (`Remote⇅`, in `Repository::prime_upstream_ahead_behind_cache`) |
//! | `CiStatus` | `ci_status::cache` |
//! | `SummaryGenerate` | `summary` |
//!
@@ -187,8 +187,6 @@
//! ### Already optimized (not cache candidates)
//!
//! - `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
//!
//! ### Cached via tree SHA
//!
@@ -1112,7 +1110,8 @@ pub fn collect(
// See: https://gitlab.com/gitlab-org/git/-/merge_requests/148 (scalar's fsmonitor workaround)
// See: https://github.com/jj-vcs/jj/issues/6440 (jj hit same fsmonitor issue)
let previous_branch_cell: OnceCell<Option<String>> = OnceCell::new();
- let snapshot_cell: OnceCell<Option<worktrunk::git::RefSnapshot>> = OnceCell::new();
+ let snapshot_cell: OnceCell<Option<std::sync::Arc<worktrunk::git::RefSnapshot>>> =
+ OnceCell::new();
rayon::scope(|s| {
// Previous branch lookup (for gutter symbol)
@@ -1128,6 +1127,10 @@ pub fn collect(
// `commit_shas` priming + `batch_ahead_behind` pair: tasks consume
// it by SHA, dodging ref→SHA cache staleness.
//
+ // After the snapshot is built, an inner spawn primes the
+ // `Remote⇅` cache off its already-scanned inventories — see the
+ // nested `s.spawn` below for the rationale.
+ //
// 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
@@ -1140,11 +1143,66 @@ pub fn collect(
// 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(|_| {
+ s.spawn(|s| {
let snap = match default_branch.as_deref() {
Some(db) => repo.capture_refs_with_ahead_behind(db).ok(),
None => repo.capture_refs().ok(),
- };
+ }
+ .map(std::sync::Arc::new);
+
+ // Prime the `ahead-behind/` SHA-cache for the `Remote⇅`
+ // column, pairing each local branch with its configured
+ // upstream. Mirrors the `main↕` priming inside
+ // `capture_refs_with_ahead_behind`, but per-upstream-group
+ // instead of single-base: one serial `for-each-ref
+ // %(ahead-behind:UPSTREAM_SHA)` walk per unique upstream
+ // that's both cold and above the same threshold.
+ //
+ // Nested inside this spawn (rather than a sibling) so it can
+ // read the snapshot's already-scanned local/remote
+ // inventories — a sibling spawn would race the snapshot's
+ // own scans and (when `--remotes` is off) fire a redundant
+ // `for-each-ref refs/remotes/`. The primer still runs in
+ // parallel with downstream scope work (fsmonitor, etc.); it
+ // just gates on its data dependency.
+ //
+ // Scope to branches that will actually render an
+ // `UpstreamTask` row: with `--branches` that's every local;
+ // without it that's just the worktree-attached subset.
+ // Otherwise plain `wt list` on a repo with many stale
+ // tracking branches would block the worker pool on a serial
+ // batch for rows nobody sees.
+ if let Some(snap_arc) = snap.as_ref() {
+ let snap_for_primer = std::sync::Arc::clone(snap_arc);
+ s.spawn(move |_| {
+ // Honor `list.task-timeout-ms` for the primer's git
+ // commands — these are the same `for-each-ref
+ // %(ahead-behind)` / `rev-list` invocations that
+ // used to run inside `UpstreamTask`, where the
+ // worker loop sets the per-thread timeout. Without
+ // this, `wt list` could sit at the skeleton on a
+ // pathologically slow git until the (untimed) batch
+ // returned.
+ worktrunk::shell_exec::set_command_timeout(command_timeout);
+ let all_locals = snap_for_primer.local_branches();
+ let filtered_locals: Vec<LocalBranch>;
+ let candidates: &[LocalBranch] = if show_branches {
+ all_locals
+ } else {
+ filtered_locals = all_locals
+ .iter()
+ .filter(|b| worktree_branches.contains(b.name.as_str()))
+ .cloned()
+ .collect();
+ &filtered_locals
+ };
+ repo.prime_upstream_ahead_behind_cache(
+ candidates,
+ snap_for_primer.remote_branches(),
+ );
+ });
+ }
+
let _ = snapshot_cell.set(snap);
});
@@ -1158,10 +1216,7 @@ pub fn collect(
// Extract results from cells
let previous_branch = previous_branch_cell.into_inner().flatten();
- let snapshot = snapshot_cell
- .into_inner()
- .flatten()
- .map(std::sync::Arc::new);
+ let snapshot = snapshot_cell.into_inner().flatten();
// Resolve integration targets from the snapshot. Same OR semantics
// as `Repository::integration_reason` (`primary` + optional
diff --git a/src/commands/list/collect/tasks.rs b/src/commands/list/collect/tasks.rs
index 4acaa1566..5ad3e2934 100644
--- a/src/commands/list/collect/tasks.rs
+++ b/src/commands/list/collect/tasks.rs
@@ -813,15 +813,14 @@ impl Task for UpstreamTask {
// 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`.
+ // SHA-keyed), so warm runs are pure reads. Cold runs are also
+ // primed up front: `Repository::prime_upstream_ahead_behind_cache`
+ // runs in the same post-skeleton `rayon::scope` as the snapshot
+ // capture and pre-fills the cache via one `for-each-ref
+ // %(ahead-behind:UPSTREAM_SHA)` walk per unique upstream — same
+ // shared-graph-traversal win that `capture_ahead_behind` uses for
+ // the `main↕` column. This per-row call then falls through to a
+ // cache read.
let upstream_sha = ctx
.resolve_sha(&upstream_branch)
.map_err(|e| ctx.error(Self::KIND, &e))?;
diff --git a/src/git/repository/ref_snapshot.rs b/src/git/repository/ref_snapshot.rs
index ada9a9f17..9c5b1ed3c 100644
--- a/src/git/repository/ref_snapshot.rs
+++ b/src/git/repository/ref_snapshot.rs
@@ -292,6 +292,154 @@ impl Repository {
/// shared base-history traversal amortizes across the cold subset.
const AHEAD_BEHIND_SCOPED_BATCH_MIN_MISSES: usize = 8;
+impl Repository {
+ /// Prime the persistent `ahead-behind/` SHA-cache for the `Remote⇅`
+ /// column of `wt list`. Pairs each local branch with its configured
+ /// upstream and, for the ones the cache doesn't already cover, runs
+ /// one `for-each-ref %(ahead-behind:UPSTREAM_SHA)` walk per unique
+ /// upstream SHA — the same shared-graph-traversal win that
+ /// [`Self::capture_refs_with_ahead_behind`] uses for the `main↕`
+ /// column, scoped to branches sharing one base.
+ ///
+ /// Mirrors the cache-correctness defenses applied in
+ /// [`Self::capture_refs_with_ahead_behind`]:
+ /// `%(ahead-behind:UPSTREAM_SHA)` (not `:UPSTREAM_REFNAME`) so git
+ /// counts against the SHA the cache will be keyed by — a tag
+ /// shadowing the remote-tracking branch can't poison the entry; the
+ /// cache key uses the `%(objectname)` git reports for the branch in
+ /// the same walk, so a branch ref that moved between the initial
+ /// scan and the batch can't poison the entry either; writes flow
+ /// through `sha_cache::put_ahead_behind_bulk` for one `sweep_lru` at
+ /// the end; orphan branches (no common ancestor with their upstream)
+ /// are normalized to `(0, 0)` to match a cache miss in
+ /// [`Self::ahead_behind_by_sha`]. Each unique upstream's
+ /// `rev-list --count` is memoized in a local map so the orphan check
+ /// pays one count per upstream, not one per branch.
+ ///
+ /// Branches without an upstream, or with a `[gone]` upstream
+ /// ([`LocalBranch::upstream_short`] is `None` for both cases — see
+ /// `parse_local_branch_line`), are skipped: nothing to cache. Each
+ /// per-upstream group below the same threshold
+ /// `capture_ahead_behind` uses for the cold-subset batch is also
+ /// skipped — the per-row `UpstreamTask` will recompute those by SHA
+ /// in the parallel pool, which beats blocking the pool on a small
+ /// serial batch. Unlike [`Self::capture_refs_with_ahead_behind`]
+ /// there is no "all cold → unscoped walk" shortcut: each upstream
+ /// group's refs are already the maximal set of branches that track
+ /// it.
+ ///
+ /// Known limitation — distinct-upstream branches:
+ /// when every branch tracks its own remote (each upstream SHA is
+ /// unique), every group has `refs.len() == 1` and the primer skips
+ /// all of them. Those branches fall through to the per-row
+ /// `ahead_behind_by_sha` path in the parallel pool. A `%(upstream:track)`
+ /// walk could batch them in one shot, but git computes that atom
+ /// against the upstream's CURRENT value at walk time, which we
+ /// cannot pin to the SHA the cache will be keyed by — the resulting
+ /// race breaks the cache invariant `compute_ahead_behind` would
+ /// have established on a miss. Live with this until we either (a)
+ /// fan per-group batches out in parallel (turns N size-1 groups
+ /// into one batch wall-time) or (b) find an atom that reports
+ /// ahead/behind against an explicitly supplied per-branch SHA.
+ ///
+ /// Returns the number of cache entries written. Side-effect only;
+ /// no value is threaded through to callers — per-row
+ /// `ahead_behind_by_sha` lookups read the cache.
+ pub fn prime_upstream_ahead_behind_cache(
+ &self,
+ locals: &[LocalBranch],
+ remotes: &[RemoteBranch],
+ ) -> usize {
+ let full_ref = |b: &LocalBranch| format!("refs/heads/{}", b.name);
+
+ // (branch_refname, branch_sha, upstream_sha) for branches with a
+ // resolvable upstream. Skip no-upstream and `[gone]` branches:
+ // `parse_local_branch_line` collapses both into
+ // `upstream_short == None`.
+ let mut candidates: Vec<(String, String, String)> = Vec::new();
+ for b in locals {
+ let Some(upstream_short) = b.upstream_short.as_deref() else {
+ continue;
+ };
+ // `%(upstream:short)` looks like `origin/feature` for a
+ // remote-tracking upstream and like `main` (just the branch
+ // name) when `branch.<x>.remote = .` configures a local
+ // branch as upstream. `resolve_sha_from_scan` checks locals
+ // before remotes on a bare name, covering both cases without
+ // a prefix-prepending step that would mask the local form.
+ let Some(upstream_sha) = resolve_sha_from_scan(upstream_short, locals, remotes) else {
+ continue;
+ };
+ candidates.push((full_ref(b), b.commit_sha.clone(), upstream_sha.to_string()));
+ }
+ if candidates.is_empty() {
+ return 0;
+ }
+
+ // Partition cold vs warm by probing the SHA cache. Warm pairs
+ // need no work — the per-row `UpstreamTask` reads them in
+ // parallel via `ahead_behind_by_sha`.
+ let mut cold_by_upstream: HashMap<String, Vec<String>> = HashMap::new();
+ for (branch_ref, branch_sha, upstream_sha) in &candidates {
+ if super::sha_cache::ahead_behind(self, upstream_sha, branch_sha).is_some() {
+ continue;
+ }
+ cold_by_upstream
+ .entry(upstream_sha.clone())
+ .or_default()
+ .push(branch_ref.clone());
+ }
+ if cold_by_upstream.is_empty() {
+ return 0;
+ }
+
+ // One serial `for-each-ref %(ahead-behind:UPSTREAM_SHA)` per
+ // upstream group, only above the same threshold
+ // `capture_ahead_behind` uses — small groups go through the
+ // parallel per-row path instead. `base_totals` memoizes
+ // `rev-list --count` per upstream so the orphan check is one
+ // count per upstream, not one per branch.
+ let mut writes: Vec<(String, String, (usize, usize))> = Vec::new();
+ let mut base_totals: HashMap<String, Option<usize>> = HashMap::new();
+ for (upstream_sha, refs) in &cold_by_upstream {
+ if refs.len() < AHEAD_BEHIND_SCOPED_BATCH_MIN_MISSES {
+ continue;
+ }
+ let fresh = scan_ahead_behind(self, upstream_sha, Some(refs));
+ if fresh.is_empty() {
+ continue; // git < 2.36 or batch failed
+ }
+ let base_total = *base_totals.entry(upstream_sha.clone()).or_insert_with(|| {
+ self.run_command(&["rev-list", "--count", upstream_sha])
+ .ok()
+ .and_then(|s| s.trim().parse().ok())
+ });
+ for branch_ref in refs {
+ let Some((object_sha, (ahead, behind))) = fresh.get(branch_ref) else {
+ continue;
+ };
+ // Orphan against this upstream: git's `%(ahead-behind)`
+ // reports the two disjoint history sizes; a cache miss
+ // (which calls `compute_ahead_behind`) returns `(0, 0)`.
+ // Detect via `behind == |upstream|`.
+ let counts = if base_total == Some(*behind) {
+ (0, 0)
+ } else {
+ (*ahead, *behind)
+ };
+ writes.push((upstream_sha.clone(), object_sha.clone(), counts));
+ }
+ }
+
+ let n = writes.len();
+ super::sha_cache::put_ahead_behind_bulk(
+ self,
+ writes.iter().map(|(u, b, c)| (u.as_str(), b.as_str(), *c)),
+ );
+ n
+ }
+}
+
/// 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>(
@@ -808,4 +956,364 @@ mod tests {
// today's Branch::upstream.
// (This test mainly checks the method exists and doesn't panic.)
}
+
+ // Set up a local branch that tracks `origin/<upstream_basename>`. Uses
+ // the bare config-file path so tests stay self-contained: no real
+ // remote, just enough refs and config for git's `%(upstream:short)` to
+ // resolve.
+ fn track(test: &TestRepo, branch: &str, upstream_basename: &str) {
+ test.run_git(&["config", &format!("branch.{branch}.remote"), "origin"]);
+ test.run_git(&[
+ "config",
+ &format!("branch.{branch}.merge"),
+ &format!("refs/heads/{upstream_basename}"),
+ ]);
+ }
+
+ fn ahead_behind_cache_path(repo: &Repository, base_sha: &str, head_sha: &str) -> PathBuf {
+ crate::cache::cache_dir(repo, "ahead-behind").join(format!("{base_sha}-{head_sha}.json"))
+ }
+
+ use std::path::PathBuf;
+
+ #[test]
+ fn prime_upstream_writes_cache_on_cold_run() {
+ // 10 branches all tracking origin/trunk → above
+ // AHEAD_BEHIND_SCOPED_BATCH_MIN_MISSES, single-group scoped batch.
+ let test = TestRepo::with_initial_commit();
+ let trunk_sha = test.git_output(&["rev-parse", "main"]);
+ test.run_git(&["update-ref", "refs/remotes/origin/trunk", &trunk_sha]);
+ for i in 0..10 {
+ test.run_git(&["checkout", "-b", &format!("feat{i}"), "main"]);
+ test.run_git(&["commit", "--allow-empty", "-m", &format!("c{i}")]);
+ track(&test, &format!("feat{i}"), "trunk");
+ }
+ test.run_git(&["checkout", "main"]);
+
+ let repo = Repository::at(test.root_path()).unwrap();
+ let locals = repo.local_branches().unwrap().to_vec();
+ let remotes = repo.remote_branches().unwrap().to_vec();
+ let written = repo.prime_upstream_ahead_behind_cache(&locals, &remotes);
+
+ // Skip on git < 2.36 where the batch silently yields nothing.
+ if written == 0 {
+ return;
+ }
+ assert_eq!(written, 10, "one cache entry per tracking branch");
+
+ // Each (trunk_sha, feat{i}_sha) pair lives on disk and reflects the
+ // real (1, 0) — `ahead_behind_by_sha` would compute the same.
+ for i in 0..10 {
+ let feat_sha = test.git_output(&["rev-parse", &format!("feat{i}")]);
+ assert_eq!(
+ repo.ahead_behind_by_sha(&trunk_sha, &feat_sha).unwrap(),
+ (1, 0),
+ "feat{i} is 1 ahead, 0 behind origin/trunk"
+ );
+ assert!(
+ ahead_behind_cache_path(&repo, &trunk_sha, &feat_sha).exists(),
+ "cache entry must exist for (trunk, feat{i})"
+ );
+ }
+ }
+
+ #[test]
+ fn prime_upstream_warm_cache_skips_walk() {
+ // Same setup as the cold test, but on the second call every entry
+ // is cached → primer writes nothing (and tampering with the cache
+ // survives — proving we didn't re-run the batch).
+ let test = TestRepo::with_initial_commit();
+ let trunk_sha = test.git_output(&["rev-parse", "main"]);
+ test.run_git(&["update-ref", "refs/remotes/origin/trunk", &trunk_sha]);
+ for i in 0..10 {
+ test.run_git(&["checkout", "-b", &format!("feat{i}"), "main"]);
+ test.run_git(&["commit", "--allow-empty", "-m", &format!("c{i}")]);
+ track(&test, &format!("feat{i}"), "trunk");
+ }
+ test.run_git(&["checkout", "main"]);
+
+ let repo = Repository::at(test.root_path()).unwrap();
+ let locals: Vec<_> = repo.local_branches().unwrap().to_vec();
+ let remotes: Vec<_> = repo.remote_branches().unwrap().to_vec();
+ let written = repo.prime_upstream_ahead_behind_cache(&locals, &remotes);
+ if written == 0 {
+ return; // git < 2.36
+ }
+
+ // Tamper with one entry; a second prime that re-ran the batch
+ // would overwrite it.
+ let feat0_sha = test.git_output(&["rev-parse", "feat0"]);
+ let tampered = ahead_behind_cache_path(&repo, &trunk_sha, &feat0_sha);
+ std::fs::write(&tampered, "[7,3]").unwrap();
+
+ let repo2 = Repository::at(test.root_path()).unwrap();
+ let locals2 = repo2.local_branches().unwrap().to_vec();
+ let remotes2 = repo2.remote_branches().unwrap().to_vec();
+ let second_written = repo2.prime_upstream_ahead_behind_cache(&locals2, &remotes2);
+ assert_eq!(
+ second_written, 0,
+ "everything cached → no batch and no writes"
+ );
+ assert_eq!(
+ std::fs::read_to_string(&tampered).unwrap(),
+ "[7,3]",
+ "warm-cache run must not overwrite the tampered value"
+ );
+ }
+
+ #[test]
+ fn prime_upstream_below_threshold_leaves_cache_cold() {
+ // Only 1 branch tracks origin/trunk → below
+ // AHEAD_BEHIND_SCOPED_BATCH_MIN_MISSES; primer leaves it for the
+ // per-row task's parallel `ahead_behind_by_sha`.
+ let test = TestRepo::with_initial_commit();
+ 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", "feat", "main"]);
+ test.run_git(&["commit", "--allow-empty", "-m", "c"]);
+ track(&test, "feat", "trunk");
+ test.run_git(&["checkout", "main"]);
+
+ let repo = Repository::at(test.root_path()).unwrap();
+ let locals = repo.local_branches().unwrap().to_vec();
+ let remotes = repo.remote_branches().unwrap().to_vec();
+ let written = repo.prime_upstream_ahead_behind_cache(&locals, &remotes);
+ assert_eq!(written, 0, "below threshold → no batch, no writes");
+
+ let feat_sha = test.git_output(&["rev-parse", "feat"]);
+ assert!(
+ !ahead_behind_cache_path(&repo, &trunk_sha, &feat_sha).exists(),
+ "primer must not seed below-threshold groups"
+ );
+ }
+
+ #[test]
+ fn prime_upstream_skips_no_upstream_branches() {
+ // 10 branches without any upstream config → nothing to cache.
+ let test = TestRepo::with_initial_commit();
+ 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"]);
+
+ let repo = Repository::at(test.root_path()).unwrap();
+ let locals = repo.local_branches().unwrap().to_vec();
+ let remotes = repo.remote_branches().unwrap().to_vec();
+ let written = repo.prime_upstream_ahead_behind_cache(&locals, &remotes);
+ assert_eq!(written, 0, "no upstream → no candidates → no writes");
+ assert!(
+ !crate::cache::cache_dir(&repo, "ahead-behind").exists()
+ || std::fs::read_dir(crate::cache::cache_dir(&repo, "ahead-behind"))
+ .unwrap()
+ .next()
+ .is_none(),
+ "ahead-behind cache dir must stay empty"
+ );
+ }
+
+ #[test]
+ fn prime_upstream_skips_gone_upstream() {
+ // Branches with `branch.X.remote/merge` set but the corresponding
+ // `refs/remotes/origin/<basename>` missing → `[gone]` track state →
+ // `parse_local_branch_line` collapses to `upstream_short = None`,
+ // so the primer skips them too.
+ let test = TestRepo::with_initial_commit();
+ for i in 0..10 {
+ test.run_git(&["checkout", "-b", &format!("gone{i}"), "main"]);
+ test.run_git(&["commit", "--allow-empty", "-m", &format!("c{i}")]);
+ track(&test, &format!("gone{i}"), "this-is-deleted-elsewhere");
+ }
+ test.run_git(&["checkout", "main"]);
+
+ let repo = Repository::at(test.root_path()).unwrap();
+ let locals = repo.local_branches().unwrap().to_vec();
+ let remotes = repo.remote_branches().unwrap().to_vec();
+ let written = repo.prime_upstream_ahead_behind_cache(&locals, &remotes);
+ assert_eq!(
+ written, 0,
+ "[gone] upstream → upstream_short = None → no candidates"
+ );
+ }
+
+ #[test]
+ fn prime_upstream_normalizes_orphan_to_zero() {
+ // 9 normal tracking branches plus one orphan branch that also
+ // tracks origin/trunk. The orphan's `%(ahead-behind)` reports the
+ // two disjoint history sizes; the primer must store `(0, 0)` to
+ // match `compute_ahead_behind` / a cache miss.
+ let test = TestRepo::with_initial_commit();
+ // Advance main a few commits so origin/trunk has a non-trivial
+ // total — this is what the orphan check compares against.
+ for i in 0..3 {
+ test.run_git(&["commit", "--allow-empty", "-m", &format!("m{i}")]);
+ }
+ let trunk_sha = test.git_output(&["rev-parse", "main"]);
+ test.run_git(&["update-ref", "refs/remotes/origin/trunk", &trunk_sha]);
+
+ for i in 0..9 {
+ test.run_git(&["checkout", "-b", &format!("feat{i}"), "main"]);
+ test.run_git(&["commit", "--allow-empty", "-m", &format!("c{i}")]);
+ track(&test, &format!("feat{i}"), "trunk");
+ }
+
+ // Orphan branch — 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"]);
+ track(&test, "orphanbr", "trunk");
+ test.run_git(&["checkout", "main"]);
+
+ let repo = Repository::at(test.root_path()).unwrap();
+ let locals = repo.local_branches().unwrap().to_vec();
+ let remotes = repo.remote_branches().unwrap().to_vec();
+ let written = repo.prime_upstream_ahead_behind_cache(&locals, &remotes);
+ if written == 0 {
+ return; // git < 2.36
+ }
+
+ let orphan_sha = test.git_output(&["rev-parse", "orphanbr"]);
+ let cached: (usize, usize) = serde_json::from_str(
+ &std::fs::read_to_string(ahead_behind_cache_path(&repo, &trunk_sha, &orphan_sha))
+ .expect("orphan pair should be cached"),
+ )
+ .expect("cache entry is a (usize, usize)");
+ assert_eq!(
+ cached,
+ (0, 0),
+ "orphan-vs-upstream must normalize to compute_ahead_behind's (0, 0)"
+ );
+ // Sanity-check parity with the per-pair API.
+ assert_eq!(
+ repo.ahead_behind_by_sha(&trunk_sha, &orphan_sha).unwrap(),
+ (0, 0)
+ );
+ }
+
+ #[test]
+ fn prime_upstream_groups_by_unique_upstream_sha() {
+ // Two upstream groups, both above threshold. Each group runs its
+ // own scoped `for-each-ref` walk; entries land under separate
+ // base-SHA keys.
+ let test = TestRepo::with_initial_commit();
+ let main_sha = test.git_output(&["rev-parse", "main"]);
+ test.run_git(&["update-ref", "refs/remotes/origin/trunkA", &main_sha]);
+ // Advance main, then point trunkB at the new tip — distinct SHA.
+ test.run_git(&["commit", "--allow-empty", "-m", "advance-main"]);
+ let main_sha2 = test.git_output(&["rev-parse", "main"]);
+ assert_ne!(main_sha, main_sha2);
+ test.run_git(&["update-ref", "refs/remotes/origin/trunkB", &main_sha2]);
+
+ for i in 0..8 {
+ test.run_git(&["checkout", "-b", &format!("a{i}"), "main"]);
+ test.run_git(&["commit", "--allow-empty", "-m", &format!("a{i}")]);
+ track(&test, &format!("a{i}"), "trunkA");
+ }
+ for i in 0..8 {
+ test.run_git(&["checkout", "-b", &format!("b{i}"), "main"]);
+ test.run_git(&["commit", "--allow-empty", "-m", &format!("b{i}")]);
+ track(&test, &format!("b{i}"), "trunkB");
+ }
+ test.run_git(&["checkout", "main"]);
+
+ let repo = Repository::at(test.root_path()).unwrap();
+ let locals = repo.local_branches().unwrap().to_vec();
+ let remotes = repo.remote_branches().unwrap().to_vec();
+ let written = repo.prime_upstream_ahead_behind_cache(&locals, &remotes);
+ if written == 0 {
+ return; // git < 2.36
+ }
+ assert_eq!(written, 16, "8 entries per upstream group, two groups");
+
+ for i in 0..8 {
+ let a_sha = test.git_output(&["rev-parse", &format!("a{i}")]);
+ assert!(
+ ahead_behind_cache_path(&repo, &main_sha, &a_sha).exists(),
+ "a{i} entry keyed by trunkA (main_sha)"
+ );
+ let b_sha = test.git_output(&["rev-parse", &format!("b{i}")]);
+ assert!(
+ ahead_behind_cache_path(&repo, &main_sha2, &b_sha).exists(),
+ "b{i} entry keyed by trunkB (main_sha2)"
+ );
+ }
+ }
+
+ #[test]
+ fn prime_upstream_resolves_local_upstream() {
+ // `branch.X.remote = .` makes another LOCAL branch the upstream;
+ // `%(upstream:short)` is then just the branch name (e.g., `main`)
+ // with no `origin/` prefix. The primer must still find its SHA
+ // via the local-branch inventory and seed the cache; otherwise a
+ // documented fallback silently does nothing.
+ let test = TestRepo::with_initial_commit();
+ let main_sha = test.git_output(&["rev-parse", "main"]);
+ for i in 0..10 {
+ test.run_git(&["checkout", "-b", &format!("feat{i}"), "main"]);
+ test.run_git(&["commit", "--allow-empty", "-m", &format!("c{i}")]);
+ // `.` means "this repo": the upstream is the local branch
+ // matched by `branch.<x>.merge`.
+ test.run_git(&["config", &format!("branch.feat{i}.remote"), "."]);
+ test.run_git(&[
+ "config",
+ &format!("branch.feat{i}.merge"),
+ "refs/heads/main",
+ ]);
+ }
+ test.run_git(&["checkout", "main"]);
+
+ let repo = Repository::at(test.root_path()).unwrap();
+ let locals = repo.local_branches().unwrap().to_vec();
+ let remotes = repo.remote_branches().unwrap().to_vec();
+ let written = repo.prime_upstream_ahead_behind_cache(&locals, &remotes);
+ if written == 0 {
+ return; // git < 2.36
+ }
+ assert_eq!(written, 10, "local-upstream branches must be cached too");
+
+ for i in 0..10 {
+ let feat_sha = test.git_output(&["rev-parse", &format!("feat{i}")]);
+ assert!(
+ ahead_behind_cache_path(&repo, &main_sha, &feat_sha).exists(),
+ "feat{i} keyed against main_sha (local upstream)"
+ );
+ }
+ }
+
+ #[test]
+ fn prime_upstream_caches_equal_branch_as_zero() {
+ // Branch whose tip equals its upstream → (0, 0). The cache key
+ // uses the same SHA for both base and head (a-a.json), and a
+ // later `ahead_behind_by_sha` of the equal pair must hit it.
+ let test = TestRepo::with_initial_commit();
+ let trunk_sha = test.git_output(&["rev-parse", "main"]);
+ test.run_git(&["update-ref", "refs/remotes/origin/trunk", &trunk_sha]);
+ for i in 0..10 {
+ // Each branch is created from main and stays equal to it.
+ test.run_git(&["branch", &format!("eq{i}"), "main"]);
+ track(&test, &format!("eq{i}"), "trunk");
+ }
+
+ let repo = Repository::at(test.root_path()).unwrap();
+ let locals = repo.local_branches().unwrap().to_vec();
+ let remotes = repo.remote_branches().unwrap().to_vec();
+ let written = repo.prime_upstream_ahead_behind_cache(&locals, &remotes);
+ if written == 0 {
+ return; // git < 2.36
+ }
+ // 10 equal-to-trunk branches plus main itself (if main has an
+ // upstream, but we didn't track it here) — assert at least the 10.
+ assert!(
+ written >= 10,
+ "all 10 equal branches must be cached (got {written})"
+ );
+ let cache_path = ahead_behind_cache_path(&repo, &trunk_sha, &trunk_sha);
+ assert_eq!(
+ std::fs::read_to_string(&cache_path).unwrap(),
+ "[0,0]",
+ "equal branch must cache as (0, 0) — same SHA on both sides"
+ );
+ }
}