Branches and descriptions

Branches are the unit of work; the branch description is the commit message.

Markdown

All pages

In Oak the branch is the unit of work, not the commit. A branch is one task — usually one agent session or one change a person wants reviewed — and it ends by being squash-merged onto main or closed.

How branches work#

Start a task#

oak start "Fix the login redirect"                     # branch named fix-the-login-redirect
oak start "Fix the login redirect" --name login-fix    # choose the name

oak start is the usual way to begin work. It creates a branch from main named after the summary (with -2, -3 if that's taken), sets the summary as its description, and pushes it. Run oak pull to merge in a newer main; if that conflicts, see Merging and conflicts.

Uncommitted files come with you, as with oak switch -c; --clean discards them. --no-push skips the push.

Create and switch#

oak switch -c                       # new branch off the latest main, generated name
oak switch -c fix-login-redirect    # …with a name
oak switch -c --clean               # …and drop uncommitted changes instead of carrying them over
oak switch fix-login-redirect       # switch to an existing branch (fetched from the server if needed)
oak switch                          # pick from a list
oak switch -d 3f9fab02              # detach HEAD at a commit (full hash or unique prefix)

Uncommitted edits come with you when you create a branch, the way git checkout -b works; pass --clean to start fresh instead. oak switch main is an error — there's no local main to switch to.

Descriptions#

Commits carry no message. The branch description says what the whole branch does, and it becomes the commit message of the squash commit on main when the branch merges.

oak desc "Retry flaky uploads with jittered backoff"
oak desc --file description.md          # from a file
git log -1 --format=%B | oak desc --file -   # …or from stdin
oak desc --append "Also fixes #212."    # add a paragraph to the existing description

oak desc saves locally and, if the branch has been pushed, updates the server too; otherwise the next oak push carries it. It can be changed any number of times until the branch merges.

Write it for someone reading main's history months from now: what changed and why, not a list of touched files. A first line that works as a title, then a blank line and detail, renders best. If a branch merges without a description, the squash commit's message falls back to the branch name.

--append refuses, rather than overwrite, when your local copy of the description is out of date with the server's — it tells you the exact command to refresh with. That makes it safe for several agents to add notes to one branch.

List and inspect#

oak branch                      # local branches
oak branch --show-current       # just the current branch's name
oak branch list --remote        # open branches on the server, as JSON
oak branch list --remote --status all
oak branch show fix-login-redirect --remote
oak status --json               # repo, branch, parent, remote, and linked-repo details

Add --json to any of them for machine-readable output. To compare or review branches without switching to them, see Reviewing branches.

Close and reopen#

oak close                                   # close the current branch
oak close old-experiment --remote --json    # close a pushed branch without switching to it
oak close old-experiment --reason "superseded by fix-login-redirect"

To close several pushed branches only if they haven't moved since you looked, pin each to its head: oak close --remote --json A@FULL_HEAD B@FULL_HEAD --reason superseded. The pin is read, then the branch is closed; the server's close has no expected-head condition, so a push in between isn't prevented. The CLI re-checks afterward and reports closed_after_head_moved if the head moved. Details in the CLI reference.

Merging closes a branch automatically. Close the ones you're abandoning so they drop off the open-branch view. Closing is idempotent and keeps everything — a closed branch can be reopened from its page on oak.space (or via the API).

Reshape a branch with oak split#

oak split is Oak's git rebase -i. It opens a todo list of the branch's commits where you can reorder them, drop some, or send groups of them to new, independent branches — useful when an agent did two unrelated things on one branch.

oak split                         # interactive, on the current branch
oak split --from big-branch       # on another branch
oak split --plan plan.txt         # apply a plan non-interactively (or --plan - for stdin)
oak split --dry-run               # print the resulting structure without writing

oak histedit is an alias.

Branch names#

Names can't contain whitespace, control characters, / or \, and main is reserved.

oak branch rename exists but is temporarily disabled (the server returns 503) while a storage-integrity issue is fixed. To rename, create a new branch from the old one's work and close the old one.

Limits#

A repo can hold up to 10,000 branches, open and closed. There's no cap on open branches during the beta — see Plans and limits.

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