企业官网建设流程全解析

• 嵌入式
• 物联网
• 机器人
• 自动驾驶
• 智能硬件

导读

本文围绕 PX4-Autopilot 仓库中 AI 辅助开发流程的核心技能文档 .agents/skills/rebase-onto-main/SKILL.md，系统讲解如何将一个功能分支安全地 rebase 到main，并重点解决 PX4 维护实践中一个高频且易错的场景：父分支（feature 分支的上游分支）被 squash 合并进 main 后，如何在不重复回放已被继承的提交的前提下，仅重放当前分支独有的提交。你将掌握工作树/worktree 检查、git range-diff边界界定、--force-with-lease安全推送、备份引用（backup ref）等一整套可落地、可复用的 Git 操作流程，并能直接套用于 PX4 这类以 "squash merge + rebase merge" 为合并策略、追求线性提交历史的开源项目。

适用范围说明：本文操作命令基于 Git 标准 CLI，适用于在 PX4-Autopilot 任意克隆仓库（含 fork）中执行；文中涉及的 PX4 合并策略、提交规范等事实均来自当前仓库的 CONTRIBUTING.md 与 .github/instructions/code-review.instructions.md。

为什么需要 rebase-onto-main：PX4 的线性历史与合并策略

PX4 官方开发流程采用 GitHub flow 模型：新功能始终从main拉出分支，提交遵循 conventional commits 规范（type(scope): description），最终通过 pull request 合入。而仓库的代码审查指南 .github/instructions/code-review.instructions.md 明确了两条与本文直接相关的规则：

• 合并策略：Both squash merge and rebase merge are enabled; merge commits are disabled——即 PX4 允许 squash 合并与 rebase 合并两种方式，但不允许产生 merge commit，保证main上始终是线性历史；
• 提交整洁性：WIP or review-response commits should be squashed before merge——评审期间产生的 WIP、修改意见提交应在合并前 squash。

这两条规则直接催生了本文要解决的典型困境：

1. 你在本地有一个功能分支feature-a，它基于另一个正在开发中的分支parent-branch拉出（例如feature-a依赖parent-branch上的新 API）；
2. 维护者把parent-branch通过squash merge合入了main——squash 会把parent-branch上的 N 个提交压缩成main上的1 个新提交；
3. 此时若对feature-a执行普通的git rebase main，Git 会依据 patch-id 去重并尝试回放feature-a的全部提交——但 squash 后提交内容与原始提交的哈希完全不同，去重机制失效，极易导致feature-a中继承自parent-branch的提交被重复回放，产生重复 diff、冲突甚至错误代码。

rebase-onto-main技能的核心价值，就是在这类场景下只重放feature-a独有的提交，跳过那些已经被 squash 合并进main的继承提交。这正是该技能 description 中 "handling squash-merged parent branches without replaying inherited commits"（处理 squash 合并的父分支而不回放继承的提交）的含义。

前置检查：工作树、worktree 与输入分支确认

技能文档明确要求，在任何改写历史的操作之前，必须先确认环境状态。这一环节对应.claude/skills/rebase-onto-main/SKILL.md中 "Read ... and follow its workflow with these adaptations" 的适配要求，也是整个流程的安全底线。

1. 明确输入分支

输入是用户请求中指定的分支，若用户未指定，则默认为当前分支。注意技能文档特别强调：Do not interpret $ARGUMENTS as a shell variable——即不要把$ARGUMENTS当作 shell 变量展开，而要当作字面的分支名或用户话语来解析。

# 查看当前所在分支 git branch --show-current

2. 检查工作树与 worktree

先检查工作区是否干净、是否存在多个 worktree，并确认目标分支归属哪个 worktree：

# 查看所有 worktree 及其所在分支 git worktree list # 查看工作区状态（是否存在未提交改动） git status

技能文档的适配要点强调：

• 保留无关改动（Preserve unrelated changes），不要自动 stash 用户的工作；
• 在拥有该分支的 worktree 中执行 rebase（run in the worktree that owns the branch）；
• 若main被另一个 worktree 检出，则不要直接更新那个已检出的分支，而是 fetchorigin main，以origin/main作为新基线。

# 拉取远程 main 的最新提交（即使本地有其他 worktree 检出 main 也安全） git fetch origin main

这一设计的直接好处是：origin/main是一个只读的远程跟踪引用，更新它不会触碰任何已检出的工作树，从根本上规避了"改到一半发现 main 被占用"的尴尬。

记录改写前快照：old head 与 unique-commit 边界

在重写历史（rebase）之前，技能文档要求先记录旧的 HEAD 与"独有提交"边界（Record the old head and the unique-commit boundary before rewriting history）。这是整个流程中最关键、也最容易被忽略的一步。

什么是 unique-commit 边界

假设分支结构如下：

main: ... A --- B --- C（B、C 是 parent-branch 被 squash 合并后的提交） \ parent-branch: A1 --- A2（原始提交，被 squash 成 main 上的 B） \ feature-a: A1 --- A2 --- F1 --- F2

这里feature-a的独有提交（unique commits）是从分支分叉点之后、属于该分支自己的提交F1、F2；而A1、A2是继承自parent-branch的提交。<first-unique-commit>指的就是F1——即feature-a上第一个不属于父分支的提交。

用 git range-diff 界定重放范围

技能文档给出的核对命令是：

git range-diff <first-unique-commit>^..<old-head> <new-base>..<new-head>

其语义是：

• <first-unique-commit>^：第一个独有提交的父提交，即继承链与独有链的分界点；
• <first-unique-commit>^..<old-head>：rebase之前该分支上应当被重放的提交集合（独有提交）；
• <new-base>..<new-head>：rebase之后新基线上属于该分支的提交集合；
• git range-diff逐对比较两个提交区间，输出每对提交的 patch 差异。

对于 squash 合并的父分支场景，只比较分支的独有提交区间，而不是全量比较——因为parent-branch的原始提交在 squash 后已不存在于main上，把它们纳入比较毫无意义。通过 range-diff 可以确认：

• 每个独有提交是否被正确重放（无丢失、无多余）；
• 重放后的 patch 与重放前是否一致（无意外改动）；
• 是否有新增或缺失的提交。

技能文档特别提示：被有意排除在回放之外的继承提交（inherited commits intentionally excluded from the replay）并不是丢失的工作（not lost work）——它们已经以 squash 后的形态存在于main中。但如果 range-diff 显示独有 patch 本身有 changed/missing/added，则必须停下来调查，不能直接继续。

执行 rebase 与校验

1. 在正确的工作环境下执行 rebase

# 确保在 feature-a 所属的 worktree 中 git checkout feature-a # 以 origin/main 为基线进行 rebase git rebase origin/main

如果 rebase 过程中出现冲突，PX4 官方文档 docs/en/contribute/git_examples.md 的 "Rebase merge conflicts" 一节提供了处理指引：逐个解决冲突后git add相关文件并git rebase --continue。由于 PX4 采用 squash/rebase 合并且禁用 merge commit，保持线性历史的 rebase 是合入前的事实标准步骤。

2. 用 range-diff 校验重放结果

git range-diff <first-unique-commit>^..<old-head> <new-base>..<new-head>

• 输出为空或仅显示"identical"性质的对等关系，说明独有提交完整、干净地重放到了新基线上；
• 若出现某对提交的 patch 不一致、或区间内提交数量对不上，说明回放过程中产生了内容漂移，需要回到 rebase 现场排查。

备份引用与安全推送

技能文档对推送环节提出了两条硬性要求：

1. 保留一个备份引用（backup ref），直到结果被审查通过；
2. 推送前必须征得同意，且只能使用--force-with-lease；未经授权不得改写或推送依赖分支（dependent branches）。

1. 创建备份引用

在 rebase 之前（或刚 rebase 完但尚未推送时）为旧 HEAD 打一个本地引用：

# 备份当前分支旧 HEAD（在 rebase 之前执行最佳） git branch backup/feature-a-before-rebase # 若已 rebase 完，可从 reflog 找回旧 HEAD git branch backup/feature-a-before-rebase <old-head-sha>

备份引用是纯本地的，不影响远程、不参与推送，是回滚的救命稻草：一旦 range-diff 校验发现问题或评审提出异议，可以随时git reset --hard backup/feature-a-before-rebase回到改写前的状态。

2. 使用 --force-with-lease 推送

由于 rebase 改写了提交哈希，普通git push会被拒绝（non-fast-forward），必须强制推送。但绝对不要使用裸--force，而要使用--force-with-lease：

git push --force-with-lease origin feature-a

--force-with-lease与--force的本质区别在于：它会先检查远程引用是否仍是自己上次 fetch 时的值（即"租约"），只有当远程没有被他人更新时才允许覆盖，从而避免覆盖别人刚推上来的新提交。这与 PX4 官方文档 docs/en/contribute/git_examples.md "Force push to forked repository" 一节的建议完全一致：rebase 之后 push 到 fork 需要使用git push --force-with-lease origin <branch>。

技能文档同时强调：依赖当前分支的其它分支（dependent branches）不得在未经授权的情况下被改写或推送。若feature-b基于feature-a拉出，改写并强推feature-a会连带影响feature-b的历史，这类操作必须单独征得同意后处理。

与 PX4 协作规范的衔接：为什么这一流程是仓库级的硬需求

rebase-onto-main技能并非孤立存在，它与 PX4 仓库的多份协作规范互相咬合：

• 提交规范：仓库根目录 AGENTS.md 与 CLAUDE.md 都要求使用 conventional commit 格式（type(scope): description），CONTRIBUTING.md 进一步给出feat(ekf2): add height fusion timeout、fix(mavlink): correct BATTERY_STATUS_V2 parsing等示例。当你的提交是干净、逻辑完整的，PX4 会以 rebase merge 方式逐提交保留在main上；反之，多个 WIP 提交会被要求 squash。这两种结局决定了你的分支最终如何与main对齐，也决定了 rebase 时"独有提交"的粒度。
• 评审纪律：.github/instructions/code-review.instructions.md 要求提交原子化、可独立回退（Commits should be atomic and independently revertable）。rebase-onto-main 流程通过 range-diff 逐提交核对，正是对"原子化"的工程化保障。
• AI 辅助贡献：PX4 允许 AI 辅助贡献，但要求作者理解并能为每一行代码负责，且提交中需带Assisted-by: NAME:MODEL尾注（见 CONTRIBUTING.md 的 AI-assisted contributions 一节）。当 AI 工具执行的正是rebase-onto-main这样的技能时，上述"先记录、再改写、后校验、安全推送"的纪律同样必须遵守。

常见问题与排查清单

为什么普通git rebase main会把继承提交再放一遍？

Git 的去重（skip）机制依赖 patch-id 匹配：当父分支被 squash 合并后，main上出现的是内容等价但哈希全新的单个提交，其 patch-id 与原始提交的 patch-id可能不一致（squash 会重新计算整体 diff 与作者信息），因此去重失败，继承提交被当作"新提交"回放。这正是本技能要求显式界定 unique-commit 区间、用 range-diff 而不是裸 rebase 来核对的根本原因。

range-diff 结果异常时怎么办？

按技能文档要求，出现 changed/missing/added 的独有 patch 时必须先调查再继续，不要带着疑问强推。典型排查动作：

# 查看重放前后的提交序列 git log --oneline --graph <first-unique-commit>^..<old-head> git log --oneline --graph <new-base>..<new-head> # 对比单个提交的完整 diff git show <old-sha> git show <new-sha>

若确认是 rebase 冲突解决时引入了错误改动，用备份引用回滚后重来：

git reset --hard backup/feature-a-before-rebase

完整操作速查

# 1. 环境确认 git worktree list && git status git fetch origin main # 2. 记录旧 HEAD 与独有提交边界（rebase 前） OLD_HEAD=$(git rev-parse HEAD) git branch backup/feature-a-before-rebase "$OLD_HEAD" # <first-unique-commit> 为分支上第一个独有提交 # 3. 执行 rebase git rebase origin/main # 4. 校验独有提交的重放 git range-diff <first-unique-commit>^.."$OLD_HEAD" origin/main..HEAD # 5. 审查通过后安全推送（先征得同意） git push --force-with-lease origin feature-a

总结

rebase-onto-main技能为 PX4-Autopilot 的 AI 辅助开发提供了一套可审计、可回滚的分支同步流程，其核心贡献在于：在父分支被 squash 合并的复杂场景下，用显式的 unique-commit 边界界定 +git range-diff逐提交核对，把"重写历史"从高风险操作变成可验证、可回退的常规操作。配合 docs/en/contribute/git_examples.md 中关于 force push、rebase 冲突处理的官方指引，以及 CONTRIBUTING.md 与 .github/instructions/code-review.instructions.md 规定的合并策略，这套方法完全适配 PX4 禁用 merge commit、追求线性历史的仓库现实。无论你是人类开发者还是 AI 编码助手，遵循"先记录、再改写、后校验、--force-with-lease推送、保留备份引用"这一纪律，就能在保证代码安全的前提下，持续将功能分支干净地同步到main之上。

• 嵌入式
• 物联网
• 机器人
• 自动驾驶
• 智能硬件