# Reviewing branches

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

```bash
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:

| Field | Values |
|---|---|
| Mergeability | `clean`, `conflicts` |
| Contribution | `contributes`; or `empty` / `superseded_exact` for a branch that adds nothing `main` doesn't already have |
| CI | the branch head's [CI](/docs/ci) status |
| Recommended action | `validate_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

```bash
oak branch review fix-auth--a1b2c3d4 --remote --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`. Add `--json` for agents.

## Read a diff without switching

```bash
oak diff fix-auth--a1b2c3d4                     # full-screen viewer: what the branch contributes
oak branch diff fix-auth--a1b2c3d4 --remote     # summary of changed files
oak branch diff fix-auth--a1b2c3d4 --remote --print          # the patch, to stdout
oak branch diff fix-auth--a1b2c3d4 --remote --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`):

| Mode | Answers |
|---|---|
| `contribution` | What did this branch add since it forked from `main`? The honest "what did the agent do". |
| `tree` | How do the two heads differ right now? (Default for `oak branch diff`.) |
| `net-merge` | What 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.

## Preview a merge train

```bash
oak branch train fix-auth--a1b2 add-search--e5f6 bump-tokio--c9d0 --remote
```

`oak branch train` previews landing several independent branches in order — would each still merge cleanly after the ones before it? — without publishing anything. Up to 32 branches.

## The full-screen viewers

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

| Style | Keys |
|---|---|
| Arrows | ↑ ↓, PgUp / PgDn, Home / End |
| less / vi | `j` `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 with its description and a CI status chip. Each branch opens a detail page with:

- the full diff, file by file;
- per-workflow CI pills that link to live run logs;
- a **Seen by** list — opening a branch page records that you've read it;
- **Merge**, **Update** (merge the latest `main` into the branch), and **Close** / **Reopen** buttons, plus conflict resolution in the browser when a merge would conflict.

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

```bash
oak switch fix-auth--a1b2c3d4     # fetches it if needed
oak merge --wait                  # wait for CI, then squash onto main
```

See [Merging and conflicts](/docs/merging).