# Stacked pull requests A stack is an ordered chain of open pull requests in one repository. Each pull request targets the branch of the one below it, and the bottom one targets the **landing base**, such as `main`. Use a stack to split a large change into small reviewable steps that depend on each other. You need read access to view a stack and write access to change one. A pull request belongs to at most one stack, and a stack holds 1 to 50 pull requests. ## View stacks Open the repository's stacks list at `///stacks`, or a single stack at `///stacks/`. A pull request in a stack shows the stack in its sidebar. ```sh cafe stack list cafe stack status 14 ``` ## Publish a stack from local commits `cafe stack submit` pushes each commit after the base as its own branch and opens or reuses one pull request per commit. Run it from your checkout; it works with Git, jj and Sapling. ```sh cafe stack submit --name my-change --base main --dry-run cafe stack submit --name my-change --base main ``` `--dry-run` shows the plan without pushing. To add commits to the stack later, run the same command with the same `--name` and `--base`: the existing pull requests must be the start of the new plan, and new ones are appended. If submission stops part-way, the branches and pull requests it already created remain. Fix the problem and run the same command again to continue. To choose the version control tool once instead of passing `--vcs` each time: ```sh cafe config set stack.vcs jj --global ``` ## Link existing pull requests If the pull requests already exist and form a chain, link them bottom to top: ```sh cafe stack link 12 13 14 ``` Pull 13 must target pull 12's branch, and pull 14 must target pull 13's branch. Linking does not push anything. ## Land a stack Landing merges the stack from the bottom up through the pull request you choose. Each landed pull request leaves the stack and the next one retargets to the landing base. The stack is complete when its last pull request lands. ```sh cafe stack merge 14 --dry-run cafe stack merge 14 --strategy merge --yes ``` Replace `14` with the highest pull request you want to land, or pass `--stack ` to land the whole stack. The preview shows readiness; permissions and [rulesets](https://git.cafe/docs/repositories/repository-rulesets.md) are checked again for each pull request as it lands, and landing stops if a branch changes after you approved it. - **merge** can land several pull requests at once. - **rebase** lands one pull request at a time. - **squash** is not available for stacks hosted in GitCafe. A pull request in a stack can only merge through its stack: `cafe pr merge` points you to `cafe stack merge`. Open pull requests outside the stack that target a landed branch move to the landing base too. ### If landing does not finish Landing continues in the background after the command returns. To check on it: ```sh cafe stack merge --stack 7 --operation latest ``` If it is waiting for you, resume the same operation rather than starting a new one: ```sh cafe stack merge --stack 7 --operation --resume --yes ``` In the browser, reloading a member pull request shows the unfinished landing and offers **Resume landing** when it can continue. ### Stacks synchronized with GitHub In a repository synchronized with GitHub through the GitHub App, with pull request writes enabled, GitHub stacks are imported and stack changes made in GitCafe are sent to GitHub. GitHub performs the merge and supports merge, squash and rebase. A one-pull-request stack stays a plain pull request on GitHub until you append a second one. ## Restack after the base changes Restacking rebases each pull request in the stack onto the current version of the one below it, so the chain stays up to date after a lower pull request changes or the landing base moves. Use **Restack** in a member's sidebar to start at that member, or: ```sh cafe stack restack --stack 7 --dry-run cafe stack restack --stack 7 ``` Each upper pull request replays only its own commits. If a pull request no longer contains the previous tip of the one below it, restacking stops there with a conflict: rebase the remaining pull requests locally and push them. A failed restack may already have updated the lower branches, so check the stack before trying again. `cafe stack restack --stack 7 --operation latest` shows the latest result. ## Unstack or close a stack **Unstacking** dissolves the stack and leaves its pull requests open. It is available through the [REST API](https://git.cafe/docs/reference/api.md) (the stack `unstack` operation). Pull requests cannot be reordered or removed from a stack individually. **Closing** dissolves the stack and closes all its open pull requests without merging them, for example when the change landed some other way: ```sh cafe stack close --stack 7 --dry-run cafe stack close --stack 7 --yes ``` Closing needs write access and permission to close each open pull request. Pull requests that already landed stay merged. Either everything closes or nothing changes. A stack that is landing or restacking cannot be closed until that finishes. Closed pull requests can be reopened one by one, but the stack cannot be restored.