---
title: "Stacks: Stacked Pull Requests"
description: How to create and manage stacked PRs.
---
import { Image } from "astro:assets"
import GHPRSchema from "../images/stacked-gh-pr.png"
import MergifyStackSchema from "../images/stacked-mergify-pr.png"
import StackComment from "../images/stack-comment.png"
Mergify Stacks allow you to split your local Git branches in multiple pull
requests to make it easier to split you work in small atomic parts.
## Limitations of GitHub's Pull Request Model
The conventional GitHub pull request model operates on a branch-based system
where each branch corresponds to one pull request.
As more commits are added to a branch and pushed, the associated pull request
expands. This continual growth can complicate the review process, making it
challenging for reviewers as the code base increases. Moreover, this model
often discourages the division of work into atomic, manageable commits.
The concept of Stacks addresses this issue by breaking down work into
incremental, reviewable steps. This structure not only simplifies the review
process but also enhances the digestibility of changes for teammates.
Furthermore, should a rollback be necessary, it's far simpler and less
disruptive to revert a single, small pull request rather than an entire branch
of accumulated changes.
## Advantages of Using Mergify Stacks
Mergify Stacks retains the familiar branch model used in Git while innovating
on how pull requests are handled. Instead of opening one pull request for an
entire branch, Mergify Stacks opens a separate pull request for each commit.
This approach allows developers to maintain all their changes within a single
branch while effectively segmenting their work into smaller, more manageable
parts. Each part is easier to review and quicker to integrate, streamlining the
development process and enhancing overall efficiency.
When a commit needs to be changed, [`git rebase
--interactive`](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) can
be used to
change the content of the branch. Mergify Stacks automatically synchronize your
branch to the pull requests.
This means that there is no need to learn any new tool to manage your Mergify
Stacks: they are just regular Git branches.
:::note
For Mergify Stacks to function effectively, branches must be in the `heads`
namespace.
:::
This process ensures that developers don't have to tediously update each
individual pull request manually. Everything is managed under the hood by
Mergify Stacks, from the commit level to the PR level.
The automated nature of this approach minimizes the chances of human error—like
missing a pull request update or misapplying a change. Developers maintain the
freedom and flexibility of the Git interactive rebase, allowing for granular
and precise changes to commits.
## Setting Up Mergify Stacks
### Installation
Begin by installing the Mergify CLI using
[pip](https://packaging.python.org/en/latest/tutorials/installing-packages/):
Linux:
```bash
python3 -m pip install --user mergify-cli
```
MacOS:
```bash
brew install pipx
pipx install mergify-cli
```
### Configuration
To use Mergify CLI for creating stacked pull requests in your repository,
follow these steps:
1. Execute the following command to set up the commit-msg hook:
```bash
mergify stack --setup
```
2. For GitHub API access, Mergify CLI requires a GitHub OAuth token. If you
have the [gh client](https://cli.github.com/) authenticated, Mergify CLI
will seamlessly fetch the token. If not, create a [personal access
token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
with necessary permissions and set it as an environment variable
(`GITHUB_TOKEN`). You can also provide it directly using the `--token`
parameter.
## Creating Stacked Pull Requests
1. Spawn a branch and introduce your changes.
2. Commit the changes. If Mergify CLI is correctly configured, your commit
message will automatically contain the `Change-Id`.
3. In case you committed before initializing Mergify CLI, use `git rebase
-i` to reword commits and automatically embed the `Change-Id`.
4. To construct the stack, run:
```bash
mergify stack
```
Mergify CLI will manage the creation of individual pull requests for every
commit in your feature branch. This structured approach ensures smooth and
error-free management of changes and reviews.
## Updating Stacked Pull Requests
Inevitably, there will be times when you'll need to modify or refine your pull
requests—perhaps due to feedback from a code review or just a late realization.
Mergify CLI streamlines this process, ensuring your stacked pull requests are
always in sync with your latest changes.
1. **Stay in Your Feature Branch:** The beauty of stacked PRs lies in their
granular structure. Always make sure you are working within the specific
feature branch where the relevant commits reside.
2. **Modifying Commits:** To update or modify commits inside your branch:
- Use the interactive rebase feature of Git:
```bash
git rebase --interactive
```
- Within the interactive rebase session, you can:
- **pick** to retain a commit.
- **reword** to change a commit message.
- **edit** to modify the content of a commit.
- **squash** to combine the commit with the previous one.
- **drop** to remove a commit entirely.
Make your desired changes and save. This action will reapply your commits on
top of the base branch, incorporating the changes you've made.
3. **Pushing Updated Stacked PRs:** Once you've made all the necessary
modifications to your branch and are satisfied with the changes, call the
Mergify CLI with the `stack` command:
```bash
mergify stack
```
This command will push your modified commits and update the corresponding
pull requests on GitHub. Mergify CLI intelligently keeps track of the
relationships between your commits and the pull requests, ensuring
everything remains synchronized.