Index of every page on this site: llms.txt
All skills
cat-xierluo avatar

/git-workflow

@5fb69a0
Run it yourself

Git 工作流安全助手。用于分支与 worktree 管理、主目录 main 防切换保护、Skill 稀疏检出、PR 创建/审查/合并,以及提交身份和隐私检查;也支持 CI 额度治理、敏感文件历史撤回与仓库瘦身。不要用于批量生成提交信息、项目任务分配或本地 Agent 会话编排。

Use this Skill: https://skilld.dev/gh/cat-xierluo/legal-skills/git-workflow

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencespr-workflow.md

≈2.9k tokens on demand. Your agent reads this file only when SKILL.md points to it.

PR 创建、审查与合并

创建、审查、合并或更新 PR 时读取本页。先满足共同约束;完整历史、精确文本与例外格式只在隐私预检维护;标题和 Issue 语义见命名格式。

0. 按分支角色确定 PR 路径

先读 分支命名,再核任务合同中的实际角色与完整目标;名称和目标冲突时先对账,不能只靠前缀选 base。

分支角色 创建与更新 Ready / 合并门槛 交付后的去向
独立短任务 同一任务、同一目标复用一个有效 PR,base 为声明主干;默认 Draft,已验且授权满足再转 Ready 本项范围、实际验证及本页通用门禁满足;短不等于免验 证明交付后按清理合同处理短分支/树
里程碑短子任务 base 为完整父里程碑分支;正文关联父任务/已有父 PR,不能默认 main 本子项独立验收;进入父线不代表整体可发布 子任务可独立收尾,父线及其树继续保留
里程碑整体 首个可审阅提交出现且已有发表授权时,建议开唯一 Draft 主干 PR;返修持续更新同一 PR 里程碑范围、观察证据、最终候选及通用门禁全部满足,才转 Ready/合并 核主干交付及本机稳定入口,再判结案或具名下一里程碑;删除另核

不提交空 PR 来占位,不因换会话或每轮返修重复建 PR;第一次网络返回不明先查同一 head/base/任务的已有 PR。父 PR 尚未创建时,子 PR 关联真实父任务与完整父分支即可,不伪造 PR 编号。同一短任务直接交付两种目标确有 backport 等需求时,分别记录目标和采用关系,不能把重复 PR 当作默认迭代手段。

正文应让接手者能直接判断

沿用下一节的摘要、验证、归属与来源要求,再按角色补足:

  • 所有 PR:分支角色(独立任务/里程碑子任务/里程碑整体)、实际目标、允许范围与不包含的内容。结论对应当前 head,不把旧版本通过沿用成新 head 通过。
  • 子 PR:父任务/父分支/已有父 PR,自己交付什么、还有哪些依赖,子项完成是否影响父线观察候选。
  • 里程碑整体:纳入与排除子项、固定观察候选与最终 head 的关系、实际运行/失败/返修证据、尚未验证的范围、下一复核节点,以及本轮完成后结案还是继续下一目标。无证据时保持 Draft;约定一周到期不等于自动 Ready。

任务源维护当前阶段与 owner,PR 描述保留本次交付说明和对应证据链接,不复制全量内部任务流水。字段要求是协作合同,不表示 safe-pr.py 已能机械校验这些语义。

合并、关闭、删除分别判断

  • 合并表示已通过审查并交付到实际 base。子 PR 合入父线只结算该子项;父里程碑未整体达标时继续保留,不能报已进入 main。
  • 关闭但不合并适用于取消、被取代或决定不采用;需已获关闭授权,说明原因、替代 PR(如有)及未采用成果去向。因等待观察、暂时冲突或超过计划日期,不自动关闭。取消的观察记录和失败证据保留。
  • 删除分支/工作树是另一次资源处置,沿 生命周期合同核当前 tip、交付、dirty/ignored/占用与授权。合并默认不带 delete-branch;关闭 PR 不等于允许删未交付成果。删除失败记 CLEANUP_PENDING,不重放已完成合并。
  • 里程碑结案先核实际主干结果、交付范围内共享加载入口的采用(如适用)和剩余工作,再选择结束或具名续线。没有下一目标不无限维持“活跃”状态,但结案标记也不能跳过删除门禁。远端交付、本机采用和资源清理分别记录。

1. 创建与后验

确认授权、目标仓库、真实 PR base 和独占 head 分支;先按身份与推送使用 safe-push 推送已核不可变 OID。Python 3.10+、Git 和已认证 gh 必须可用,缺失时停止,不绕过 helper。

将最终单行标题与完整正文写入仓外或 Git 管理目录的文件,再运行:

python3 "$git_workflow_dir/scripts/safe-pr.py" create \
  --base '<已核真实目标分支>' --head '<branch-name>' --expected-head '<完整已核 head OID>' \
  --title-file '<最终标题文件>' --body-file '<最终正文文件>'

默认 draft,不用 --fill 或自动拼接未经核验的历史说明。创建后立即检查返回 URL、head/base、完整标题正文及状态;宿主要求附加 PR 到任务时使用其原入口。API 创建没有原子 head 条件,后验失败或网络结果不明时先只读确认,不能盲目再建。

PR 正文最低要求:摘要、实际测试及未验原因、Agent 归属(如适用:ID/作者/触发来源)、关联 Issue 或项目任务。迁移、删除、权限、安全、跨模块变更补风险与回退方式;缺摘要或测试计划不 approve,Agent 归属缺失先补齐。

提 PR 前可在独占候选运行 bash "$git_workflow_dir/scripts/pre-worktree-check.sh" --pre-pr <branch>,以 Git 2.38+ 的 merge-tree --write-tree 预演 base/head 冲突;该 helper 会 fetch,merge-tree 可写对象但不改检出或 index。本地预演干净不代替创建后的真实 mergeable 和最终 CI 后验。

2. 审查与隔离验证

审查者只在隔离候选/一次性 fixture 验证命令;需要主目录安装证据时由具名集成者提供只读版本与哈希。主目录禁入、快照与实际强制保护的边界统一见主目录合同,不在本页另建例外。

外部贡献先核需求来源和项目契合度(Issue、任务源、路线图或核心用途),再投入代码深审。需求证据缺失时保留待讨论,不自动关闭或发送评论;用户已授权处置时才执行。项目答案不能从“代码看起来正确”推断。

读取完整 diff 和文件清单,核与声明范围一致;Monorepo 不带入无关目录、未解释的大量删除、敏感配置或无法关联的 lock/schema/迁移/生成物,版本与索引须一致。

本地测试优先复用适合的隔离树,不能在共享主源 gh pr checkout。新树先核真实 PR head 与所需范围;Skill/套件按稀疏合同从创建时控制检出,不先全量落盘。原主树有 merge/rebase/dirty 时保留原归属,不为审查他人 PR 自行 abort/reset。

验证错误与 PR diff 对不上时,核实际 root、HEAD、环境和残留状态,在独立候选复跑再归因。不默认链接共享 node_modules 或重新安装依赖;存在项目明确复用方案时核可写性和测试副作用。本人创建的试验按其归属完成或安全中止,记录真实结果。

3. 合并前门禁

以下查询用于只读核对,不能替代独立 review 和实际测试:

gh pr view '<N>' --json title,state,isDraft,mergeable,reviewDecision,headRefOid,headRefName,baseRefName
gh pr diff '<N>' --name-only
gh pr diff '<N>'
gh pr checks '<N>'

任一条件不满足则停止:

  • PR 是 OPEN 且非 draft;仅在授权和验收满足后,使用 gh pr ready '<N>' --repo '<owner/repo>' 将同一个 PR转为 ready,保留原编号与审查记录。不要为转 ready 关闭或重建 PR;gh pr edit 没有 --remove-draft 并不表示必须另建 PR。标准入口见 GitHub CLI 官方手册。
  • 转换前固定当前 PR 的 number/headRefOid/baseRefName;转换后重新读取同一 PR,核 state=OPEN、isDraft=false 且 head/base 未变,再继续原有 review/CI/合并门禁。ready 不代表已获合并授权或检查通过。
  • 转换失败或网络结果不明时,先只读回查同一 PR;仍为 draft 或无法确认则停止并保留现场,交原 owner 排查权限/CLI。不得以关闭重建绕过失败,也不尝试未验证的 REST draft PATCH。
  • mergeable 明确可合并,完整 diff 可读,范围与删除解释已核。
  • 独立 review 有明确 verdict,分支保护和 required checks 满足;CHANGES_REQUESTED、结论矛盾或只有摘要均未通过。
  • 最终 head 的 checks 明确通过。失败、等待、未知或读取失败不合;仓库明确无需某项检查时核实际保护与项目合同,不能把缺失自行判 PASS。
  • 当前 head/base、实际验证、最终完整文本与受审候选相同;候选变化后复验。

GitHub 不允许作者自 approve。仓库无需 GitHub approval 时可使用真实不同角色、绑定当前候选的独立审查;保护要求他人 approval 时按规则满足,不使用 admin override。

4. 精确合并与收口

授权、review、CI 和范围门均满足后使用:

python3 "$git_workflow_dir/scripts/safe-pr.py" squash --number '<N>' \
  --expected-head '<完整已审核 head OID>' \
  --title-file '<最终 squash 标题文件>' --body-file '<最终 squash 正文文件>'

最终标题包含 (#N)(已有不重复),API 自定义标题不会自动加编号;当前 PR 标题/正文、每笔历史与最终 squash 说明都须精确检查。helper 的 head 绑定不代替 review/CI/授权。其他合并方法/API 也检查相同范围及最终文本,不能依赖自动生成说明。

用户明确要保留多个原子 commit 时按原意选择合并方法,仍满足所有门禁,不强制 squash。所谓“把 PR 拉进 main”默认核正式服务端交付;不得用 fast-forward pull 代替 PR 来源记录和验收,也不能把 CLOSED 称为 MERGED。本地采用遵循改动集成。

完成后读取真实 MERGED、mergedAt、mergeCommit 和目标侧内容。main 被另一树占用或 cleanup 报错时先对账,区分云端合并、本机待同步与清理失败;不切换/删除别人的树,不重放已完成合并。生命周期合同维护清理、批量验收与取代旧 PR 的授权和覆盖关系,合并默认不附删除参数。

5. base 落后、冲突与未知状态

创建后立即读取 mergeable/mergeStateStatus/baseRefName/headRefName,不要等待下一轮才发现过期基准。MERGEABLE/CLEAN 仅表示无合并冲突,仍须 review/CI;UNKNOWN 不等于只是 CI 慢,先查服务端计算、权限与检查状态。

场景 处理
BEHIND、无内容冲突 核原 head owner、项目同步策略及授权,再更新 base;不能盲目 update-branch
共享文档冲突 保留双方有效记录,串行分配版本/编号,按文件解决;未发表短分支可按项目策略 rebase,已发表历史须另核授权
代码冲突或旧候选带入无关差异 按授权在最新目标开隔离窄采用候选,保留原 PR/分支及来源映射;覆盖和未采用处置完成后按取代合同关闭
少量集中冲突 按文件解决,核最终 message/patch/blob;网页处理同样核发布文本、实际服务端结果和候选

长期功能线只在波次边界 merge 主干,不 rebase/reset/force。冲突不自动授权关 PR、删分支、重建同名 head 或裸 force push;safe-push 当前不支持 force,拒绝时保留成果按已授权路径处理。

6. 项目扩展

文档体检等扩展仅沿项目已有接口及授权衔接。其阈值、状态、可改目录、维护 PR 与调用时机归项目维护;不因 PR 创建/合并自动授权新任务、消息或外部写入,不能替代本页门禁。

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts18d3 checks · Risk SAFE
  • Gen Agent Trust Hub18d

    The git-workflow skill is a security-focused toolset for managing Git workflows. It provides robust mechanisms for branch and worktree management, identity auditing, and privacy pre-commit checks. The skill uses standard local tools (Git and GitHub CLI) to enhance development safety, prevent data leakage, and ensure identity consistency across projects without any suspicious external communications or malicious behaviors.

  • Socket18d

    No alerts

  • Snyk18d

    Risk: LOW · No issues

Signed by skilld at 5fb69a0. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 days ago
Other metadata
metadata
{
  "version": "1.27.1",
  "homepage": "https://github.com/cat-xierluo/legal-skills",
  "author": "杨卫薪律师(微信ywxlaw)"
}

README badge

README badge for cat-xierluo/legal-skills/git-workflow