分支名从 main 改成 master？本地怎么改、远程（GitHub）怎么改、如果别人也在用这个仓库该怎么办？

一句话总结

要做的就 3 件事：

1. 把本地分支 main 改名为 master；
2. 把远程仓库的默认分支从 main 改成 master；
3. 把远程的旧 main 分支删掉，并更新本地跟踪关系。

整体流程示意

下面是整个操作的简化流程图，你可以先有个整体印象：

flowchart LR
  A[确认当前在 main 分支] --> B[本地重命名为 master\n git branch -m main master]
  B --> C[推送新分支到远程\n git push -u origin master]
  C --> D[GitHub 上将默认分支改为 master]
  D --> E[删除远程旧 main 分支\n git push origin --delete main]
  E --> F[设置本地 master 跟踪远程 master\n git branch -u origin/master]

第 0 步：先确认当前状态

1. 打开终端（Windows 下是 Git Bash / PowerShell / VS Code 终端），进入你的项目目录。
2. 看一下当前分支：

   git branch
   

   输出前面有 * 的是当前分支，例如：

     main
   * master
   

   如果你已经在 main 分支上，那很好；如果不在，先切换：

   git checkout main
   

3. 看一下远程分支：

   git branch -a
   

   一般你会看到类似：

     main
   * master
     remotes/origin/main
     remotes/origin/HEAD -> origin/main
   

   这说明远程默认分支叫 main。

第 1 步：本地把 main 改名为 master

1.1 重命名本地分支

Git 官方推荐用 git branch --move（简写 -m）来重命名分支。
我们现在要把 main 改成 master：

# 确保当前在 main 分支
git checkout main
# 把 main 重命名为 master
git branch -m main master

说明：

• git branch -m main master 意思是：把名为 main 的分支改名为 master。
• 如果当前已经在 main 分支上，也可以直接写：

  git branch -m master
  

  这表示“把当前分支改名为 master”。
  再执行一次：

  git branch
  

  确认现在本地已经没有 main，只有 master：
  ```text

• master
  (可能还有别的分支，比如 dev 之类)
  ```

第 2 步：把新的 master 推送到远程（GitHub）

本地改名只在你自己的电脑上生效，要让 GitHub 上也出现 master 分支，需要推送：

# 把本地的 master 分支推送到远程，并设置上游跟踪
git push -u origin master

• -u 等同于 --set-upstream，表示以后这个分支默认推送到 origin master。
• 执行完后，远程会有一个新分支 origin/master。

第 3 步：在 GitHub 上把默认分支改为 master

GitHub 仓库的「默认分支」决定了：

• 打开仓库时默认看到哪个分支；
• PR 默认合并到哪个分支；
• 哪些分支可以受到保护等。

  3.1 打开 GitHub 仓库的 Settings

1. 用浏览器打开你的 GitHub 仓库页面，例如：
   https://github.com/zhugq404/STM32F407ZET-FreeRTOS
2. 点击仓库下的 Settings（设置） 标签。

   3.2 修改默认分支

   根据 GitHub 官方文档：
3. 在 Settings 页面左侧找到 Branches（分支） 或直接找到 Default branch（默认分支） 区域。
4. 右侧有一个默认分支名称（比如 main），旁边有一个切换按钮（双向箭头）。
5. 点击切换按钮，在弹出的下拉框中选择 master。
6. 点击 Update 按钮，确认弹出的警告。
   完成后，GitHub 会：

• 把仓库的默认分支改成 master；
• 以后新建 PR、查看仓库默认都用 master。

第 4 步：删除远程的旧 main 分支

现在远程已经有 master 作为默认分支了，旧的 main 分支可以删掉。

# 删除远程的 main 分支
git push origin --delete main

--delete 选项用于删除远程分支。
执行完后，远程仓库就只有 master 了，不会再有 main。

第 5 步：更新本地 master 的跟踪关系

如果你之前是用 git push -u origin master 推送的，那本地 master 已经跟踪了 origin/master，这步可以跳过。
如果你没有用 -u，可以手动设置：

# 设置本地 master 跟踪远程 master
git branch -u origin/master master

git branch -u / --set-upstream-to 用于建立本地分支与远程分支的跟踪关系。
之后，你就可以简单地：

git pull
git push

而不需要每次写 origin master。

第 6 步：如果别人也在用这个仓库（团队协作）

如果你是「唯一开发者」，可以跳过这一节。
如果有队友也在这个仓库上工作，改名后他们需要同步一下，否则下次 git pull 会报错。

6.1 他们可以怎么做？

比较简单的两种方式：

方式 A：重新 clone（最省事）

1. 让队友备份自己本地的修改（比如先提交并推送，或者备份到别的目录）。
2. 删除本地旧仓库目录。
3. 重新 clone：

   git clone https://github.com/zhugq404/STM32F407ZET-FreeRTOS.git
   

   这样拿到的仓库默认分支就是新的 master。

   方式 B：在现有仓库上改名

   根据一些项目的分支改名建议，队友可以在旧仓库里执行：

   # 1. 把本地 main 改名为 master
   git branch -m main master
   # 2. 拉取远程的最新信息
   git fetch origin
   # 3. 设置本地 master 跟踪新的远程 master
   git branch -u origin/master master
   # 4. 清理远程跟踪分支里旧的 main 引用
   git remote prune origin
   

   git remote prune origin 会清理本地记录的「远程分支」信息，把已经不存在的分支删掉。

第 7 步：可选——全局配置默认分支为 master

如果你以后新建仓库就想默认用 master，可以全局设置：

# 设置默认分支名为 master（适用于以后 git init）
git config --global init.defaultBranch master

这样以后本地 git init 创建的仓库，默认分支就会是 master，而不是 main。

常见问题与报错处理

1. git push 报错：Updates were rejected because the tip of your current branch is behind

这说明：

• 你本地的 master 历史，和远程 master 不在一条线上；
• 可能远程有别人推送的新提交，而你本地还没有合并。
  解决思路：

  # 1. 拉取并合并远程 master
  git pull --rebase origin master
  # 如果有冲突，解决后继续：
  # git add .
  # git rebase --continue
  # 2. 再推送
  git push origin master
  

  如果你非常确定远程那几条提交不要了，也可以强制推送（谨慎）：

  git push origin master --force-with-lease
  

2. 删除远程 main 时报错：refusing to delete the current branch

这通常是因为 GitHub 上的默认分支仍然是 main，而不是 master。必须先在 GitHub 的 Settings → Branches 里把默认分支改成 master，再删除 main。

3. 本地已经有 master 分支怎么办？

如果本地已经有 master 分支，同时又有一个 main，你需要：

1. 确认你想保留的是哪个分支；
2. 先把多余的分支删掉，或者合并到目标分支；
3. 再按上面步骤改名。
   例如，把 main 合并到 master：

   git checkout master
   git merge main
   # 然后再删除本地的 main
   git branch -d main
   

一套完整命令小结（可以直接照抄）

假设你当前在 main 分支，远程默认分支也是 main：

# 1. 切到 main
git checkout main
# 2. 本地重命名为 master
git branch -m main master
# 3. 推送新分支到远程
git push -u origin master
# 4. 在 GitHub 网页上把默认分支改为 master（Settings -> Branches -> Default branch）
# 5. 删除远程旧 main 分支
git push origin --delete main
# 6. 设置本地跟踪（如果之前没用 -u）
git branch -u origin/master master