# 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

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

```bash
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](/docs/branches) for descriptions, and the [CLI reference](/docs/cli#oak-switch) for the flags.