如何将 Git 仓库的默认分支从 master 修改为 main

(Updated: )
git
, , ,

随着技术社区对包容性语言的倡导，将 Git 仓库的默认分支从 master 修改为 main 已成为一种普遍的推荐做法。本文将提供一个详细、安全的操作指南，帮助你顺利完成这一迁移。

整个过程主要分为四个核心步骤，外加一个针对团队协作的同步步骤。我们将依次进行操作，确保万无一失。

1. 重命名本地分支

首先，我们需要在本地的 Git 仓库中进行操作。打开你的项目终端或命令行工具。

  1. 切换到 master 分支并拉取最新代码，确保本地与远程是同步的。

    1
    2
    git checkout master
    git pull origin master

  2. 使用 -m (--move) 参数重命名分支。这将把本地的 master 分支直接更名为 main。

    1
    git branch -m master main

    执行后，你的本地主分支名就修改完成了。

2. 推送新分支到远程仓库

本地分支改名后，需要将这个新的 main 分支推送到你的远程仓库（如 GitHub 或 GitLab），并建立跟踪关系。

  1. 推送 main 分支。使用 -u (--set-upstream) 参数，这样 Git 会记住本地 main 分支对应远程的 main 分支，方便以后直接使用 git push 和 git pull。
    1
    git push -u origin main
    此时，你的远程仓库会同时存在 master 和 main 两个分支，它们的内容完全相同。

3. 修改平台的默认分支（关键步骤）

这是整个流程中最关键的一步，必须在代码托管平台的网页上完成。**只有修改了默认分支，新的克隆 (clone) 和拉取请求 (Pull Request) 才会默认指向 main**。

以 GitHub 为例：

  1. 进入你的仓库主页，点击右上角的 Settings (设置)。
  2. 在左侧菜单栏找到并点击 Branches (分支)。
  3. 在 “Default branch” (默认分支) 区域，点击切换按钮（通常是两个箭头图标）。
  4. 在弹出的窗口中，将默认分支从 master 选为 main，然后点击 Update 确认。

其他平台（如 GitLab, Gitee）的操作也类似，通常都在仓库的“设置”或“仓库管理”中的“分支”选项里。

4. 清理远程的 master 分支

在确认 main 已成为默认分支，并且所有相关的自动化流程（如 CI/CD）都已更新后，你就可以安全地删除远程的 master 分支了，以避免团队成员产生混淆。

  1. 执行删除命令：
    1
    git push origin --delete master

至此，你的仓库就完全迁移到 main 作为主分支了。

注意事项与协作者指南

如果你的项目是多人协作的，请务必通知所有成员，并让他们在自己的本地仓库执行以下命令来同步变更：

# 1. 切换到旧的 master 分支
git checkout master

# 2. 从远程拉取最新的分支结构信息
git fetch origin

# 3. 将本地的 master 也重命名为 main
git branch -m master main

# 4. 重新设置本地 main 分支去跟踪远程的 main 分支
git branch --set-upstream-to=origin/main main

# 5. (推荐) 清理本地无效的远程跟踪分支
git remote prune origin