---
title: Stacked pull requests with venom stack
description: Split a large branch into a chain of small pull requests, submit, restack and land them with venom stack.
section: reference
order: 190
audience: [user, agent]
sources: [docs/stacked-prs.md, cli/src/stack.ts]
features: [reference.doc-stacked-prs]
---

A stack is a chain of branches, each built on the one below, each with its own small pull request. `venom stack` runs it over `git` and `gh`; no model is called.

```bash
venom stack status            # the branches between origin/main and HEAD, bottom first, with their PRs
venom stack submit            # push each branch and open (or retarget) its PR on the branch below
venom stack restack           # rebase each branch onto the one below, the bottom onto origin/main
venom stack land              # land the stack bottom up through the gate
venom stack land --dry-run    # print the order and stop
```

Run it from the top branch of the stack with a clean tree. The stack is the local branches whose tips lie on `origin/main..HEAD`.

## Splitting a big branch {#split}

```bash
venom stack split --dry-run                      # the plan: slices, files, lines
venom stack split --max-lines 400 --check "make test-cli"
venom stack submit
```

`split` cuts a branch with a large diff into `<branch>-split-1` to `-k`, each a single commit on the one below, the first on the merge base with `origin/main`. Files are ordered by dependency: a TypeScript or JavaScript file comes after the changed files it imports, and a test after the code it tests.

`--check <cmd>` runs a command on every layer; the first failure stops the split and names the layer, so a layer that is not green on its own is found before it is submitted. Without `--check`, only the dependency order supports the claim that each layer builds.

## Landing {#land}

For each pull request, bottom first: the remaining branches are rebased onto `origin/main` without the commits that just merged, pushed with `--force-with-lease`, the pull request is retargeted to `main`, and the gate runs with `--merge`. `land` stops at the first pull request that does not merge and says which stage failed.

| Exit code | Meaning |
|---|---|
| 0 | Done. |
| 1 | A gate stage or a `gh` call failed. |
| 2 | Needs a person: a conflict, a dirty tree, a missing pull request, a bad argument. |

## Related

- [Evidence bundles](/docs/reference/evidence-bundle.md)
- [make targets](/docs/reference/make-targets.md)
