QMK Firmware Git 工作流高频同步 Fork 的 master 分支但绝不在其上提交【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本篇技术指南围绕 QMK Firmware 仓库 Git 最佳实践系列的第一篇文档展开讲解如何把 QMK 官方仓库配置为upstream远端并定期同步 fork 的master分支、如何在独立开发分支上进行提交、以及如何将变更推送到 fork 以供发起 Pull Request。读完本文你将掌握一套可直接复制执行的分支工作流并能理解该工作流如何与 QMK 的贡献规范PR 检查清单、贡献指南衔接从源头减少合并冲突与 CI 失败。核心原则Update Often, Commit Never在 QMK 开发中无论你在做什么、在哪里做官方都强烈建议保持你的master分支持续更新但绝不在其上提交任何变更。所有修改都应放在独立的开发分支中完成并在开发完成后从该分支发起 Pull Request。这条原则的直接目的是降低**合并冲突merge conflict**的概率——即两名或多名用户同时编辑了同一文件的同一部分时产生的冲突。将master保持在较新状态、并在每次开始新开发前创建新分支是避免分支落后过多、进而避免 PR 阶段大规模冲突的关键习惯。这一原则在仓库的其他文档中有明确的执行佐证docs/pr_checklist.md 中记录了维护者处理 PR 时的标准动作如果提交者把自己的master分支用作开发分支合并后会被发送一段提醒文字明确建议保持 master 更新但绝不向其提交并附上了本文对应的链接docs/contributing.md 的General Guidelines一节同样要求在贡献之前先确保你的 fork 与上游qmk_firmware仓库保持同步以帮助减少本地编译通过但 CI 却失败的情况。配置 upstream 远端要让 fork 能持续跟上 QMK 官方仓库第一步是把 QMK Firmware 仓库repo添加为 Git 的远端仓库。在 Git 命令行中执行git remote add upstream https://github.com/qmk/qmk_firmware.git两点说明upstream这个名字是任意的只是社区中约定俗成的常见叫法你可以给这个远端取任何喜欢的名字git remote命令的语法是git remote add name url其中name是远端仓库的简称。这个名字会出现在许多 Git 命令中包括但不限于fetch、pull、push用于指定命令作用于哪个远端仓库。添加完成后运行git remote -v验证。正常应返回两对条目——origin指向你的 forkupstream指向 QMK 官方仓库$ git remote -v origin https://github.com/your_username/qmk_firmware.git (fetch) origin https://github.com/your_username/qmk_firmware.git (push) upstream https://github.com/qmk/qmk_firmware.git (fetch) upstream https://github.com/qmk/qmk_firmware.git (push)一个实用的判断技巧来自 docs/newbs_git_resynchronize_a_branch.md如果你的git remote -v只看到origin且其 URL 指向 QMK 官方仓库说明你是直接 clone 官方仓库而非自己的 fork需要先按该文档指引执行git remote set-url origin把origin重定向到自己的 fork再补加upstream远端否则后面的git push origin master会直接写入官方仓库的语义混乱。同步 master 分支fetch 与 pull 的分工配置好两个远端后可以用git fetch upstream检查官方仓库是否有更新。fetch会从 QMK 仓库获取所有分支和标签这些引用对象合称为refs。此时数据已下载到本地但尚未合并——fetch 是取回参照物之后才能比较你 forkorigin上的数据与 QMK 官方仓库的数据差异。实际更新 fork 的master分支时依次执行以下四行命令每行执行后按回车git checkout master git fetch upstream git pull upstream master git push origin master这四条命令的完整语义是命令作用git checkout master切换到你的master分支确保后续操作作用在正确分支上git fetch upstream从 QMK 仓库取回最新的 refs分支、标签git pull upstream master将 QMK 当前的master分支内容下载到本地并合并进你的mastergit push origin master把同步后的master上传到你的 GitHub fork使远端 fork 与本地一致这样你 GitHub 上的 fork、本地工作副本与 QMK 官方仓库的master三者保持一致。从当前仓库的git状态可以确认QMK 仓库当前使用的正是master分支名origin/HEAD - origin/master因此文档中的master写法与仓库现状一致。创建开发分支所有变更的起点同步好master之后任何新开发都从新建分支开始git checkout -b dev_branch git push --set-upstream origin dev_branch第一条命令创建名为dev_branch的新分支并立即切换过去第二条命令把这个新分支保存到你的 fork。--set-upstream参数告诉 Git此后在这个分支上直接运行git push或git pull时默认使用origin远端与dev_branch分支。该参数只在首次推送时需要之后就可以安全地直接使用git push/git pull不再携带任何参数。::: tipgit push中可以用-u代替--set-upstream——-u是它的缩写别名。 :::分支名几乎可以随意取但官方建议用与即将做的变更相关的名字命名这样在 PR 列表和 CI 日志中一眼就能看出分支用途。git checkout -b默认基于当前已检出的分支创建新分支。如果你希望基于另一个尚未检出的已有分支创建把该分支名追加到命令后即可git checkout -b dev_branch master这与 docs/contributing.md 中贡献流程第 5 步git checkout -b branch-name-here的做法完全一致且由于第 1 步要求先同步 fork等价于从最新的上游 master 切出开发分支。提交变更暂存区与小步提交有了开发分支后用文本编辑器修改并保存需要更新的文件。官方建议向分支做大量小的提交这样任何引起问题的变更都能被更轻松地追溯必要时也能单独撤销。把改动纳入 Git 管理的两步操作是先把文件加入 Git 的暂存区staging area再提交到分支git add path/to/updated_file git commit -m My commit message.git add把已修改的文件加入 Git 的暂存区。暂存区可以理解为 Git 的装载区loading zone里面存放着即将被提交的内容git commit把暂存区中的变更正式保存到仓库历史中。请使用描述性的提交信息让他人包括未来的自己一眼就能看出这次提交改了什么。::: tip 如果你修改了多个文件可以用git add -- path/to/file1 path/to/file2 ...一次性把所有目标文件加入暂存区。 :::结合 docs/contributing.md 对提交信息的进一步要求QMK 期望的提交信息规范是第一行不超过 70 字符的简短描述第二行留空从第三行起按需详细描述变更动机与细节。这条规范在评审时会被维护者实际检查建议养成习惯。发布变更推送到 fork最后一步是把变更推送到你的 forkgit push由于创建分支时已经用--set-upstream设置好了上游这里直接执行git push即可把dev_branch的当前状态发布到你的 fork。之后就可以在 GitHub 上基于该分支向 QMK 官方仓库发起 Pull Request。需要提醒的适用限制推送后合并并不等于立刻完成。从 docs/pr_checklist.md 的评审流程看一个 PR 通常需要两名或以上做过实质性代码检查的审阅者批准才会进入合并阶段社区平均每月约有 200 个 PR 打开与合并因此请对评审周期保持耐心。工作流断裂后的修复路径本文档是 QMK Git 最佳实践三部曲的第一部完整索引见 docs/newbs_git_best_practices.mdPart 1本文Your Forks Master: Update Often, Commit Never——正常情况下的同步与分支流程Part 2Resolving Merge Conflicts——当开发周期长、上游已发生重叠修改时如何用git rebase upstream/master把分支变更重放到最新上游之上并手工解决冲突标记 HEAD//Part 3Resynchronizing an Out-of-Sync Git Branch——当你违反原则向master提交了内容后如何先用git branch old_master master备份脏分支再用git reset --hard upstream/master与git push --force-with-lease将 fork 强制重置为与上游一致。这两篇修复文档均明确声明以本文的概念为基础。换句话说本文的高频同步 绝不提交到 master纪律正是让 Part 2 与 Part 3 的修复场景永远不会发生的前提。实操核对清单完成一套完整流程后可以用以下命令自检当前状态git remote -v # 确认 origin/upstream 双远端配置正确 git fetch upstream # 取回上游最新 refs git rev-list --left-right --count HEAD...upstream/master # 查看当前分支领先/落后上游的提交数其中git rev-list --left-right --count的用法出自 docs/newbs_git_resolving_merge_conflicts.md输出的两个数字分别代表当前分支自创建以来的提交数以及上游master在此期间新增、而当前分支尚未包含的提交数。当第二个数字持续增长时就是你该回到master执行一次四步同步、或对新分支执行 rebase 的信号。总结本指南所描述的 QMK 分支纪律可以浓缩为一句话master只用于同步开发只在分支上进行。配置upstream远端、四步同步命令、checkout -b加--set-upstream建分支、小步提交加描述性 commit、最后git push发布构成了一条与 docs/contributing.md 贡献流程和 docs/pr_checklist.md 评审规范完全咬合的工作流。遵循它你的 PR 将更少遭遇合并冲突你的 fork 也将始终处于可以随时切出新分支的干净基线之上。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考