Stacked Pull Requests
How to create and manage stacked PRs.
Mergify CLI is a powerful tool designed to simplify and automate the creation and management of stacked pull requests on GitHub. Before diving into its functionalities, let's grasp the concept of stacked pull requests and why they matter.
In the world of development, a common scenario is having a
with multiple commits that are sequentially dependent on each other. For
instance, if you have a branch named
feature with three commits:
C, creating stacked pull requests manually on GitHub would require:
- A branch
Awith a pull request based on
- A branch
Bwith a pull request based on
- A branch
Cwith a pull request based on
While this method ensures structured and granular reviews, the native GitHub
approach has its challenges. If a modification is made to commit
subsequent branches and their associated pull requests need manual updates — a
tedious and error-prone task.
With a mechanism similar to code review tools like
Gerrit, Mergify CLI introduces a unique
Change-Id, into the commit message. This identifier is
managed via a git commit-msg hook, ensuring systematic tracking of changes.
Here's a glimpse of the
The tool utilizes the GitHub API to manage the pull requests, ensuring that your local git repository remains pristine.
For Mergify CLI to function effectively, branches must be in the
Streamlined Workflow: This process ensures that developers don't have to tediously update each individual pull request manually. Everything is managed under the hood by Mergify CLI, from the commit level to the PR level.
Reduced Errors: The automated nature of this approach minimizes the chances of human error—like missing a pull request update or misapplying a change.
Flexibility: Developers maintain the freedom and flexibility of the Git interactive rebase, allowing for granular and precise changes to commits.
Begin by installing the Mergify CLI using pip:
pip install mergify_cli
To use Mergify CLI for creating stacked pull requests in your repository, follow these steps:
- Execute the following command to set up the commit-msg hook:
mergify stack --setup
- Identify your trunk branch. This branch acts as the foundation for your stacked pull requests. You can configure it using:
git config --add mergify-cli.stack-trunk origin/branch-name
Alternatively, you can specify the trunk branch using the
- For GitHub API access, Mergify CLI requires a GitHub OAuth token. If you
have the gh client authenticated, Mergify CLI
will seamlessly fetch the token. If not, create a personal access
with necessary permissions and set it as an environment variable
GITHUB_TOKEN). You can also provide it directly using the
Spawn a branch and introduce your changes.
Commit the changes. If Mergify CLI is correctly configured, your commit message will automatically contain the
In case you committed before initializing Mergify CLI, use
git rebase <base-branch> -ito reword commits and automatically embed the
To construct the stack, run:
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.
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.
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.
Modifying Commits: To update or modify commits inside your branch:
Use the interactive rebase feature of Git:git rebase --interactive <base-branch>
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.
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
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.