Merging and conflicts

Squash-merging onto main, resolving conflicts, and recording what passed with marks.

Markdown

All pages

Merging is how work reaches main, and it's the only way. A merge takes a whole branch — every checkpoint on it — and lands it on main as one squash commit whose message is the branch description.

Merging is a human decision. Agents should push their branch and stop; a person reviews and merges. (Nothing enforces that — it's the workflow Oak is built around, and what the agent skill teaches.)

The merge, step by step#

oak desc "Cache tile lookups in the renderer"   # this becomes the commit message on main
oak push                                          # publish the branch

oak pull                       # bring main's newer commits into your branch
oak diff --branch              # last look at everything the branch changes
oak merge --dry-run --json     # would it merge cleanly? (a prediction; changes nothing)

oak merge                      # squash onto main and close the branch

What each step is for:

You can merge a branch you aren't on: oak merge fix-login-redirect. And you can merge from the browser — every branch's page on oak.space has a Merge button, and the branches list has Merge selected for landing several non-overlapping branches at once. The web merge checks for conflicts before you click.

What lands on main#

One commit:

A merge to main fires the merge webhook event.

Resolving conflicts#

A conflict can come up during oak pull (merging main into your branch) or during oak merge. Both work the same way.

oak pull
# CONFLICT in src/render/tiles.rs

oak conflict status              # what's in progress and how much is left
oak conflict show                # per-file details for every conflicted path

$EDITOR src/render/tiles.rs      # resolve by hand: remove the <<<<<<< ======= >>>>>>> markers
oak conflict take src/render/tiles.rs --theirs   # …or take one side of every block in a file

oak pull --continue              # finish
oak pull --abort                 # …or back out; the branch is left as it was

During a merge, the same commands finish or cancel it: oak merge --continue, oak merge --abort.

When a pushed branch conflicts#

If an agent's branch has gone stale against main, you don't need to redo the work. A conflicting branch's page shows the conflicted files in place of Merge, and the conflict is resolved locally, on the branch, in one of two ways.

With a coding agent. Copy resolve prompt copies instructions for a coding agent: get the branch (an existing clone, or a new shallow one), pull, resolve, check, and push. The agent stops there, so you still review and merge.

By hand. Switch to the branch in a clone (a shallow one is enough), pull, resolve, and push:

oak clone acme/web --shallow
cd web
oak switch fix-auth
oak pull            # conflicts appear here
# resolve, or hand the clone to an agent to resolve
oak pull --continue
oak commit && oak push

Tests and deploys#

Oak runs none of your code on the server, before or after a merge. Agents run the tests before they push. To ship, give each thing you deploy a mark and a machine that follows it with oak mark follow --check ... --run ...: it tests each change on main, moves the mark when the tests pass, and deploys the move.

Undoing a merge#

Open the commit on oak.space and click Revert: Oak lands a new commit on main that applies the inverse of that commit's changes, like git revert. If any file the commit touched has changed since, the revert is refused rather than guessed at. The API equivalent is POST /api/{owner}/{name}/commits/{hash}/revert.

When a merge is refused#

What you seeMeaningWhat to do
Conflicts (409 with conflict_paths)The branch and main changed the same lines.oak pull, resolve, push, merge again.
main_moved / branch_moved (409, retryable)Someone landed on main, or pushed to the branch, during the merge. Nothing was merged.Retry.
"already closed" (400)The branch was already merged or closed.Nothing — check oak branch show <name> --remote.
"Repository isn't linked to an organization yet"The repo has never been pushed.oak push --repo <org>/<name> first.

Something here wrong or missing? Run oak feedback -m "…" or email [email protected].