★ FEATURED ARTICLE 1. 为什么还要折腾分支名这件事先把话说在前头把默认分支从main改回master在今天的舆论环境里算是个有点“逆流”的操作。但工程上的事从来不是看风向而是看你的实际处境。我之所以专门写这一篇是因为过去大半年里至少有四五个人问过我同一个问题本地推上去的分支叫master远端仓库却自动生成了main两边对不上每次 push 都要多敲一长串参数烦得要命还有一些老项目、老脚本、老 CI 配置里到处硬编码了master新仓库一建出来就是main结果流水线直接红给你看。这篇文章就是冲着这些具体麻烦来的。我会把 GitHub 的基础使用逻辑先捋一遍让你明白分支名到底在哪些地方被引用、被写死然后手把手带你走一遍“把默认分支从 main 改成 master”的完整流程包括网页端操作、本地仓库同步、以及那些容易被忽略的连带影响。适合谁看适合已经会git clone、git push但对分支模型和远端默认分支机制还模模糊糊的开发者也适合那些接手了历史项目、被分支名不一致折磨过的运维和测试同学。看完之后你应该能独立完成默认分支切换并且知道切换之后哪些地方需要跟着改不至于改完发现 CI 挂了、PR 目标分支错了。需要提前说明的是GitHub 官方从 2020 年起把新仓库的默认分支名定为main这是平台层面的默认值不是强制值。也就是说你完全有权利把它改回master平台也提供了对应的入口。我们要做的就是把这个入口找出来并且把改完之后的一堆“后遗症”处理干净。2. GitHub 基础使用逻辑快速过一遍2.1 仓库、分支、远端这三个概念到底啥关系很多人改分支名改出问题根子在于没分清“本地分支”和“远端分支”是两套东西。我用一个生活化的类比远端仓库remote repository就像公司总部的一个文件柜本地仓库local repository是你工位上的一份复印件。你在复印件上改东西改完要“推”push到总部文件柜别人才看得到别人在总部改了你要“拉”pull回自己的复印件。分支branch则是文件柜里的不同抽屉。master和main只是抽屉的标签标签本身没有魔法真正重要的是“默认抽屉”是哪一个——也就是别人打开文件柜时第一眼看到、默认去取的那个抽屉。GitHub 上的“默认分支”default branch就是这个意思克隆仓库时默认检出它提 PR 时默认以它为合并目标网页上打开仓库首页时默认展示它的内容。这里有个关键点默认分支是一个仓库级别的设置不是分支本身的属性。你可以有一个叫master的分支但它未必是默认分支也可以有一个叫main的分支把它设成默认。改名和改默认是两件可以分开做的事。很多人把这两件事混在一起才会觉得“我明明改了名怎么还是不对”。2.2 本地分支和远端分支的对应关系本地分支和远端分支之间是“跟踪关系”tracking。当你执行git clone时Git 会自动帮你建立一条跟踪本地的master或main跟踪远端的origin/master或origin/main。之后你敲git push不带参数Git 就知道该推到哪个远端分支去。问题就出在这里如果远端默认分支叫main而你本地习惯用master那么克隆下来之后本地分支名会跟着远端走变成main。你想推到一个叫master的远端分支就得显式指定git push origin master而且第一次推还要加-u建立跟踪。一天敲几十次谁受得了。所以把远端默认分支改成master本质上是为了让本地和远端的命名习惯统一减少这种无谓的摩擦。2.3 哪些地方会“记住”默认分支名在动手改之前你得知道有哪些地方引用了默认分支名否则改完会踩坑。我整理了一张表这些都是我实际踩过的引用位置是否随默认分支自动更新说明克隆时的默认检出分支是改完默认分支后新克隆会检出新的默认分支网页端 PR 的默认目标分支是新建 PR 时默认指向新的默认分支仓库首页展示内容是首页展示新默认分支的内容已有的开放 PR否已存在的 PR 目标分支不会自动改需要手动调整CI/CD 配置文件否配置文件里硬编码的分支名需要手动改分支保护规则否保护规则绑定的是具体分支名改名后规则可能失效本地已克隆的仓库否本地需要手动同步否则跟踪关系还是旧的各种脚本、文档、徽章链接否需要全局搜索替换这张表建议你截图存一下改完之后逐项核对。我见过太多人只改了网页设置结果 CI 里写的还是main流水线一直失败排查半天才发现是分支名没同步。3. 把默认分支从 main 改成 master 的完整实操3.1 前置检查先确认当前状态动手之前先登录 GitHub打开目标仓库点进 Settings设置左侧找到 Branches分支这一项。在 Default branch默认分支区域你会看到当前默认分支是main。同时确认一下仓库里是否已经存在一个叫master的分支这一步很关键分两种情况情况 A仓库里已经有master分支。那最简单直接把默认分支切换过去就行跳到 3.2。情况 B仓库里只有main没有master。那你得先创建一个master分支或者把main改名成master。我推荐后者因为改名能保留提交历史而新建分支再合并会多出一堆无意义的合并记录。如果你属于情况 B先在本地操作。打开终端进入你的本地仓库目录# 确认当前在哪个分支 git branch # 如果当前在 main 分支先确保它是最新的 git pull origin main # 把本地的 main 分支改名成 master git branch -m main master # 把改名后的分支推到远端 git push origin master # 让本地 master 跟踪远端 master git push -u origin master推完之后远端就多了一个master分支。这时候别急着删main等默认分支切换完成、确认一切正常之后再删给自己留条后路。3.2 网页端切换默认分支回到 GitHub 仓库的 Settings → Branches 页面在 Default branch 区域点那个双向箭头的切换按钮。弹出的下拉框里会列出仓库里所有分支选中master然后点 Update 确认。这里有个细节GitHub 会弹一个警告告诉你切换默认分支会影响 PR 目标、克隆行为等。这个警告不是吓唬你是真实存在的连带影响但只要你按本文的清单逐项处理就没问题。确认之后仓库的默认分支就变成master了。提示如果你的仓库开启了分支保护规则Branch protection rules切换默认分支后原来绑定在main上的保护规则不会自动迁移到master。你需要去 Branches 页面下方重新为master配置保护规则比如要求 PR 审查、要求状态检查通过等。这一步漏了等于保护形同虚设。3.3 本地仓库同步与跟踪关系修复网页端改完之后你本地那个已经克隆过的仓库还蒙在鼓里。它的HEAD可能还指向旧的main跟踪关系也还是旧的。需要手动同步一下# 拉取远端最新的分支信息 git fetch origin # 查看远端默认分支指向哪里 git remote show origin # 如果本地还在 main 分支切到 master git checkout master # 重新设置上游跟踪分支 git branch --set-upstream-toorigin/master master # 确认跟踪关系正确 git branch -vvgit remote show origin这个命令特别有用它会明确告诉你“HEAD branch”是哪个也就是远端默认分支。改完之后再跑一次确认它显示的是master。如果你本地还有别的克隆副本或者团队里其他人也克隆了这个仓库记得通知他们做同样的同步操作。否则他们下次git pull可能会拉到旧分支产生困惑。3.4 删除旧的 main 分支可选但推荐确认新默认分支工作正常之后可以把旧的main分支删掉避免仓库里留两个几乎一样的分支让人迷惑。删除远端分支git push origin --delete main删除本地可能残留的main分支git branch -d main如果本地main分支还有未合并的提交-d会拒绝删除这时候你要么先合并要么确认那些提交确实不要了再用-D强删。我个人的习惯是删之前一定用git log main --not master看一眼确认没有独有提交再动手。4. 改完之后必须检查的连带影响4.1 CI/CD 配置里的分支名硬编码这是最容易翻车的地方。很多项目的 CI 配置文件里写着类似这样的触发条件on: push: branches: [ main ] pull_request: branches: [ main ]默认分支改成master之后这些配置如果还写着main那么推送到master的代码根本不会触发流水线。你会以为 CI 正常实际上它压根没跑。所以改完默认分支第一件事就是全局搜索配置文件里的main逐个替换成master。搜索范围包括但不限于.github/workflows/目录下的所有 YAML 文件、Jenkinsfile、.gitlab-ci.yml如果同时用了别的平台、azure-pipelines.yml、各种部署脚本、Docker 构建脚本。用编辑器的全局搜索功能搜main这个词然后人工判断哪些是分支名引用哪些只是普通变量名。4.2 分支保护规则与合并策略前面提过分支保护规则绑定的是具体分支名。切换默认分支后去 Settings → Branches 检查一下原来针对main的保护规则是否还需要如果main已经删了规则可以一并删除。是否为新的master分支创建了保护规则建议至少开启“Require a pull request before merging”和“Require status checks to pass”这两个是最基本的质量闸门。合并策略Merge button的设置是仓库级别的不随分支变一般不用动。我踩过的一个坑是切换默认分支后忘了配保护规则结果有同事直接往master上强推把别人的提交覆盖了。虽然最后用 reflog 找回来了但那个下午全组都在帮忙恢复教训深刻。4.3 开放中的 PR 和 Issue 引用如果切换默认分支时仓库里还有开放中的 PR它们的“目标分支”不会自动改变。你需要逐个检查这些 PR把目标分支从main手动改成master。操作方式是在 PR 页面点目标分支旁边的 Edit 按钮选择新的分支。Issue 里如果有关联的 PR 引用、或者正文里提到了main分支的链接这些链接可能会失效。GitHub 对已删除分支的链接一般会重定向到仓库首页但体验不好。建议在切换前先把重要 Issue 里的分支引用更新一遍。4.4 文档、README 和徽章链接README 里的状态徽章badge经常带有分支参数比如https://img.shields.io/.../main这种链接里的main要改成master否则徽章会显示“branch not found”或者一直显示旧状态。同样文档里如果写了“请克隆后切换到 main 分支”之类的说明也要同步更新。这类问题不影响功能但影响专业度别人一看文档和实际对不上对你的项目信任度就打折扣。5. 常见问题与排查技巧实录5.1 改了默认分支为什么克隆下来还是 main这种情况通常是缓存或者操作顺序的问题。先确认你在网页端确实点了 Update 并且看到了成功提示。然后检查是不是浏览器缓存了旧页面强制刷新一下。如果确认网页端已经是master但克隆下来还是main那可能是你克隆的是本地某个旧的镜像或者缓存副本换个目录重新克隆试试。还有一种可能你改的是仓库 A 的默认分支但克隆的是仓库 B。听起来很蠢但我真的见过尤其是在同时维护多个相似仓库的时候。5.2 push 时报错 “src refspec master does not match any”这个报错的意思是你本地根本没有master分支却想推它。常见于新建的本地仓库默认分支是main你没改名就直接git push origin master。解决办法就是先git branch -m main master改名再推。或者你本地分支叫别的名字先确认git branch的输出。5.3 切换后 CI 不触发怎么快速定位按这个顺序排查打开 CI 平台的日志页面看最近一次触发是什么时候、针对哪个分支。检查 CI 配置文件里的branches过滤条件确认写的是master而不是main。确认推送的分支名确实是master用git branch -vv看本地用git ls-remote origin看远端。如果 CI 平台有“手动触发”功能手动跑一次看是否能成功以此判断是触发条件问题还是构建本身的问题。我一般会先手动触发一次能跑通就说明是触发条件写错了直接去改配置跑不通就是构建脚本本身的问题另说。5.4 团队协作时怎么避免混乱分支名切换这种事最怕的就是“我改了别人不知道”。我的做法是切换前在团队频道里发个通知说明什么时候切、切完大家需要做什么。切换后立刻发一条操作指引把本文 3.3 节的同步命令贴出来让大家照着做。在仓库 README 顶部加一行醒目提示写清楚当前默认分支是master以及本地同步方法。一周后检查一遍看还有没有人的 PR 目标分支是旧的main有的话单独提醒。这套流程走下来基本不会出乱子。最忌讳的就是闷头改完不说等别人踩坑了才解释。5.5 常见问题速查表现象可能原因解决方向克隆下来是 main网页端未生效或克隆了旧副本确认网页设置换目录重新克隆push 报 refspec 错误本地无对应分支先改名或创建分支再推CI 不触发配置文件分支名未更新全局搜索替换 main 为 masterPR 目标分支错误开放 PR 未手动调整逐个编辑 PR 目标分支保护规则失效规则绑定旧分支名为 master 重新配置保护规则徽章显示异常徽章链接含旧分支名更新 README 中的徽章 URL6. 一些个人经验和收尾建议说实话分支名这事本身技术含量不高但它牵扯的面很广属于典型的“改一行、动全身”。我自己现在的做法是新项目一律跟随平台默认用main不去逆着来只有接手历史项目、且项目里大量硬编码了master的时候才会考虑把默认分支改回master目的是减少改动面。换句话说改不改不是立场问题是成本问题——哪边改动少、风险低就往哪边走。另外分享一个小技巧在切换默认分支之前先给当前状态打个标签tag比如git tag before-branch-rename并推送到远端。这样万一改出问题你有一个明确的回退点心里踏实很多。标签不占什么空间但关键时刻能救命。最后提醒一句改完默认分支后别急着删旧分支至少观察一个完整的开发周期确认没有遗漏的引用之后再清理。我见过有人当天就删了main结果第二天发现某个定时任务脚本里还写着main任务直接失败又得重新建分支白折腾一圈。稳一点不丢人。
阅读完成 · 觉得有帮助？
