Struct Builder 

pub struct Builder { /* private fields */ }

Builder for a RepoWatcher — set the watch scope and debounce timing, then build.

Implementations

impl Builder

pub fn working_tree(self, yes: bool) -> Self

Also watch the working tree recursively, so a bare unstaged edit (vim file) fires WorkingCopyChanged immediately. Off by default (only the .git/.jj state dir is watched, which catches an unstaged edit once it touches the index / a jj snapshot).

Note: notify is .gitignore-unaware, so this also watches ignored and build directories — heavier on a large tree.

jj note: on jj, a bare working-tree edit only becomes an observable state change once something snapshots the working copy. The re-query is read-only by default (it must not itself snapshot — see snapshot_working_copy), so watching the tree alone will not surface an unsnapshotted edit as a WorkingCopyChanged: the event fires once a jj command (or another watcher opted into snapshot_working_copy) records it. Opt into snapshot_working_copy(true) to have the re-query itself snapshot, at the cost of the watcher recording jj operations.

pub fn snapshot_working_copy(self, yes: bool) -> Self

Whether each re-query may let jj snapshot the working copy — off by default, which keeps the watcher a pure observer.

By default (false) the re-query is read-only: on jj it passes --ignore-working-copy (via Repo::snapshot_readonly), so observing the repo records no jj operation and never moves @. This is almost always what you want: an ordinary jj query snapshots the working copy as a side effect (taking the working-copy lock, recording an operation, possibly moving @), so a naive watcher would mutate the very state it reports — and, worse, a requery_timeout firing mid-snapshot would abort that mutation.

The trade-off (jj only): a bare working-tree edit that no jj command has snapshotted yet is not reflected until a real jj operation records it. If your consumer genuinely needs to observe such unsnapshotted edits (e.g. a live “dirty” indicator driven purely by filesystem edits), set this true: each re-query then snapshots the working copy (via Repo::snapshot), recording a jj operation and possibly moving @ — an explicit, opt-in mutation, not a hidden side effect of reading. Pair it with working_tree(true) so the tree edits actually trigger a re-query.

On git this knob has no effect — git’s status/branch queries never record operations or move refs, so both modes behave identically.

pub fn debounce(self, window: Duration) -> Self

The quiet window: re-query once the watched dir has been silent this long after the last event (default 250 ms). Coalesces an operation’s write burst into one re-check.

pub fn max_wait(self, ceiling: Duration) -> Self

The ceiling on how long a continuous event stream defers the re-query (default 1 s) — a long bulk operation still reports at this cadence.

pub fn requery_timeout(self, timeout: Option<Duration>) -> Self

Deadline on a single re-query (the snapshot + branch-list pair), default DEFAULT_REQUERY_TIMEOUT (30 s); None disables it. Orthogonal to max_wait: that bounds how long signals may defer a re-query, this bounds how long one re-query may run. On overrun the spawned commands are killed (kill-on-drop) and the re-query is retried three times with bounded exponential backoff, even if no new filesystem event arrives.

It also bounds the startup baseline captured by build: a baseline that overruns fails build() with a transient Io TimedOut (Error::is_transient()), rather than hanging the caller — so a wedged repo can’t stall build() any more than it can stall the loop.

Note: on a very large repository a cold-cache git status (first run after a gc, or on a slow disk) can legitimately exceed the 30 s default — raise it (or pass None) there; a watcher whose every re-query is being killed shows up as climbing WatcherStats::skipped with flat changes.

pub async fn build(self) -> Result<RepoWatcher>

Start watching. Captures the baseline state, registers the filesystem watch, and spawns the background re-query task on the current tokio runtime.

The baseline capture is bounded by requery_timeout, so on a wedged repo build() returns a transient Io TimedOut (Error::is_transient()) instead of hanging at startup — retry, or raise the timeout.