Skip to content

vox-vcs API Reference (generated)

Crate: vox-vcs · Version: 0.6.0 · Target: Library (lib.rs)

VCS backend abstraction for Vox — VcsBackend trait, in-memory CasFallback, and (later) the jj-lib engine. The single home for all jj_lib:: calls.

vox-vcs — the VCS backend abstraction for Vox.

All jj-lib calls are confined to this crate (jj_backend.rs). The public async VCS API is [VcsBackend]; use [backend::boxed_for] to obtain a backend for a given path. For jj repos the backend is backed by [jj_actor::JjActorHandle] — a Send + Sync handle to a dedicated OS thread that owns the !Send jj engine.

  • jj (default): enables the jj-lib engine (jj_backend, jj_actor, JjBackend, JjActorHandle) and the tokio/futures dependencies they require. Build-time-sensitive consumers that do not need jj can opt out with --no-default-features; the VcsBackend trait, CasFallback, and all types remain available.
FeatureDefault / Enables
defaultjj
jjdep:jj-lib, dep:tokio, dep:futures
DependencyKind
vox-configNormal
ModuleDescription
backend—
cas_fallback—
types—
jj_backend—
Dependency Topology, diagram 13 nodes, 2 edges: vox-vcs → vox-config; vox-orchestrator → vox-vcsvox-vcsvox-configvox-orchestrator
Diagram source
graph {
direction: right
node vox_vcs: "vox-vcs"
node vox_config: "vox-config"
vox_vcs -> vox_config
node vox_orchestrator: "vox-orchestrator"
vox_orchestrator -> vox_vcs
}
Consumer CrateRole
vox-orchestratorDirect workspace dependent
KindSymbolSignatureSourceDescription
enumbackend::VcsErrorpub enum VcsErrorcrates/vox-vcs/src/backend.rs#L14-L19—
traitbackend::VcsBackendpub trait VcsBackend: Sendcrates/vox-vcs/src/backend.rs#L35-L68Async VCS backend. Methods are async fn so backends can drive async engines (e.g. jj-lib’s async APIs) by awaiting directly — no internal block_on, so they are safe to call from within the orchestrator’s tokio runtime. async_trait boxes the returned futures, which keeps the trait dyn-object-safe (Box<dyn VcsBackend> / Arc<RwLock<dyn VcsBackend>>). ## Send-safe design jj-lib 0.42’s async futures are !Send. VcsBackend is #[async_trait] (Send futures) so handles can cross tokio::spawn. The JjBackend engine (which is !Send) lives on a dedicated OS thread behind JjActorHandle, which satisfies this Send contract.
enumbackend::VcsBackendKindpub enum VcsBackendKindcrates/vox-vcs/src/backend.rs#L71-L74—
fnbackend::detectpub fn detect(repo_root: &Path) -> VcsBackendKindcrates/vox-vcs/src/backend.rs#L80-L88Detect which VCS kind is present at repo_root. Returns Jj when a .jj directory exists and the jj feature is enabled; otherwise returns Cas.
fnbackend::boxed_forpub async fn boxed_for(root: &Path) -> Box<dyn VcsBackend>crates/vox-vcs/src/backend.rs#L98-L108Construct a boxed [VcsBackend] for root. With the jj feature (default): if the directory contains a .jj workspace, a [crate::jj_actor::JjActorHandle] is spawned (the actor owns the !Send jj engine on a dedicated OS thread). If spawning fails, or there is no jj workspace, [CasFallback] is returned. Without the jj feature: always returns [CasFallback].
structcas_fallback::CasFallbackpub struct CasFallbackcrates/vox-vcs/src/cas_fallback.rs#L10-L13—
fncas_fallback::newpub fn new() -> Selfcrates/vox-vcs/src/cas_fallback.rs#L16-L21—
structjj_backend::JjBackendpub struct JjBackendcrates/vox-vcs/src/jj_backend.rs#L102-L106In-process jj engine. Awaits jj-lib’s async APIs directly from the async VcsBackend trait — no internal tokio runtime, so it never panics with “Cannot start a runtime from within a runtime” when called from the orchestrator’s async context.
fnjj_backend::openpub async fn open(root: &Path) -> Result<Self, VcsError>crates/vox-vcs/src/jj_backend.rs#L141-L174Open a jj workspace at root, loading an existing one if present and otherwise initializing a fresh colocated jj/git repo. This is the path the Vox repo itself needs: it is already colocated, so a blind init_colocated_git would error on the existing .jj dir. Load path (P2 Task 1): Workspace::load(settings, root, &StoreFactories::default(), &default_working_copy_factories()) (workspace.rs:406) attaches to the on-disk .jj/. DefaultWorkspaceLoader::new returns WorkspaceLoadError::NoWorkspaceHere (workspace.rs:567) when there is no .jj dir — that is our fall-back-to-init signal. The loaded Workspace does not carry a repo, so we materialize it with workspace.repo_loader().load_at_head().await (repo.rs:764).
fnjj_backend::create_conflict_for_testpub async fn create_conflict_for_test(crates/vox-vcs/src/jj_backend.rs#L187Test-only: construct a commit whose tree CONTAINS a materialized conflict in file path, set it as the working-copy commit, and register it. This proves jj-lib can REPRESENT a conflict as data (P2 Task 4) without needing a full rebase/merge driver. Recipe: write three file blobs (base/left/right), build three single-file MergedTrees via MergedTreeBuilder (merged_tree_builder.rs), then MergedTree::merge(Merge::from_vec([left, base, right])) (merged_tree.rs:336) — a 3-way merge with divergent left/right yields a tree where has_conflict() is true. We commit that conflicted tree as the wc commit.
fnjj_backend::snapshotpub async fn snapshot(crates/vox-vcs/src/jj_backend.rs#L284—
fnjj_backend::changespub async fn changes(&self) -> Result<Vec<Change>, VcsError>crates/vox-vcs/src/jj_backend.rs#L372-L390—
fnjj_backend::diffpub async fn diff(&self, a: Option<ChangeId>, b: Option<ChangeId>) -> Result<Diff, VcsError>crates/vox-vcs/src/jj_backend.rs#L399-L435P2 Task 3: real tree diff between two changes. Resolves each ChangeId to its jj Commit via the side-table, takes the commit’s MergedTree (commit.tree(), commit.rs:120), and streams from_tree.diff_stream(&to_tree, &EverythingMatcher) (merged_tree.rs:283), collecting the changed RepoPaths. A None change means the empty tree.
fnjj_backend::undopub async fn undo(&mut self) -> Result<ChangeId, VcsError>crates/vox-vcs/src/jj_backend.rs#L444-L509P2 Task 3: undo the last operation by restoring the parent op’s view. We walk the op log (op_walk::walk_ancestors, op_walk.rs:263) to find the current head op’s parent, reload the repo at that operation (repo_loader().load_at, repo.rs:776), and re-point the working copy by finishing the wc mutation against the restored op id. The restored head op becomes the new current op. Returns the restored op’s ChangeId.
fnjj_backend::conflictspub async fn conflicts(&self) -> Result<Vec<Conflict>, VcsError>crates/vox-vcs/src/jj_backend.rs#L520-L557P2 Task 4 (conflicts-as-data): surface conflicts in the current working-copy commit tree as data. Reads the wc commit’s MergedTree, iterates tree.conflicts() (merged_tree.rs:196) for conflicted paths, and materializes each via materialize_tree_value (conflicts.rs:207). A FileConflict carries contents: Merge<BString> — the conflict sides — which we surface as the sides of our Conflict type. This is the “conflict as readable data, not a blocking error” property the spec wants.
fnjj_backend::resolvepub async fn resolve(crates/vox-vcs/src/jj_backend.rs#L559—
fnjj_backend::pushpub async fn push(crates/vox-vcs/src/jj_backend.rs#L582P2 Task 5: push a change to a remote under bookmark. jj-lib 0.42 reality: push_refs (git.rs:3177) ultimately calls git_ctx.spawn_push (git.rs:3336) — a git subprocess, NOT pure gix transport. A git binary on PATH (>= 2.41) is therefore required. We set the local bookmark to the change’s commit, then push it as a new ref (before: None).
fnjj_backend::create_branchpub async fn create_branch(&mut self, name: &str) -> Result<(), VcsError>crates/vox-vcs/src/jj_backend.rs#L647-L666P4 §5.1/§5.3 (SeparateBranches): create (or move) a local bookmark named name pointing at the current working-copy commit. jj bookmarks are the in-process branch primitive. We set the local bookmark target in a transaction (set_local_bookmark_target, reused from the push path) and publish the op — no git/gix subprocess is needed (unlike push), so this works purely in-process.
structtypes::ChangeIdpub struct ChangeId(pub u64)crates/vox-vcs/src/types.rs#L8—
structtypes::Changepub struct Changecrates/vox-vcs/src/types.rs#L17-L21—
structtypes::Diffpub struct Diffcrates/vox-vcs/src/types.rs#L24-L26—
structtypes::Conflictpub struct Conflictcrates/vox-vcs/src/types.rs#L29-L32—
enumtypes::ResolveStrategypub enum ResolveStrategycrates/vox-vcs/src/types.rs#L35-L39—