Module sync 

The sync engine: source-agnostic glue between ReviewSource, RepoStore, and the Vcs backends.

Workspaces are per stack, not per review: reviews whose ancestors chain them together (a Phabricator stack) share one workspace, built from the stack’s tip, and a lone review is just a stack of one. See stacks for how reviews are grouped.

rq sync (this module’s sync()) only ever tracks metadata and updates/removes existing workspaces - it never creates one. Per source, per run:

1. fetch_queue() - reviews currently waiting on you.
2. New reviews are recorded with no workspace (see fetch_local() for that); tracked ones get their metadata (including version and ancestors) refreshed.

Then, once per source, for tracked reviews that weren’t in this run’s queue (you acted on them - approved, requested changes - so they dropped out): fetch_status() tells us whether the review itself resolved (landed/closed/abandoned/merged). A resolved review that isn’t part of a workspace is just dropped.

Finally each existing workspace is reconciled against its stack: reviews newly chained onto a checked-out stack join its workspace; a workspace whose tip or tip version changed is updated in place if clean (update_workspace), or flagged if dirty; one whose reviews have all resolved is removed, discarding any local changes. This is the only workspace-removal path; there’s no separate prune step.

fetch_local() is the on-demand counterpart - resolving a canonical repo (asking before cloning one, unless told otherwise) and creating a workspace for a single already-tracked review’s stack, or, if it already has one, moving it to that review’s patch. It’s what rq fetch and the fetch hotkey in rq show’s TUI call; sync() never calls it itself.

Structs

SyncReport

WorkspaceDirty

Returned by remove_workspace when the workspace has local changes and force wasn’t set. Callers should confirm with the user and retry with force: true if they agree to discard them.

Functions

fetch_local

Resolve a canonical repo (asking before cloning one, unless on_missing says otherwise) and make sure key, a review already tracked by a prior sync(), has a workspace - the one for its whole stack - then move that workspace to key’s own patch. If the stack is already checked out this is just the move (skipped when the workspace has local changes, which are never disturbed); an ApplyFailed workspace is instead cleaned up and rebuilt, since handing back a broken/empty path again would just repeat the failure silently. This is the on-demand counterpart to sync()’s deliberate refusal to create workspaces on its own - see the module docs.

remove_workspace

Delete the local workspace of a review’s stack on demand - the d hotkey in rq show’s TUI. Acts regardless of resolved/in_queue, unlike sync()’s own resolved-and-clean removal path, and on every review in the stack, since they share the one workspace.

sync