Creating stacked pull requests

Create a stack of dependent pull requests using the gh stack extension in GitHub CLI or directly on GitHub.

In this article

Note

This feature is in public preview and subject to change.

Create stacked pull requests with the gh stack extension in GitHub CLI or on the GitHub website.

Note

Stacked pull requests require all branches to be in the same repository. Cross-fork stacks are not supported.

Creating a stack with GitHub CLI

  1. Initialize a stack. This creates and checks out the first branch on top of your trunk branch.

    Shell
    gh stack init BRANCH-NAME

  2. Write code for the first layer, then stage and commit your changes.

    Shell
    git add .
git commit -m "helpful-commit-message"

  3. Add a branch for the next logical unit of work. The new branch is created on top of the current one.

    Shell
    gh stack add BRANCH-NAME

  4. Write code and commit on the new branch. Repeat for each additional layer.

  5. Push all branches to the remote repository and create the stacked pull requests on GitHub.

    Shell
    gh stack submit

    Each pull request is created with the correct base branch, so reviewers see only the diff for that layer, and the pull requests are automatically linked together as a stack.

Creating a stack from the GitHub website

You can create a stack without the CLI by setting the base branch of each pull request to the branch below it.

  1. Create the first pull request as you normally would. Typically your base would target main.

  2. Create the next pull request and set its base branch to the first pull request's branch. Select the