Skip to content

Commit f100cfc

Browse files
skarimskarim
committed
more faq content
1 parent fe887eb commit f100cfc

1 file changed

Lines changed: 76 additions & 35 deletions

File tree

‎docs/src/content/docs/faq.md‎

Lines changed: 76 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,6 @@ title: FAQ
33
description: Frequently asked questions about GitHub Stacked PRs.
44
---
55

6-
:::note
7-
This FAQ is a work-in-progress. Detailed answers will be added soon.
8-
:::
9-
106
## Creating Stacked PRs
117

128
### What is a stacked PR? How is it different from a regular PR?
@@ -27,33 +23,59 @@ gh stack add api-routes
2723
gh stack submit
2824
```
2925

30-
Or you can create stacked PRs manually by setting each PR's base branch to the branch of the PR below it.
26+
You can also create stacks entirely from the GitHub UI — create the first PR normally, then when creating subsequent PRs, select the option to add them to a stack. See [Creating a Stack from the UI](/gh-stack/guides/ui/#creating-a-stack-from-the-ui) for a walkthrough.
3127

3228
### How do I add PRs to my stack?
3329

3430
Use `gh stack add <branch-name>` to add a new branch on top of the current stack. When you run `gh stack submit`, a PR is created for each branch and they are linked together as a Stack on GitHub.
3531

32+
You can also add PRs to an existing stack from the GitHub UI. See [Adding to an Existing Stack](/gh-stack/guides/ui/#adding-to-an-existing-stack) for details.
33+
3634
### How can I modify my stack?
3735

3836
Reordering or inserting branches into the middle of a stack is not currently supported. To restructure a stack, you need to delete it and recreate it with the desired order.
3937

4038
### How do I delete my stack?
4139

42-
<!-- TODO: Update once stack deletion workflow is finalized -->
43-
44-
You can unstack a stacked of PRs from the PRs UI on the web. Functionality to do this from the CLI will be coming soon.
40+
You can unstack PRs from the GitHub UI — see [Unstacking](/gh-stack/guides/ui/#unstacking) for a walkthrough. This dissolves the association between PRs, turning them back into standard independent PRs. CLI support for unstacking is coming soon.
4541

4642
### Can stacks be created across forks?
4743

48-
<!-- TODO: Add answer once fork support is confirmed -->
49-
5044
No, stacked PRs currently require all branches to be in the same repository. Cross-fork stacks are not supported.
5145

46+
## Checks, Rules & Requirements
47+
48+
### How are branch protection rules evaluated for stacked PRs?
49+
50+
Every PR in a stack is treated as if it is targeting the **base of the stack** (typically `main`), regardless of which branch it directly targets. This means:
51+
52+
- **Required reviews** are evaluated as if the PR is targeting the stack base.
53+
- **Required status checks** are evaluated as if the PR is targeting the stack base.
54+
- **CODEOWNERS** are evaluated from the stack base — changes in codeowners on a PR at the bottom of the stack will not affect PRs above it in the stack.
55+
- **Code scanning workflows** are evaluated as if the PR is targeting the stack base.
56+
57+
### How do GitHub Actions work with stacked PRs?
58+
59+
GitHub Actions workflows trigger as if each PR in the stack is targeting the base of the stack (e.g., `main`). If you have a workflow configured to run on `pull_request` events targeting `main`, it will run for **every PR in the stack** — not just the bottom one.
60+
61+
### Do all previous PRs need to be passing checks before I can merge?
62+
63+
Yes. In order to merge a PR in the stack, **all PRs below it** must also have passing checks and meet all merge requirements. For example, in a stack of `main <- PR1 <- PR2 <- PR3` and you want to merge PR #3, both PR #1 and PR #2 must have passing checks, required reviews, and satisfy all branch protection rules.
64+
65+
### Is a linear history required?
66+
67+
Yes. There must be a **fully linear history** between each of the branches in the stack. This is a strict requirement for merging.
68+
69+
If the stack is not linear (e.g., after changes were pushed to a lower branch), you can fix it in two ways:
70+
71+
- **From the CLI** — Run `gh stack rebase` to perform a cascading rebase locally and then push with `gh stack push`.
72+
- **From the UI** — Click the **Rebase Stack** button in the merge box to trigger a cascading rebase across all branches in the stack.
73+
5274
## Merging Stacked PRs
5375

5476
### What conditions need to be met for a stacked PR to be mergeable?
5577

56-
The same conditions as any PR targeting the final target branch (e.g., `main`) — required reviews, passing CI checks, CODEOWNER approvals, etc. These rules are evaluated against the final target branch, not the direct base branch of the PR.
78+
Every PR in a stack must meet the same merge requirements as a PR targeting the stack base (e.g., `main`): required reviews, passing CI checks, CODEOWNER approvals, and a linear history. All PRs below it must also meet these requirements. See the [Checks, Rules & Requirements](#checks-rules--requirements) section above for details.
5779

5880
### How does merging a stack of PRs differ from merging a regular PR?
5981

@@ -65,25 +87,41 @@ You cannot merge a PR in the middle of the stack before the PRs below it are mer
6587

6688
### How does squash merge work?
6789

68-
Squash merges are fully supported. Each PR in the stack produces one clean, squashed commit when merged. The rebase engine automatically detects squash-merged PRs and uses `--onto` mode to correctly replay commits from the remaining branches.
90+
Squash merges are fully supported. Each PR in the stack produces one clean, squashed commit when merged. The rebase engine automatically detects squash-merged PRs and replays commits from the remaining branches onto the squashed result.
6991

70-
### What happens if you close a PR in the middle of the stack?
92+
### How does merge commit work?
7193

72-
<!-- TODO: Add specific behavior details -->
94+
When you merge a stack using the merge commit strategy, it creates **one merge commit for the entire group** of PRs being merged. The full commit history of each PR is preserved within the merge commit.
7395

74-
Closing a PR in the middle of the stack does not automatically affect the other PRs. However, the stack relationship is preserved, so the PRs above the closed PR will still target the closed PR's branch.
96+
### How does rebase merge work?
7597

76-
### What happens when there is an error merging a PR in the middle of a stack?
98+
With rebase merge, all of the commits from each PR in the stack are replayed onto the base branch one at a time, creating a linear history without merge commits.
99+
100+
### Do all PRs get merged at once or one at a time?
101+
102+
PRs in a stack are merged sequentially, from the bottom up. When you initiate a merge, the bottom PR is merged first, and then the next PR above it, and so on.
103+
104+
There will not be a single push operation that adds all the commits from all the branches at once.
105+
106+
### Can I merge only part of a stack? What happens to the remaining unmerged PRs?
107+
108+
Yes, partial stack merges are supported. After the merge, the lowest unmerged PR is updated to explicitly target the stack base (e.g. `main`). A cascading rebase is also automatically run to rebase the remaining unmerged branches.
109+
110+
### What happens if you close a PR in the middle of the stack?
77111

78-
<!-- TODO: Add specific error handling details -->
112+
Closing a PR in the middle of the stack will block all PRs above it from being mergeable. The stack relationship is preserved, so if you want to open a different PR or modify the stack, you will need to unstack and then recreate the stack.
113+
114+
### What happens when there is an error merging a PR in the middle of a stack?
79115

80116
If a merge fails (e.g., due to a failing check or merge conflict), the operation stops and no subsequent PRs are merged. You'll need to resolve the issue before continuing.
81117

82-
### What happens if auto-delete branches is enabled for PRs?
118+
### Does Stacked PRs support merge queue?
83119

84-
<!-- TODO: Add specific behavior details -->
120+
Yes, stacked PRs fully support merging via merge queue. When you merge a stack through the merge queue:
85121

86-
When a PR is merged and its branch is auto-deleted, the remaining stack is rebased so the next PR targets the appropriate base branch.
122+
- **All PRs in the stack are added to the queue** in the correct order, ensuring a linear sequence.
123+
- **If a PR is removed or ejected from the merge queue**, all PRs above it in the stack are also ejected and removed from the queue.
124+
- **Stacks can be split across merge groups** in the merge queue — not all PRs in the stack need to be in the same merge group.
87125

88126
## Local Development
89127

@@ -101,26 +139,29 @@ See the [CLI Reference](/gh-stack/reference/cli/) for the full command documenta
101139

102140
No. Stacked PRs are built on standard git branches and regular pull requests. You can create and manage them manually with `git` and the GitHub UI. The CLI just makes the workflow much simpler — especially for rebasing, pushing, and creating PRs with the correct base branches.
103141

104-
### Will this work with a different tool for stacking (jj / Sapling / ghstack / git-town, etc.)?
142+
### Will this work with a different tool for stacking?
105143

106-
<!-- TODO: Add compatibility details -->
144+
Yes, you can continue to use your tool of choice (e.g. jj, Sapling, ghstack, git-town, etc.) to manage stacks locally and push up your branches to GitHub.
107145

108146
Stacked PRs on GitHub are based on the standard pull request model — any tool that creates PRs with the correct base branches can work with them. The `gh stack` CLI is purpose-built for the GitHub experience, but other tools that manage branch chains should be compatible.
109147

110-
<!-- ## Miscellaneous -->
111-
112-
<!-- ### Do you have a VS Code extension? -->
113-
114-
<!-- TODO: Add answer -->
148+
You can also use the GitHub CLI in conjunction with other tools to simply create a stack of PRs:
115149

116-
<!-- ### Will stacked PRs work with the GitHub mobile app? -->
150+
```bash
151+
# Create a stack of branches locally using jj
152+
jj new main -m "first change"
153+
jj bookmark create change1 --revision @
154+
# ...
117155

118-
<!-- TODO: Add answer -->
156+
jj new -m "second change"
157+
jj bookmark create change2 --revision @
158+
# ...
119159

120-
<!-- ### Will stacked PRs work with the GitHub Desktop app? -->
160+
jj new -m "third change"
161+
jj bookmark create change3 --revision @
162+
# ...
121163

122-
<!-- TODO: Add answer -->
123-
124-
<!-- ### What happens if I merge via the REST or GraphQL APIs? -->
125-
126-
<!-- TODO: Add answer -->
164+
# Use gh stack to submit a stack of PRs
165+
gh stack init --adopt change1 change2 change3
166+
gh stack submit
167+
```

0 commit comments

Comments
 (0)