maintain-fork-pr-merge
当合入 fork 来源的 PR 且 mergeStateStatus=CONFLICTING/DIRTY 时——先 git merge-tree 探测冲突清单,查 maintainer_can_modify,再在 worktree 隔离目录解冲突后 push fork 分支,勿因 CI 绿直接 merge
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 21
- Forks
- 4
01 前言 Front Matter
- name
- maintain-fork-pr-merge
- type
- Skill
- status
- stable
- metadata
- { "reason": "created from candidate materials", "source": "skill_creator", "summary": "fork PR 冲突时的维护者合入 SOP:merge-tree 探测 + worktree 隔离 + push fork", "revisions": [ "at: \"2026-09-06T11:43:46Z\"", { "at": "2026-09-06T11:45:12Z", "reason": "试用反馈:适用条件补 DRAFT 态 caveat(flag_issue skill-ineffective)", "source": "skill_creator" }, { "at": "2026-09-06T11:46:06Z", "reason": "drift 验证轮", "source": "skill_creator" }, { "at": "2026-09-06T11:50:16Z", "reason": "移除 drift 验证临时段,恢复正式正文", "source": "skill_creator" } ], "source_refs": [ "wiki/scenarios/发布与依赖治理方法.md", "notes/2026-08-26-fork-来源的-pr-与目标分支冲突时的维护者合入流程merge-tree-探测-worktree-push-fork.md" ], "installed_at": "2026-09-06T11:50:20Z", "installed_to": ".codebuddy/skills/maintain-fork-pr-merge/", "installed_hash": "sha256:3aa4f3725ce83a7c9c83531a737828dd674039eb7734fbaf1fc5d23f15db670e" }
- generated
- { "at": "2026-09-06T11:43:46Z", "by": "codewiki/5.6.1" }
- description
- 当合入 fork 来源的 PR 且 mergeStateStatus=CONFLICTING/DIRTY 时——先 git merge-tree 探测冲突清单,查 maintainer_can_modify,再在 worktree 隔离目录解冲突后 push fork 分支,勿因 CI 绿直接 merge
- stale_after
- 1796428800000
03 SKILL.md 正文
工作场景
维护者合入外部贡献者从 fork 发起的 PR,且 PR 分支与目标分支存在冲突(mergeStateStatus=CONFLICTING/DIRTY)。本仓的典型情境:评审期间 develop 又合入了新提交,导致 fork PR 的改动与主线重叠。
适用条件
- PR 的 head 分支在贡献者 fork 仓库中(isCrossRepository=true),本地
git fetch <pr-branch>会 404 gh pr view --json mergeable,mergeStateStatus显示 CONFLICTING 或 DIRTY- 注意:此时 CI 检查可能是全绿——CI 通过不等于可合并,以 mergeStateStatus 为准
- mergeStateStatus=DRAFT(CI 未跑完)时先等结果再探测冲突,勿提前判定
核心 SOP
- 探测冲突清单:
git merge-tree --write-tree --name-only <base> <head>——无需真实 checkout/merge 即可拿到冲突文件列表 - 确认可否代改:
gh pr view --json isCrossRepository,headRepository;fork PR 合入前查gh api repos/<owner>/<repo>/pulls/<n> --jq .maintainer_can_modify——为 false 时只能请作者解决或换合并策略 - 隔离解冲突:工作区有未提交改动时,用
git worktree add <tmp> <head> -b <branch>在独立目录解决冲突,不污染主工作区 - 更新 PR 分支:冲突解决后
git push https://github.com/<fork-owner>/<repo>.git <local-branch>:<pr-branch>(maintainer_can_modify=true 时 GitHub 允许维护者推 fork 的 PR head) - 收尾清理:
git worktree remove --force+git branch -D,再gh pr merge --merge
判断逻辑
- mergeStateStatus=DIRTY ≠ CI 失败:先看冲突字段,不要先怪 CI
- 主工作区是否常驻未提交改动决定是否必须走 worktree:常驻则必须隔离
- maintainer_can_modify 是代改的前提闸门:false 时一切 push fork 方案不可行
禁忌与反模式
- 不要直接在主工作区 checkout PR 分支解冲突(污染未提交改动)
- 不要因 CI 绿就点 merge(mergeStateStatus 会拒绝,但先探测可省一轮)
- 不要试图 fetch fork 的分支名到本地远程(不在主仓库,fetch 404 是预期行为)
- maintainer_can_modify=false 时不要尝试 push fork(无权限,会失败)
04 同仓库更多 Skills
write-doc-file-content-file-sidechannel
write_doc_file 建档报目标路径已被手写文件占用/路由冲突时——走 content_file 临时文件侧通道:正文写临时文件→删占位文件→write_doc_file(content_file=...) 正式建档→删临时文件
windows-python-release
当要手动发布 Python 包(codewiki-plus)到 PyPI 并建 GitHub Release 时——CI 不发布、Windows 控制台为 GBK、可能无 gh CLI、本机网络对 upload.pypi.org 的 Python TLS 握手有干扰——先核对 tag 区间与工作区未提交改动定 bump 级别,再按 8 步主干执行:同步四处版本→bump 提交(只 add 具体文件)→聚焦+ruff+全量闸门→清 dist 构建→PR 合并 main→tag merge commit 建 Release→uv publish(TLS 超时则 curl.exe 直传)→PyPI JSON API 核对
windows-dev-env
Windows/PowerShell 下做 git 写操作、跑子进程或批量文件/测试清理时:shell 漂移与中文路径致命令静默失败、无控制台宿主子进程闪窗、GCM 每次弹 OAuth 框、原生 DLL 被锁——须显式复核落盘、subprocess 加 CREATE_NO_WINDOW、gh auth setup-git 持久化凭据,并用 cmd /c 绕 safe-delete 钩子
repowiki-conclusion-update
已落库 repowiki 结论发生变化时,按「结论方向 vs 表述」分流:方向变则新写 decision 笔记+reject_note 旧+confirm 并回源 ADR,仅表述/证据变则 edit_doc_file 原地改
git-commit-hygiene
在共享 worktree 多会话并行或暂存区有残留时提交代码——用显式 pathspec 只提交自己的文件并排除临时目录,禁止 git add -A 或裸 commit 扫入并行会话的改动
writing-shape
Writing, exploit: shape raw material into an article, paragraph by paragraph.