Snippets

Appearance

Using Stacks ​

Stacked PRs are a way to better manage large pull requests by breaking them down into smaller, more manageable pieces. As a super high level overview we can think of a stack PR being a PR per commit, with each PR then targeting the previous PR in the stack. This allows for a more granular review process, as each PR can be reviewed and merged independently, while still maintaining the overall context of the larger change.

Requirements ​

The GitHub CLI is required to use stacked PRs. You can install it from here, or use the commands below:

bash
brew install gh
bash
winget install --id GitHub.cli

We also need to enable the stacked PRs feature in the GitHub CLI. This can be done by running the following command:

bash
gh extension install github/gh-stack

We also need to be authenticated with GitHub. You can do this by running the following command:

bash
gh auth login

Creating a Stack ​

To create a stack open up the repository and then when checked out in the default branch, run the following command:

bash
gh stack init

The command will ask you for the first branch in the stack (e.g. my-feature-branch)

Adding to the Stack ​

Once you are happy with the first part of the stack you can add a new branch to the stack by running the following command:

bash
gh stack add

The command will ask you for the name of the new branch (e.g. my-feature-branch-part-2) and will create a new branch based on the previous branch in the stack.

Viewing the Stack ​

Run gh stack view to see the current stack of PRs. This will show you the list of branches with some other details, and also allow you to switch to the appropriate branch in the stack using the terminal.

Push and Submit ​

Ideally we just push the stack at once, or when it's ready, which we can do with gh stack push. To create the appropriate PRs for each branch in the stack, we can run gh stack submit. This will create a PR for each branch in the stack, with each PR targeting the previous PR in the stack.

The UI can be used to edit names of PRs and set descriptions or even to toggle status (or inclusion) of PRs in the stack. Press CTRL + S to save changes and push the stack

Handy Commands ​

gh stack add -Am "MESSAGE": Add a new branch to the stack with a commit message and all files staged. This is useful for quickly adding a new branch to the stack without having to manually create a commit.