Reviewing branches

Checkout-free review: triage a fleet of branches, read diffs, and merge from the CLI or web.

Markdown

All pages

When agents do the work, review becomes the bottleneck: ten branches come back, and switching your checkout ten times to read them isn't an option. Everything on this page is checkout-free — it reads the server (or your local repo) and prints, without touching your working tree.

Triage first#

oak branch triage --remote                    # every open branch, scored
oak branch triage --remote --only mergeable   # just the ones ready to land
oak branch triage --remote --json             # for an agent doing the triage

Each row carries:

FieldValues
Mergeabilityclean, conflicts
Contributioncontributes; or empty / superseded_exact for a branch that adds nothing main doesn't already have
Recommended actionvalidate_then_merge, resolve, close, rebuild, review, do_not_merge

--only mergeable | closable | ambiguous sorts a fleet before you read a single diff: land the first bucket, close the second (agent runs that produced nothing new), and spend your attention on the third. --analysis-depth trades speed for depth, --limit N caps how many branches get the deep pass, and --against <branch> compares against something other than main.

Review one branch#

oak branch review fix-auth--a1b2c3d4 --merge-preview

oak branch review gathers the evidence for one branch: what it changed, what it's based on, and — with --merge-preview — whether it would merge cleanly, plus a merge-safety verdict that flags a prediction which would destroy work already on main. It reads the branch from your checkout, so switch to it or pull it first. Add --json for agents.

Read a diff without switching#

oak diff fix-auth--a1b2c3d4                     # full-screen viewer: what the branch contributes
oak branch diff fix-auth--a1b2c3d4              # summary of changed files
oak branch diff fix-auth--a1b2c3d4 --json --hunks   # the patch, as JSON
oak diff 3f9fab02 8fcf5aed                      # any two commits

Branch diffs come in three modes, chosen with --diff-mode (oak branch diff) or --mode (oak diff):

ModeAnswers
contributionWhat did this branch add since it forked from main? The honest "what did the agent do".
treeHow do the two heads differ right now? (Default for oak branch diff.)
net-mergeWhat would main gain if this branch merged now?

For large branches, --changed-files-limit / --changed-files-offset page through the file list and --max-bytes caps the patch text in JSON output.

The full-screen viewers#

oak diff and oak log open full-screen on a terminal. Both take the keys you already know:

StyleKeys
Arrows↑ ↓, PgUp / PgDn, Home / End
less / vij k, Space (page down), b (page up), d / u (half page), g / G, / to search
emacs^N / ^P, ^V / M-v, M-< / M->, ^S to search, ^G to cancel

In oak diff, Tab or the arrow keys move between the file tree and the diff pane, and Space folds a directory in the tree. Press ? in either viewer for the complete list. Pipe the output, or pass --print / --json, to skip the viewer.

In the browser#

The repo's Branches page on oak.space lists every open branch: its title, who pushed last, and when. Each branch opens a detail page with:

Check several branches on the list and Merge selected lands them one after another — usually how a fan-out ends when the branches don't overlap.

Then land it#

oak switch fix-auth--a1b2c3d4     # fetches it if needed
oak merge                         # squash onto main

See Merging and conflicts.

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