Source control

Repositories, virtual roots, branches, and access

Vex source control combines physical backing repositories with virtual repository roots for imported projects and monorepo workflows.

Your organization's Home repository

Every organization's aggregate repository is canonically addressed as <org>/home. GitHub onboarding weaves each imported repository into a synced folder beneath that Home repository, so the organization keeps one shared history and trunk.

Existing <org>/main addresses remain a permanent compatibility alias for the same repository identity. This address migration does not rename a branch or bookmark named main.

Pull, sync, and push are separate

vex pull refreshes hosted bookmarks as bookmark@vex without moving the working copy. Use vex sync --target main to pull and restack the current line of work; submitted stacks also reconcile their review state.

Publish an explicit source and destination with vex push -r @- --to main. Creating, forcing, and deleting hosted bookmarks require their explicit flags, and --dry-run previews the planned mutation.

Key surfaces

  • Repository tree, blob, history, branch, review, and merge views
  • Repository access token catalog and authorization flow
  • Virtual repositories rooted at a monorepo path
  • Git/GitHub import baselines and remote sync contracts
  • Native stacked review with idempotent submit and sync
  • Target-branch merge queues for stacks and GitHub pull requests
  • GitHub-compatible CI from .vex/workflows
Remote Git sync docsGitHub CI docs

Submit and merge a stack

Run vex submit to create or update one review per stable JJ change id. Amend and rebase preserve the diff identity; repeating an unchanged submit creates no patchsets. Run vex sync after target movement or landing to fetch the exact target, remove a landed prefix, restack remaining changes, and synchronize the server.

vex stack merge adds the current stack to its target queue. The repository queue page at /<org>/<repo>/queue shows ordered entries, candidate and check state, ejection reasons, and pause, promote, retry, cancel, and merge controls. Vex-primary is the default authority; a GitHub-backed virtual repository can explicitly switch to GitHub-primary after its queue and projections are clean and required App permissions are present.

Stack and queue commandsStack and queue API

Download a trunk snapshot

In a repository's Browse view, open Clone and choose Download Trunk ZIP. Vex resolves the current trunk at download time and returns its materialized files without history, .git, .jj, or generated Vex cache directories. Virtual repository downloads stay inside their configured root and remove the parent monorepo prefix.

Signed-in browser sessions can also use GET /api/v1/organizations/<org>/repos/<repo>/vcs/archive.zip. API clients need a bearer token with repository read access. Use vex clone when you need history or a normal Vex working copy.

Virtual working-copy capability model

The web app publishes the safe platform model, but it does not open local daemon sockets from the browser. Use vex daemon capabilities or the desktop VCS panel for the live host report.

CLI commands

Non-FUSE virtual working copy

Available

Local JJ fallback remains available for virtual clone workflows outside daemon mounts.

Read-only daemon mount

Host-gated

Requires local vexd plus Linux FUSE on the machine that owns the mount.

Writable daemon mount

Host-gated

Uses daemon-owned overlay writes and requires the same local FUSE boundary.

Remote lazy fetch

Environment-gated

Repo-owned code exists; live mounts need jj-backend coordinates, tenant/ref data, and auth.

Cloud workspace durability

Product-gated

Local encrypted export, inspect, and restore exist; server object storage and KMS are still pending.

Daemon-backed workflow

  1. Clone with vex clone, then inspect daemon health and capabilities from the CLI or desktop app.
  2. Mount with vex mount when Linux FUSE is available, using --read-write for overlay-backed edits.
  3. Use changed-files, hash, prefetch, and watch for build and editor integrations without scanning the tree.
  4. Snapshot, goto, and checkout through the daemon so dirty overlay state and conflicts remain explicit.
  5. Run fsck and conflicts recovery before unmounting or exporting local encrypted handoff state.
  6. Export, inspect, and restore cloud-workspace handoff bundles while live server durability remains gated.

Live remote fetch, live server-side cloud recovery, and privileged Linux FUSE smokes remain externally gated. Local encrypted cloud-workspace inspect is the current non-mutating review/build access path for unlanded workspace state.