galaxy/specs/GH10090/tech.md

Watch remote refs for updates — Tech Spec

Product spec: specs/GH10090/product.md GitHub issue: https://github.com/warpdotdev/warp/issues/10090

Problem

repo_metadata already watches repository roots and selected Git internals, but remote-tracking refs under .git/refs/remotes/* are filtered out. Code review metadata computes unpushed commits from the current branch's upstream ref, so a push or fetch that updates a loose remote-tracking ref can leave DiffStateModel and the Git operations UI stale until another invalidation happens.

The implementation needs to allow loose remote-ref watcher events through, keep each watched Repository aware of the loose remote ref tracked by its active branch, refresh that cached tracking state when HEAD or Git config changes can alter it, and expose remote-ref invalidations explicitly on RepositoryUpdate.

Relevant code

• crates/repo_metadata/src/entry.rs (361-484) — Git internal path helpers: git_suffix_components, extract_worktree_git_dir, is_shared_git_ref, is_commit_related_git_file, is_index_lock_file, and should_ignore_git_path.
• crates/repo_metadata/src/entry_test.rs (222-395) — current allowlist and shared-ref tests; remote refs and .git/config are currently asserted as ignored.
• crates/repo_metadata/src/watcher.rs (120-194) — DirectoryWatcher::find_repos_for_git_event, which routes worktree-specific, shared local branch ref, and repo-specific Git events.
• crates/repo_metadata/src/watcher.rs (293-335) — start_watching_directory, which registers watched paths with the should_ignore_git_path filter.
• crates/repo_metadata/src/watcher.rs (391-529) — filesystem event handling that converts Git internal events into RepositoryUpdate.
• crates/repo_metadata/src/watcher.rs (588-626) — RepositoryUpdate, especially commit_updated and index_lock_detected.
• crates/repo_metadata/src/repository.rs (54-151) — Repository stores root_dir, optional per-worktree external_git_directory, and optional shared common_git_directory.
• crates/repo_metadata/src/repository.rs (162-229) — Repository::start_watching, which registers the worktree root, per-worktree gitdir, and shared refs/heads for linked worktrees.
• app/src/code_review/diff_state.rs (1116-1247) — code review repository subscriber maps repository updates to metadata invalidation and throttled metadata refresh.
• app/src/code_review/diff_state.rs (1347-1393) — load_metadata_for_repo reads @{u} and recomputes unpushed_commits.
• app/src/code_review/git_status_update.rs (168-283) — Git status metadata watcher refreshes when repository metadata flags indicate Git state changed.
• app/src/util/git.rs (391-468) — get_unpushed_commits computes <upstream>..HEAD.

Current state

should_ignore_git_path uses an allowlist for .git internals. Only commit-related files (HEAD and refs/heads/*) and index.lock are allowed through; .git/refs/remotes/origin/main and .git/config are explicitly ignored in entry_test.rs.

For normal repositories, the repository root watcher is recursive, so .git/refs/remotes/*, .git/config, and .git/HEAD would be observable if the filter allowed them. For linked worktrees, remote refs and shared config are stored in the shared common .git directory, outside the worktree checkout and outside the per-worktree gitdir. Repository::start_watching currently adds common_git_dir/refs/heads for shared local branch refs, but it does not add common_git_dir/refs/remotes or common Git config.

Once a Git internal path reaches DirectoryWatcher::handle_watcher_event, it is classified with is_commit_related_git_file or is_index_lock_file. A commit_updated update is enough to trigger the existing code review and git-status metadata refresh paths, but it does not distinguish a local commit/branch update from an upstream remote-ref update. The missing pieces are path classification, cached tracked-upstream state on Repository, watcher registration for linked worktrees, scope-aware routing to repositories tracking the changed remote ref, and an explicit RepositoryUpdate field for remote-ref changes.

Proposed changes

1. Add remote-tracking ref and tracking-config path helpers

Extend crates/repo_metadata/src/entry.rs with helpers for loose remote-tracking refs and Git files that can change a repository's tracked remote ref:

• is_remote_tracking_ref(path: &Path) -> bool
  • true for paths under .git/refs/remotes/<remote>/<branch...>.
  • false for paths under .git/worktrees/<name>/..., .git/refs/heads/*, .git/refs/tags/*, .git/packed-refs, and non-Git paths.
  • requires at least a remote component and one branch component after refs/remotes.
• remote_tracking_ref_path_under_common_git_dir(path: &Path) -> Option<PathBuf>
  • canonicalization-friendly helper for routing. It returns the full loose ref path only for shared remote refs, not worktree-local files.
• is_tracking_state_git_file(path: &Path) -> bool
  • true for files that can change the active branch's tracked remote ref: repository-specific HEAD, common .git/config, and per-worktree config.worktree when present.
  • false for local branch ref files, tags, packed-refs, objects, logs, and hooks.

Update should_ignore_git_path so loose remote-tracking refs and tracking-state files are allowlisted. Keep packed-refs ignored. Do not add broad refs/* matching; tags and other Git internals remain filtered out.

Keep is_commit_related_git_file focused on .git/HEAD and .git/refs/heads/*. Remote refs should not be folded into that helper because RepositoryUpdate will expose them separately.

2. Store the tracked remote ref on Repository

Add a cached tracked-upstream field to crates/repo_metadata/src/repository.rs:

• tracked_remote_ref: Option<TrackedRemoteRef>

Add a small internal type:

• TrackedRemoteRef
  • full_ref_name: String

full_ref_name should be the symbolic full upstream ref returned by Git, for example refs/remotes/origin/feature. Store the ref name rather than remote/branch components so Git owns branch config parsing, quoted branch names, worktree config, includes, and other config edge cases.

Repository should initialize this field in Repository::new or during the first watcher registration, and expose narrow helpers:

• pub(crate) fn tracked_remote_ref(&self) -> Option<&TrackedRemoteRef>
• pub(crate) fn tracks_remote_ref_path(&self, remote_ref_path: &Path) -> bool
• pub(crate) fn refresh_tracked_remote_ref(&mut self) -> bool
• pub(crate) fn tracked_remote_ref_path(&self) -> Option<PathBuf>

refresh_tracked_remote_ref should run Git in the repository worktree context and update the cached value:

1. Run git -C <repo_root> rev-parse --symbolic-full-name @{u}.
2. If Git exits non-zero, cache None. This covers detached HEAD, no upstream, malformed config, unreadable config, and racing branch changes.
3. Trim stdout to one line.
4. If the ref name does not start with refs/remotes/, cache None. This excludes local upstreams such as remote = . that resolve to refs/heads/<branch>.
5. Validate the ref name is relative and does not contain path traversal components.
6. Cache TrackedRemoteRef { full_ref_name }.

Implementation details:

• Prefer using an existing Git command helper in the app/repo metadata layer if one is available; otherwise add a narrow helper dedicated to resolving the current upstream ref.
• Do not run Git for every remote-ref event. Run it only on repository construction/startup and allowlisted tracking-state events (HEAD, common .git/config, and optional config.worktree). Remote-ref routing should use the cached value.
• Use the existing repository task queue for Git-backed upstream refreshes so filesystem watcher routing does not block on process execution. Add a task such as Task::RefreshTrackedRemoteRef { repository: WeakModelHandle<Repository> }. The task should run the Git command off the watcher event path, then update the repository cache on completion. If the cached value changed, enqueue RepositoryUpdate { remote_ref_updated: true, ..Default::default() } for that repository's subscribers. Do not broaden remote-ref routing to every repository as a shortcut.
• tracked_remote_ref_path should compute self.common_git_dir().join(full_ref_name) from the cached TrackedRemoteRef; do not store the path separately as duplicate state.
• tracks_remote_ref_path should compare the changed path to the computed tracked remote ref path, normalizing/canonicalizing existing parent paths where possible.

This cached field is the scope boundary that satisfies the product requirement that only repositories tracking the changed remote ref refresh metadata.

3. Refresh cached tracking state when it can change

The tracked remote ref for a watched repository can change when any of these local files change:

• self.git_dir()/HEAD: the active branch changes, HEAD becomes detached, or HEAD is reattached to a branch with a different upstream.
• self.common_git_dir()/config: branch upstream config changes, including git branch --set-upstream-to, git branch --unset-upstream, git push -u, git remote rename, and manual edits to branch.<name>.remote or branch.<name>.merge.
• self.git_dir()/config.worktree: worktree-specific upstream config changes, if worktree-specific config is enabled and this repo supports reading it.

Update watcher handling so events for is_tracking_state_git_file(path) enqueue a tracked-remote-ref refresh task for each affected repository instead of running Git inline. When the queued task completes, it should compare the resolved upstream ref to the cached value. If refresh_tracked_remote_ref changed the cache, enqueue RepositoryUpdate { remote_ref_updated: true, ..Default::default() } for that repository.

Routing for tracking-state files should be scoped by where the file lives:

1. Worktree-specific HEAD and config.worktree under .git/worktrees/<name>/... route only to that linked worktree.
2. Normal repo .git/HEAD routes only to the repository whose working tree owns that .git directory.
3. Common .git/config routes to all watched repositories whose common_git_dir() matches that .git directory, then each repository decides whether its cached tracked_remote_ref changed.

A common config edit may affect multiple watched worktrees if Git resolves a different upstream for their active branches. It may also affect none of them. The config event may enqueue refresh tasks for every watched repository sharing that common Git directory, but only repositories whose resolved upstream changed should receive remote_ref_updated. Do not broaden remote-ref refreshes to every watched worktree as a substitute for the per-repository cache check.

4. Register shared Git paths for linked worktrees

Update Repository::start_watching in crates/repo_metadata/src/repository.rs so linked worktrees watch shared Git paths from the common Git directory in a way that includes remote-tracking refs and shared config.

Preferred registration for linked worktrees:

• the worktree root, as today.
• the per-worktree gitdir, as today, for HEAD, index.lock, and optional config.worktree.
• common_git_dir/refs, when it exists, so shared local branch refs and remote-tracking refs are visible.
• common_git_dir/config, if the watcher can register a file path; otherwise common_git_dir with the existing allowlist filter.

This lets a linked worktree observe both existing remote refs and first-time creation under refs/remotes without having to create Git directories from Warp. It also lets upstream tracking additions/removals in common config update the cached tracked_remote_ref.

Update Repository::stop_watching to unregister the same shared paths when the last subscriber is removed. Keep start/stop symmetric, preferably by sharing a helper that computes the optional watch paths.

For normal repositories, no extra watch path is required because the root watcher already recursively covers .git/refs/remotes, .git/config, and .git/HEAD once the filter allows those paths.

5. Add remote-ref routing in DirectoryWatcher

Update DirectoryWatcher::find_repos_for_git_event in crates/repo_metadata/src/watcher.rs with a routing tier for shared remote-tracking refs:

1. Worktree-specific paths under .git/worktrees/<name>/... keep the existing highest-priority route.
2. Remote-tracking refs under .git/refs/remotes/* route to watched repositories whose common_git_dir() contains the event path and whose Repository::tracks_remote_ref_path(event_path) returns true based on the cached full upstream ref name.
3. Shared local branch refs under .git/refs/heads/* keep the existing broadcast-to-shared-common-git-dir route.
4. Common .git/config routes to all watched repositories sharing that common Git directory so each can refresh its cached tracked remote ref.
5. Repo-specific paths keep the existing fallback route.

The remote-ref tier should deduplicate repository handles just like the existing tiers. It should log the routing tier and affected repo count with the existing [GIT_EVENT_ROUTING] pattern.

Remote-ref filesystem events should produce RepositoryUpdate { remote_ref_updated: true, ... } synchronously after cached-path routing. Tracking-state events should not produce an immediate subscriber update; they enqueue Task::RefreshTrackedRemoteRef, and task completion produces remote_ref_updated = true only for repositories whose cached tracked_remote_ref changed. No Git internal path should be added to added, modified, deleted, or moved, matching the current treatment for local Git metadata files.

6. Add a queued tracked-ref refresh task

Extend TaskQueue in crates/repo_metadata/src/watcher.rs with a task dedicated to refreshing the cached upstream ref:

• Task::RefreshTrackedRemoteRef { repository: WeakModelHandle<Repository> }

The task should:

1. Upgrade the repository handle.
2. Run refresh_tracked_remote_ref for that repository, using Git to resolve @{u} outside the watcher event path.
3. If the cached value changed, collect the repository's current subscriber IDs and enqueue Task::Update with RepositoryUpdate { remote_ref_updated: true, ..Default::default() } for each subscriber.
4. If the repository was dropped, Git fails, or the resolved upstream is unchanged, complete without delivering a subscriber update unless the cache changed to or from None.

This preserves ordering enough for correctness: if git push -u updates both .git/config and a remote ref and the remote-ref event arrives before the cache refresh completes, that remote-ref event may not match the old cache. The queued config refresh still emits remote_ref_updated when the tracked upstream changes, so code review metadata refreshes without requiring broad remote-ref routing.

7. Add RepositoryUpdate.remote_ref_updated

Extend crates/repo_metadata/src/watcher.rs:

• pub remote_ref_updated: bool
  • true when the repository's tracked upstream state changed, or when the loose remote-tracking ref currently tracked by the repository changed.

Update all RepositoryUpdate plumbing:

• RepositoryUpdate::is_empty should include !self.remote_ref_updated.
• merge_repository_updates should OR remote_ref_updated, like commit_updated and index_lock_detected.
• Destructuring call sites, tests, and default builders should include the new field.
• Logs should distinguish commit_updated, remote_ref_updated, and index_lock_detected.

Keep commit_updated for local commit/branch state (HEAD and refs/heads/*). Use remote_ref_updated for upstream state so consumers can reason about refresh causes without conflating local and remote ref changes.

8. Preserve code review and git status behavior

Consumers should refresh metadata when either commit_updated or remote_ref_updated is true.

Existing flow after the watcher update:

1. Repository caches that the active branch tracks .git/refs/remotes/origin/feature.
2. Watcher sees .git/refs/remotes/origin/feature change.
3. find_repos_for_git_event routes only to repositories whose cached full upstream ref name computes to that tracked remote ref path.
4. handle_watcher_event enqueues RepositoryUpdate { remote_ref_updated: true, ... }.
5. DiffStateModel::handle_file_update treats remote_ref_updated like commit_updated for metadata invalidation and schedules the throttled metadata refresh.
6. load_metadata_for_repo re-reads @{u} and recomputes get_unpushed_commits.
7. CodeReviewView observes the updated metadata and recalculates the primary Git action.

Tracking-add/remove flow:

1. Git updates .git/config after git push -u, git branch --set-upstream-to, or git branch --unset-upstream.
2. The watcher routes the config event to repositories sharing that common Git directory.
3. Each repository calls refresh_tracked_remote_ref.
4. Repositories whose cached tracked remote ref changed receive RepositoryUpdate { remote_ref_updated: true, ... }.
5. Code review and Git status metadata refresh from the same path used for remote-ref content updates.

GitRepoStatusModel::should_refresh_metadata should also return true for remote_ref_updated, so branch/status metadata remains consistent.

9. Tests

Add and update unit tests in crates/repo_metadata:

• entry_test.rs
  • should_ignore_git_path does not ignore .git/refs/remotes/origin/main.
  • should_ignore_git_path does not ignore .git/config or .git/worktrees/<name>/config.worktree.
  • remote branch names with slashes are recognized.
  • .git/refs/remotes/origin without a branch is not recognized.
  • .git/packed-refs, .git/refs/tags/*, .git/refs/heads/*, and worktree-local paths are not remote-tracking refs.
  • existing local branch and index-lock assertions remain unchanged.
• repository.rs tests or a new repository_tests.rs
  • tracked_remote_ref initializes from a mocked or fixture-backed git rev-parse --symbolic-full-name @{u} result such as refs/remotes/origin/feature.
  • tracked_remote_ref_path computes common_git_dir/refs/remotes/origin/feature from cached full ref name state.
  • tracks_remote_ref_path returns true for the computed loose remote ref path.
  • slash-containing branch names are preserved in the full ref name returned by Git.
  • refresh_tracked_remote_ref returns true when Git reports tracking was added, removed, or changed to a different upstream ref, and false when the resolved upstream ref is unchanged.
  • returns/caches None for detached HEAD, no upstream, Git command failure, local upstreams such as refs/heads/main, malformed output, absolute paths, and path traversal components.
  • runs Git in the worktree root so linked worktrees resolve their own active branch and worktree-specific config correctly.
• watcher_tests.rs
  • a matching remote-ref event is delivered to a subscriber as remote_ref_updated = true, commit_updated = false, and contains no file-list changes.
  • an unrelated remote-ref event is not delivered to a repository that tracks a different upstream.
  • two repositories/worktrees tracking the same remote ref both receive the update.
  • a .git/config change that adds, removes, or changes the active branch upstream enqueues Task::RefreshTrackedRemoteRef, and task completion emits remote_ref_updated = true.
  • a .git/config change unrelated to the active branch may enqueue Task::RefreshTrackedRemoteRef, but task completion does not emit remote_ref_updated when the resolved upstream is unchanged.
  • linked worktrees register/unregister shared refs and shared config in a way that covers refs/remotes, including first-time creation under refs/remotes when the common refs directory exists.
  • local refs/heads/*, worktree-specific HEAD, and index.lock routing continue to pass existing regression tests.

Update app-level tests only if repo-metadata tests cannot prove the end-to-end invalidation contract. The key app-level assertion is that DiffStateModel::handle_file_update treats remote_ref_updated as full metadata invalidation, matching commit_updated.

10. Manual validation

1. Open Warp code review on a branch tracking origin/<branch> with one or more unpushed commits.
2. Push the branch from Warp or an external terminal.
3. Confirm the loose ref .git/refs/remotes/origin/<branch> updates.
4. Confirm the unpushed commit list clears and the primary Git action updates without reopening code review.
5. Run git branch --unset-upstream, then git branch --set-upstream-to=origin/<branch>, and confirm metadata refreshes when tracked remote ref state is removed and restored.
6. Repeat with another branch's remote ref update and confirm the active branch does not refresh.
7. Repeat in a linked worktree whose common .git directory is outside the worktree checkout.

Risks and mitigations

Risk: over-invalidating every worktree sharing a common .git

Shared refs and shared config are visible to every linked worktree. Broadcasting remote-ref changes to all watched worktrees would satisfy freshness but violate the product requirement and create unnecessary metadata work.

Mitigation: cache only Git's resolved full upstream ref name on each Repository and compute the loose remote ref path from common_git_dir() when routing. For common config changes, deliver updates only when refresh_tracked_remote_ref changes the cached value. Tests must include two worktrees sharing the same common .git directory but tracking different upstream refs.

Risk: cached tracked remote ref becomes stale

If the watcher misses a HEAD or config event, remote-ref routing could use an outdated cached upstream ref name.

Mitigation: initialize the cache in Repository::new, refresh it on all allowlisted tracking-state events, and refresh it during initial scan/start-watching if needed. Keep existing manual and metadata refresh paths as backstops. Prefer conservative false negatives over routing unrelated remote refs to every repository.

Risk: running Git from watcher-triggered state refreshes

Resolving the upstream with Git is more correct than parsing config, but it introduces process execution when HEAD or config changes.

Mitigation: run Git only on repository construction/startup and tracking-state events, not on every remote-ref event. Use Task::RefreshTrackedRemoteRef in the existing repository task queue so watcher routing never blocks on Git. Cache None on Git failures and let existing manual/other refresh paths handle the repository.

Risk: over-broad shared Git watching

Watching common_git_dir/refs or common_git_dir for linked worktrees is broader than the current refs/heads registration.

Mitigation: keep should_ignore_git_path as the allowlist boundary. Only local branch refs, remote-tracking refs, tracking-state files, and index/HEAD files should pass through; tags and other refs remain ignored. Add tests proving tag changes and unrelated Git internals under the broader watched directory do not produce repository updates.

Risk: stale reads while Git is updating refs or config

A filesystem event can fire while Git is still writing a ref or replacing config.

Mitigation: route based on path and cached tracking state, refresh cached tracking state after config/HEAD events by asking Git for the current upstream, then reuse the existing debounced watcher and throttled metadata refresh. If metadata load races and observes stale state, later Git file events or manual refresh paths should correct it. Avoid adding bespoke retry loops unless tests prove they are necessary.

Follow-ups

• Support .git/packed-refs if product later needs packed remote refs to trigger metadata refresh.
• Consider a shared utility for resolving the current branch's upstream ref if other Git UI features need the same information.
• Consider adding telemetry around metadata refresh causes if remote-ref invalidations become performance-sensitive.