merging-stacked-prs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Landing an official GitHub PR stack

合并官方GitHub PR堆叠

Land dependent PRs through GitHub's native stack object and

gh stack merge

. Do not reproduce stack semantics by merging and retargeting individual PRs with

gh pr merge

and

gh pr edit

通过GitHub原生堆叠对象和

gh stack merge

合并存在依赖关系的PR。请勿通过

gh pr merge

和

gh pr edit

单独合并并重新定位PR来复现堆叠语义。

Require native stack support

要求原生堆叠支持

Run

gh stack --version

before changing GitHub state. Hard-stop if the official extension or server-side stack feature is unavailable; do not fall back to manually merging and retargeting PRs one at a time. GitHub stacks require every head branch to live in the same repository, so hard-stop on a cross-fork chain.

Use a clean dedicated worktree. Fetch current PR metadata and exact head OIDs rather than trusting branch names or an earlier report:

gh pr view <pr> --json number,author,baseRefName,baseRefOid,headRefName,headRefOid,isCrossRepository,state,isDraft,reviewDecision,mergeStateStatus,statusCheckRollup

Query

PullRequest.stack

and

stackEntry.position

for at least one PR in each apparent chain; this official GitHub object, not base-branch inference alone, is the stack-membership authority. Paginate

entries

when

size

exceeds the returned page:

gh api graphql -F owner=<owner> -F name=<repo> -F number=<pr> -f query='
query($owner: String!, $name: String!, $number: Int!) {
  repository(owner: $owner, name: $name) {
    pullRequest(number: $number) {
      number
      author { login }
      baseRefName
      headRefName
      stackEntry { position }
      stack {
        number
        baseRefName
        size
        entries(first: 100) {
          nodes {
            position
            pullRequest { number author { login } baseRefName headRefName state isDraft }
          }
        }
      }
    }
  }
}'

Establish the expected bottom-to-top order from the live PR bases: the bottom targets the trunk, and each higher PR targets the head branch immediately below it.

在修改GitHub状态前运行

gh stack --version

。如果官方扩展或服务器端堆叠功能不可用则立即终止操作；请勿退化为手动逐个合并并重新定位PR。GitHub堆叠要求所有头部分支都位于同一仓库中，因此跨派生仓库的依赖链需立即终止操作。

使用干净的专用工作树。拉取当前PR元数据和精确的头部OID，而非依赖分支名称或早期报告：

gh pr view <pr> --json number,author,baseRefName,baseRefOid,headRefName,headRefOid,isCrossRepository,state,isDraft,reviewDecision,mergeStateStatus,statusCheckRollup

查询每个可见链中至少一个PR的

PullRequest.stack

和

stackEntry.position

；这个官方GitHub对象是堆叠成员身份的权威依据，而非仅靠基础分支推断。当

size

超过返回页面时，对

entries

进行分页：

gh api graphql -F owner=<owner> -F name=<repo> -F number=<pr> -f query='
query($owner: String!, $name: String!, $number: Int!) {
  repository(owner: $owner, name: $name) {
    pullRequest(number: $number) {
      number
      author { login }
      baseRefName
      headRefName
      stackEntry { position }
      stack {
        number
        baseRefName
        size
        entries(first: 100) {
          nodes {
            position
            pullRequest { number author { login } baseRefName headRefName state isDraft }
          }
        }
      }
    }
  }
}'

根据实时PR基础确定预期的从下到上顺序：最底层以主干为目标，每个上层PR以其正下方的头部分支为目标。

Link missing stack members

链接缺失的堆叠成员

First compare any existing stack entries with the expected chain. One existing stack may contain an order-preserving subset of the requested chain; multiple stack numbers, an unexpected entry, or a conflicting order requires user direction before any mutation.

When any dependent PR is not yet in that official stack:

Compare every
```
author.login
```
exactly.
If all authors match, link the chain automatically in bottom-to-top order:

gh stack link --base <trunk> <bottom-pr> <next-pr> ... <top-pr>

If authors differ or any author is unavailable, ask the user whether to link before changing GitHub state.
Re-query GraphQL and require one stack number, the expected trunk, the complete PR set, and the expected positions and base chain.

Never dissolve, reorder, or rebuild an existing stack automatically;

gh stack link

is additive and merged or queued entries cannot be unstacked.

首先将现有堆叠条目与预期链进行比较。一个现有堆叠可能包含请求链的保序子集；若存在多个堆叠编号、意外条目或冲突顺序，则在进行任何修改前需用户指示。

当任何依赖PR尚未加入该官方堆叠时：

精确比较每个
```
author.login
```
。
如果所有作者匹配，则自动按从下到上的顺序链接链：

gh stack link --base <trunk> <bottom-pr> <next-pr> ... <top-pr>

如果作者不同或任何作者不可用，则在修改GitHub状态前询问用户是否链接。
重新查询GraphQL，要求存在一个堆叠编号、预期主干、完整PR集合以及预期位置和基础链。

请勿自动解散、重新排序或重建现有堆叠；

gh stack link

是增量操作，已合并或排队的条目无法取消堆叠。

Refresh only when needed

仅在必要时刷新

Do not rewrite branches merely because a refresh mechanism exists. When the live merge state or repository rules require an updated trunk, choose either allowed history:

Native cascading rebase: check out the remote stack with
```
gh stack checkout <pr-or-stack>
```
when it is not tracked locally, then run
```
gh stack sync
```
. The command may rebase and lease-protected force-push every active layer before local validation. Immediately inspect the rewritten scope, run the relevant checks for every affected layer, and do not merge or claim readiness until they pass. If sync detects a rebase conflict, use
```
gh stack rebase
```
, resolve and validate it, then publish with
```
gh stack push
```
. If checkout or sync reports divergent local and remote stack compositions, cancel and ask rather than deleting or recreating the remote stack automatically.
Incremental merge-forward: merge the trunk into the bottom affected branch, then propagate each updated parent into its child in bottom-to-top order and push normally.

Any history rewrite is allowed after review, but it invalidates commit-OID assumptions. Re-fetch exact heads and re-audit unresolved review threads, approvals, mergeability, and checks after the push. Never use raw

--force

or overwrite a concurrently advanced remote head.

不要仅因为存在刷新机制就重写分支。当实时合并状态或仓库规则需要更新主干时，选择以下两种允许的历史处理方式之一：

原生级联变基：当远程堆叠未在本地跟踪时，使用
```
gh stack checkout <pr-or-stack>
```
检出远程堆叠，然后运行
```
gh stack sync
```
。该命令可能在本地验证前对每个活动层进行变基并通过租赁保护强制推送。立即检查重写范围，对每个受影响的层运行相关检查，在检查通过前不要合并或声明就绪。如果同步检测到变基冲突，使用
```
gh stack rebase
```
解决并验证冲突，然后通过
```
gh stack push
```
发布。如果检出或同步报告本地和远程堆叠结构存在分歧，取消操作并询问用户，而非自动删除或重建远程堆叠。
增量向前合并：将主干合并到最底层受影响的分支，然后按从下到上的顺序将每个更新的父分支传播到其子分支并正常推送。

任何历史重写需在审核后进行，但会使提交OID假设失效。推送后需重新拉取精确的头部，并重新审核未解决的评审线程、批准状态、可合并性和检查结果。请勿使用原始

--force

参数或覆盖同时推进的远程头部。

Preflight the merge range

预检查合并范围

Re-query the official stack immediately before merging. Require every selected PR to be open, non-draft, in the expected order, and compliant with the repository's review and check requirements. Treat each PR's state independently; a ready top layer does not prove its dependencies are ready.

"Land the stack" selects the whole stack. A partial landing requires an explicit boundary PR and includes every layer from the bottom through that boundary.

在合并前立即重新查询官方堆叠。要求每个选定的PR处于开放状态、非草稿、符合预期顺序，并满足仓库的评审和检查要求。独立处理每个PR的状态；顶层PR就绪并不意味着其依赖项也已就绪。

“合并堆叠”会选择整个堆叠。部分合并需要明确的边界PR，并包含从最底层到该边界的所有层。

Merge through the stack API

通过堆叠API合并

Merge the whole stack by its official stack number:

gh stack merge <stack-number> --yes --merge

For an explicitly requested partial landing, merge through the boundary PR:

gh stack merge <boundary-pr> --yes --merge

Do not pass

--delete-branch

, manually retarget dependents, or issue per-PR merge commands. GitHub merges the selected range bottom-up and retargets or rebases any remaining upper layers. A direct stack merge is all-or-nothing; when the trunk uses a merge queue, GitHub queues the selected range together but may land it in separate groups.

Do not bypass merge requirements. If the native merge reports a blocker, inspect and resolve that blocker through the owning PR or stop and report it; never fall back to

gh pr merge

通过官方堆叠编号合并整个堆叠：

gh stack merge <stack-number> --yes --merge

对于明确请求的部分合并，通过边界PR进行合并：

gh stack merge <boundary-pr> --yes --merge

请勿传递

--delete-branch

参数、手动重新定位依赖项或发出单个PR的合并命令。GitHub会自下而上合并选定范围，并重新定位或变基任何剩余的上层。直接堆叠合并是全有或全无的；当主干使用合并队列时，GitHub会将选定范围一起排队，但可能分组合并。

请勿绕过合并要求。如果原生合并报告存在阻塞问题，通过所属PR检查并解决该问题，或终止操作并报告；请勿退化为使用

gh pr merge

。

Verify the landed state

验证合并状态

Wait for every selected PR to report

MERGED

; a queued request is not a completed landing:

gh pr view <pr> --json number,state,mergedAt,mergeCommit,baseRefName,headRefName

For a partial landing, re-query the official stack and verify that every remaining PR is still linked in the expected order and targets the stack trunk or the layer below it. Re-check current heads, review state, and CI because GitHub may have rebased the remaining layers.

Delete branches only in a separate final pass after the corresponding PRs report

MERGED

. Before deleting each branch, require GitHub to report no open PR still using it as a base:

gh pr list --state open --base <branch> --json number --jq length

Anything other than

blocks deletion.

等待每个选定的PR报告

MERGED

；排队请求不代表合并完成：

gh pr view <pr> --json number,state,mergedAt,mergeCommit,baseRefName,headRefName

对于部分合并，重新查询官方堆叠并验证所有剩余PR仍按预期顺序链接，且以堆叠主干或其下方的层为目标。重新检查当前头部、评审状态和CI，因为GitHub可能已变基剩余层。

仅在相应PR报告

MERGED

后，在单独的最终步骤中删除分支。删除每个分支前，要求GitHub报告没有开放PR仍将其用作基础：

gh pr list --state open --base <branch> --json number --jq length

任何非

的结果都会阻止删除。

Checklist

检查清单

Native
```
gh stack
```
support is available; every PR branch is in the same repository.
Live PR bases and exact heads establish one bottom-to-top dependency chain.
GraphQL reports one official stack with the expected trunk, entries, and order; an eligible same-author unstacked chain was linked automatically.
Any rewritten layers passed relevant validation, and review threads, approvals, mergeability, and checks were re-audited afterward.
The whole stack, or an explicitly bounded prefix, was submitted through
```
gh stack merge --yes --merge
```
.
Every selected PR reports
```
MERGED
```
; any remaining upper layers still form the expected official stack.
Branch deletion happened only after merged-state and zero-dependent verification.

原生
```
gh stack
```
支持可用；所有PR分支都位于同一仓库。
实时PR基础和精确头部确立了一条从下到上的依赖链。
GraphQL报告一个包含预期主干、条目和顺序的官方堆叠；符合条件的同一作者未堆叠链已自动链接。
所有重写的层都通过了相关验证，且之后重新审核了评审线程、批准状态、可合并性和检查结果。
整个堆叠或明确限定的前缀已通过
```
gh stack merge --yes --merge
```
提交。
每个选定的PR都报告
```
MERGED
```
；所有剩余上层仍构成预期的官方堆叠。
分支删除仅在验证合并状态和无依赖PR后进行。