Stacked pull requests

A stack is a set of pull requests built on one another: the bottom one merges into the default branch (usually main), the next one merges into the bottom one's branch, and so on. Splitting a large change this way keeps each pull request small enough to review.

You don't have to set anything up. When you open a pull request, Revue looks for its stack in the background. If the pull request is in a stack of two or more, a PR stack tab appears in the pull request's tab bar.

The PR stack tab#

The tab is the last one in the pull request's tab bar. Its label says where this pull request stands, counting from the bottom: PR stack 2/4 means it's the second of four.

The top of the tab sums up the stack, for example 4 PRs · 1 approved · 1 needs changes · merge order: #12 → #13 → #14. Below that a short line says how Revue found the stack (see How Revue finds a stack).

The graph reads from top to bottom:

• each pull request is a card, drawn above the one it's built on;
• the branch the stack merges into (for example main) is the last row, with a hollow dot;
• when two pull requests are built on the same one, the stack forks and the second one gets a lane of its own beside it.

The pull request you have open is marked This PR and has a highlighted border.

What a card shows#

Each card has:

• a coloured dot for the state: green open, grey draft, magenta merged, red closed;
• the number and title;
• a Merged, Closed or Draft tag when it isn't simply open;
• the review state: Approved, Changes requested or Waiting for review;
• a small dot with the CI status;
• the author, the branches (feature-b → feature-a), lines added and removed, and the number of commits;
• Needs rebase when the pull request below has moved on since this branch was started (only with a local clone, see below).

Hover a card for the same details in a list, plus how it relates to the one below: On #12: merges into its branch.

Right-click a card for Copy link, Open in browser and, when there is a Revue server for links, Copy Revue link (see Links and opening from anywhere).

Moving around the stack#

• Click a card to open that pull request. It opens in its own tab, and the one you came from stays open.
• Or use the keyboard: ↑ and ↓ move the selection between cards, and Enter opens the selected one.
• Press the tab's number key to get to the tab: 8 when Slack is connected, 7 when it isn't (the number keys pick tabs by position).

The refresh button at the top right, Look for the stack again, lists the repository's open pull requests afresh and rebuilds the graph.

Advanced: keys, refresh and when the tab disappears

• ↑, ↓ and Enter work only while the PR stack tab is showing and no text field has focus.
• Selecting the card of the pull request you're already on does nothing.
• Revue looks for the stack when the pull request loads, and again whenever its head or base branch changes (for example after the base was edited). A normal refresh reuses the repository's list of open pull requests if it was fetched in the last 5 minutes; Look for the stack again always fetches it again.
• While it's looking, the tab shows Looking for the PR stack…. If the lookup fails, the error shows in the tab, and a stack found earlier stays on screen.
• If a pull request turns out to be in no stack (any more), the tab is removed. If you were on it, Revue switches to the Files tab.
• The tab bar order is otherwise unchanged: the PR stack tab is always added at the end, so the other tabs keep their numbers.

Stack badges in the pull request list#

Once Revue has found a stack, the pull request list marks each of its pull requests with a small layers icon and its place, for example 2/4. Hover it for PR stack: 2 of 4.

Advanced: where the badges come from

• Badges come from stacks found while Revue is running: the list doesn't look for stacks itself. A pull request gets its badge once it, or another pull request of its stack, has been opened in this session.
• They aren't saved, so they start empty after a restart.

How Revue finds a stack#

Revue tries two ways, in this order, and the tab's info line says which one it used.

1. GitHub's own stacks. If GitHub keeps a stack for the pull request (GitHub's stacked pull requests), Revue shows that one. The info line says GitHub's stack #N.
2. Branch by branch. Otherwise Revue follows the branches: if this pull request merges into a branch that another pull request comes from, that one is below it, and so on down to the default branch. Going up, every open pull request that merges into this one's branch is above it. The info line says Found branch by branch: each PR's base is the branch of the one below. A stack exists only where branches point at each other. Pull requests that all merge into the same branch are no stack, even when one's branch was started from another's and so contains its commits: each of them can merge on its own. To make them a stack, change the upper pull request's base to the lower one's branch.

Per service

	GitHub	Bitbucket Cloud	Forgejo, Codeberg, Gitea
GitHub's own stacks	Yes, where the server offers them	No	No
Branch by branch	Yes	Yes	Yes

On a GitHub server without stacked pull requests (for example an older GitHub Enterprise Server), Revue quietly falls back to the branch-by-branch search.

Advanced: the rules and limits

• Only pull requests from branches of the repository itself count. A pull request from a fork whose branch happens to have the same name isn't part of the stack.
• Closed (unmerged) pull requests are left out. Merged ones are kept, so a stack whose bottom pull request is already merged still shows it.
• Merged pull requests aren't in the list of open ones, so when the bottom of the stack merges into a branch that no open pull request comes from, Revue looks up the pull requests of that branch and keeps going down through merged ones. It stops at the repository's default branch.
• When two pull requests come from the same branch, an open one is preferred over a merged one.
• For GitHub's own stacks, merged pull requests are also looked up by their branch, so their cards show the title, author and reviews. One Revue can't look up shows with what the stack says (number, state, branch).
• Revue reads the repository's open pull requests 50 at a time, up to 40 pages (2,000 pull requests). The same list is shared with the repository view's branches, and reused for 5 minutes.
• At most 20 pull requests are followed downwards, and a stack has at most 50 pull requests.
• Pull requests that point at each other in a circle are handled: the first one is put on the root branch so none is lost.
• When several pull requests sit side by side, lower numbers come first, and the line of the pull request you have open is drawn in the first lane.

Merging and rebasing a stack#

The summary's merge order lists the open pull requests of the stack in the order they can be merged, bottom first: #12 → #13 → #14. Merge them in that order, each from its own tab (see Reviews, approvals, merging and editing). Revue shows the order but doesn't merge or rebase the stack for you.

Needs rebase on a card means the pull request below has commits that this one's branch doesn't have yet, typically because the lower branch got new commits after review. Rebase (or merge) the lower branch into this one, push it, and refresh the stack.

Advanced: when Needs rebase is shown

• It needs a local clone, since it's answered by git in that clone. Without one, cards never show it. To use the local clone, Revue needs to know where it is: clone the repository from Revue or point Revue at an existing clone (see Clones, worktrees and opening in your tools).
• It's checked only between a pull request and the open one it merges into, not above a merged pull request.
• It uses the commits your clone knows about. If the clone doesn't have a commit (it hasn't been fetched), that card gets no mark. Fetch in the clone if the mark looks out of date.

Opening a pull request on top of another#

You can start or grow a stack from Revue's Open pull request form (see Opening a pull request).

1. Open the repository and go to its branches.
2. Click Open pull request on your branch.
3. Pick as the base the branch of the pull request you built on. If your branch was started from another open pull request's branch, Revue picks that base for you.
4. Check Start a pull request stack. The box says This pull request will be stacked with #12 … (click the link to see that pull request).
5. Open the pull request.

With the box checked, Revue adds a line Stacked on #12 at the end of the description. Once the new pull request is open, its PR stack tab shows it on top of #12.

Advanced: how the base is suggested

• Revue looks at the commits your branch has that the base doesn't. If one of them is the latest commit of another open pull request's branch, the nearest such branch becomes the base.
• This happens once per form, and never after you've picked a base by hand.
• Start a pull request stack shows only when the base is the branch of an open pull request (other than your own branch). It's checked automatically whenever the base changes to such a branch; uncheck it to leave the Stacked on #N line out. The base stays what you picked either way.