{"meta":{"title":"Quickstart for stacked pull requests","intro":"Install the gh stack extension in GitHub CLI and create your first set of stacked pull requests.","product":"Pull requests","breadcrumbs":[{"href":"/en/pull-requests","title":"Pull requests"},{"href":"/en/pull-requests/get-started","title":"Get started"},{"href":"/en/pull-requests/get-started/stacked-prs-quickstart","title":"Stacked PRs quickstart"}],"documentType":"article"},"body":"# Quickstart for stacked pull requests\n\nInstall the gh stack extension in GitHub CLI and create your first set of stacked pull requests.\n\n> \\[!NOTE] This feature is in public preview and subject to change.\n\nUse stacked pull requests to break large code changes into a chain of smaller, dependent pull requests that you can review and merge independently.\n\nA stack is a series of pull requests in the same repository where each pull request targets the branch of the pull request below it, forming an ordered chain that lands on a single branch, typically your main branch. Instead of one large pull request, you get a set of smaller pull requests. Since each pull request has its own focused diff, teammates can review and approve each layer independently.\n\n## Prerequisites\n\n* GitHub CLI (`gh`) 2.90.0 or later, and Git 2.20 or later.\n  * Authenticate GitHub CLI with `gh auth login`.\n* A GitHub repository you can push to.\n\n## Install the CLI extension\n\n```shell copy\ngh extension install github/gh-stack\n```\n\n> \\[!TIP]\n> To use stacked pull requests with AI coding agents, like GitHub Copilot, install the `gh-stack` skill.\n>\n> ```shell copy\n> gh skill install github/gh-stack\n> ```\n\n## Create your first stack\n\n1. To initialize a stack, navigate to your repository and run the following command. This creates a tracking entry and your first branch.\n\n   ```shell copy\n   gh stack init\n   ```\n\n   You'll be prompted to name your first branch. By default, the stack uses your repository's default branch (e.g., `main`) as the trunk, but a stack can target any branch.\n\n2. Work on your first branch as usual: write code, stage changes, and commit.\n\n   ```shell\n   # ... write code ...\n   git add .\n   git commit -m \"helpful-commit-message\"\n   ```\n\n3. When you're ready for the next logical unit of work, add a new branch to the top of the stack.\n\n   ```shell copy\n   gh stack add BRANCH-NAME\n   # ... write code ...\n   git add .\n   git commit -m \"Another-helpful-commit-message\"\n   ```\n\n4. Push all branches to the remote.\n\n   ```shell copy\n   gh stack push\n   ```\n\n5. Create pull requests and link them as a stack on GitHub.\n\n   ```shell copy\n   gh stack submit\n   ```\n\n   Each pull request is created with the correct base branch. Your first branch targets `main`, and the next branch `BRANCH-NAME` targets the first branch. Reviewers will only see the diff for that layer. The pull requests are automatically linked together as a stack on GitHub and you can see their order and quickly navigate between them.\n\n6. View the stack and see the full state at any time.\n\n   ```shell copy\n   gh stack view\n   ```\n\n   This command shows all branches, their pull request links, statuses, and the most recent commit on each.\n\n7. Use `gh stack add -Am \"MESSAGE\"` to stage all changes, commit, and create the next branch in one step. You won't need a separate `git add` or `git commit`. If the current branch has no commits yet, the commit lands there; if it already has commits, a new branch is created.\n\n   ```shell\n   # Commit lands on the current branch\n   gh stack add -Am \"Auth middleware\"\n\n   # Current branch already has commits, so this creates the next branch\n   gh stack add -Am \"API routes\"\n   ```\n\n8. When you're ready, push everything and create the pull requests.\n\n   ```shell copy\n   gh stack submit\n   ```\n\n## Next steps\n\n* [Managing stacked pull requests](/en/pull-requests/how-tos/create-pull-requests/managing-stacked-pull-requests)\n* [Merging stacked pull requests](/en/pull-requests/how-tos/merge-and-close-pull-requests/merging-stacked-pull-requests)\n* [Stack AI-generated code in pull requests](/en/copilot/tutorials/stack-ai-generated-code-in-pull-requests)\n* [Roll out stacked pull requests to your organization](/en/pull-requests/tutorials/roll-out-stacked-prs)"}