Skip to content

Branching and Merging

Kyle Ebbinga edited this page Nov 19, 2026 · 1 revision

Branching and merging

Branches in Vertex are cheap server-side copies, and merges run entirely on the server, at the file level. Nothing is downloaded to branch or merge. You sync afterwards to get the result.

Branches

vx branch                 # the current branch, and where it merges to
vx branch list            # every branch of the project
vx branch feature-x       # a new branch with the current branch's files as last submitted
vx checkout feature-x     # switch this workspace to it
vx branch -d feature-x    # delete it (asks first)

A new branch copies its parent's files as last submitted, not your workspace. Unsubmitted changes stay behind in the workspace, and vx branch warns about them. Submit first if you want them on the new branch. vx branch experiment --blank starts a branch with no files and no shared history (so it can't be merged with the others).

vx checkout refuses while you have local changes, then downloads only the files whose content differs between the two branches. Switching between two branches of a 100 GB project that differ in a handful of files takes seconds.

How branching works inside

Creating a branch copies the parent's rows in revisions.head (path → content id) in one transaction. That's metadata only: no content is copied, because chunks are shared by content id. The new branch records the parent's head revision as its base_revision. A branch's head revision is the greater of its base and its own latest revision.

Syncing to the latest revision reads revisions.head directly (the fast path). Syncing to an older revision, or a workspace last synced before the branch was copied, rebuilds the file list from history along the branch's parent chain and tells the client the list is complete, so it also removes files that aren't in it. See History and revisions.

Merging

vx merge feature-x                          # bring feature-x into the current branch
vx merge feature-x --into main              # or into another branch
vx merge feature-x --take-source            # files changed on both: feature-x wins
vx merge feature-x --keep-target            # files changed on both: the current branch wins
vx sync                                     # get the result

A merge takes every file changed on the source since the last merge between the two branches and writes them as one revision on the target. It works between any branches that share history: a parent and child in either direction, or siblings cut from the same branch.

What counts as a conflict

Vertex merges whole files, never their content. Binary assets can't be merged line by line, and for text files a server-side line merge would hide surprises. For every path whose content differs between the two branches, the server compares three content ids: the file at the merge base (B), on the source (S) and on the target (T).

Situation Result
Only the source changed it (T = B) The target takes the source's version.
Only the target changed it (S = B) Nothing to do.
Both changed it Conflict.

Any conflict refuses the whole merge and lists the files, unless --take-source or --keep-target picks a side for all of them. A file locked on the target by someone else also blocks a merge that would change it, so a merge never overwrites work in progress.

To merge some conflicting files one way and some the other, resolve them by hand on the target branch: sync both versions, keep the one you want, submit on the target, and merge again.

The merge base

The base is the newest state both branches contain:

  • After an earlier merge between the two (in either direction), it's the source side of the latest one, recorded in revisions.merges.
  • Before any merge, it's the nearest common ancestor branch as of the older of the two copies: the parent for a parent and child, the branch both were cut from for siblings.

Every merge is complete: conflicts either refuse it or are settled by --take-source/--keep-target. Every merge that settles anything is recorded, even when it writes no revision, so a conflict you settled once never comes back.

Concurrency

Planning a merge can read a lot of history, so it runs without blocking the project's other writes. The write then takes the project's write lock, checks in the same round trip that neither branch moved and no merge between them was recorded since the plan was made, and plans again if one was. A merge can't silently overwrite a submit that landed while it was planning.

Merge chains

A branch can name a merge target. Every revision that lands on it, by submit or by merge, is then merged on into that branch by the server, hop by hop:

vx branch release-1.0 --merge-to release-2.0
vx branch release-2.0 --merge-to main
# a fix submitted to release-1.0 now lands on release-2.0 and main too

vx submit prints each hop. Rules:

  • Each hop is an ordinary merge with no conflict resolution, so a chain never overwrites anything. It stops at the first hop that conflicts, hits a lock, or has nothing to do, and it continues past a target only when that hop wrote a revision.
  • The revision that started the chain stands either way.
  • A missed hop is caught up by the next revision on the branch, because a merge takes everything since the last merge between the two. To unblock a stuck hop now, resolve it with vx merge <branch> --into <target> and a side.
  • Targets must share history with the branch, and loops are refused. A branch that others merge into can't be deleted.
  • vx branch --merge-to none stops the chain. vx submit --merge-to <branch> does a one-off merge after a submit.

Refused automatic merges are recorded as merge.refused project events (completed ones as merge.completed), so server-side handlers can react to a stuck chain. Clients don't show these events yet; watch vx submit's output.

This is the job Robomerge does for Perforce studios, built into the server.

See also

Clone this wiki locally