Stacked branches

A stacked branch builds on another open branch instead of on main: main <- a <- b. Use it when b needs the unmerged work in a and you want to review and land them separately.

Create a stack#

oak switch -c part-two --stack          # stack on the current branch
oak switch -c part-three --parent part-two   # stack on a named open branch

With --stack the new branch starts at the current branch's head. --parent BRANCH stacks on that open branch instead (it needs a clean working tree, or --clean). --parent main is the ordinary, unstacked branch.

Working in a stack#

• oak diff --branch, oak status and review show only the branch's own work, against its parent.
• oak pull fetches the parent from the server and merges it in, the way a branch on main merges main.
• oak push refuses until the parent is on the server. Push the bottom of the stack first.

Landing a stack#

Land from the bottom up. oak merge on a branch that has a feature-branch parent refuses and names the bottom branch.

oak merge part-one --json    # lands on main and closes part-one
oak pull                     # in part-two: adopt main as the new parent
oak merge --dry-run --json   # predict the next one

When a branch lands or closes, the server moves its open children onto its own parent. The merge JSON lists them as restacked_branches, and the pull in a child reports restacked_from.

oak merge --into-parent folds a stacked branch into its parent locally instead of landing it on main.

See Branches for descriptions, and the CLI reference for the flags.