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:
oak pullfirst. It merges the currentmaininto your branch, so conflicts surface on your branch, where you can resolve them calmly — not halfway through landing onmain.oak merge --dry-runpredicts the merge without pushing or touching files. It checksmain's head on the server first, so the prediction is certified against themainthe merge would land on;--offlineskips that and reports it uncertified.oak mergeasks the server to squash the branch onto its parent (main) and close it. Only the approvals a path rule asks for can hold it up.
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:
- Message: the branch description (or the branch name, if it has none).
- Contents: the branch's final tree, merged with
main. - Ancestry: the squash commit keeps a pointer (
merge_parent_hash) to the branch's last checkpoint, so the full pre-squash history stays reachable for tooling, even thoughmainshows one line per task.
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.
- Markers are line-level. Oak wraps only the diverging lines, not whole files.
--ourskeeps your branch's side;--theirskeepsmain's (or the remote's).- Every
oak conflictcommand takes--json, so handing resolution to an agent is a supported path.oak diff --checkcatches markers you forgot to remove. - While a conflict is in progress, commands that would change the branch exit with code
5.
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 see | Meaning | What 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. |