Skip to content
Docs menu

Stacked pull requests with venom stack

Split a large branch into a chain of small pull requests, submit, restack and land them with venom stack.

View .md

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.

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

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

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.