更改默认分支

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

默认分支是 Git 将在新克隆上签出的第一个分支。 此外，拉取请求默认面向此分支。

我们将逐步完成更改默认分支的过程。 我们还将介绍进行此更改时必须考虑和更新的其他事项。 最后，我们将介绍一种简化转换的工具。

设置新默认分支

可以使用 main 以外的分支进行新的更改或更改存储库中的开发主线。 若要更改新存储库的默认分支名称，请参阅所有存储库设置和策略。

若要更改用于合并新拉取请求的存储库默认分支，至少需要两个分支。 如果只有一个分支，则它已是默认分支。 必须创建第二个分支才能更改默认分支。

注意

更改默认分支要求具有编辑策略权限。 有关详细信息，请参阅设置 Git 存储库权限。

1. 在项目存储库下，选择分支。

2. 在分支页上，选择所需新默认分支旁边的更多选项，然后选择设为默认分支。

   

3. 设置新的默认分支后，可以根据需要删除以前的默认值。

在进行此更改之前，还应考虑其他方面。

选择名称

Git 2.28 添加了选择初始分支名称的功能。 同时，Azure Repos、GitHub 和其他 Git 托管提供程序添加了选择其他初始分支名称的功能。 以前，默认分支几乎总是命名为 master。 最常用的替代名称是 main。 不太常见的选项包括 trunk 和 development。 如果你使用的工具或你所在的团队没有任何限制，任何有效的分支名称都是可行的。

更新其他系统

更改为其他默认分支时，工作流的其他部分可能会受到影响。 在计划更改时，需要考虑这些部分。

管道

更新所有管道的 CI 触发器。 可以在 Web 中编辑 Designer 管道。 YAML 管道可以在其各自的存储库中进行编辑。

进行中的拉取请求

将每个未完成的拉取请求重定向到新的默认分支。

现有克隆

存储库的新克隆将获取新的默认分支。 切换后，具有现有克隆的每个人都应运行 git remote set-head origin -a（如果 origin 是其他内容，请将其替换为相应的远程库名称），以更新其远程库的默认分支视图。 将来的新分支应基于新的默认值。

传入链接

需要更新指向 Azure Repos 中的文件的某些书签、文档和其他非代码文件。 文件或目录的分支名称可以显示在 URL 中。

如果 URL 包含 version 的查询字符串，例如 &version=GBmybranchname，则应更新该 URL。 幸运的是，大多数指向默认分支的链接没有 version 段，可按原样保留。 此外，删除旧的默认分支后，仍会尝试导航到新的默认分支。

临时镜像

一个 Git 存储库只能有一个默认分支。 但是，暂时可以在旧的默认分支和新的默认分支之间设置临时镜像。 这样一来，如果最终用户继续推送到旧的默认分支，他们那边就无需将工作重做一遍。 我们将使用 Azure Pipelines 设置此临时镜像。

注意

本部分使用的语言与 Microsoft 的角度不一致。 具体而言就是 master 一词会出现在多个位置，与它在 Git 中的使用方式一致。 本主题的目的是说明如何切换到更具包容性的语言，例如 main。 避免全部提及 master 会使说明更难以理解。

镜像管道

注意

这些说明并非万无一失，存储库设置可能需要进行其他更改，例如放宽权限和策略。

警告

如果旧的默认分支和新的默认分支在此管道运行之前都已更新，则管道将无法镜像更改。 必须手动将旧的默认分支合并到新的默认分支，才能使其再次自动运行。

1. 对于所有现有 CI 生成，请将其更新为针对新的默认分支而非旧的默认分支触发。

2. 向生成标识授予存储库的参与者权限。 导航到项目设置>存储库>（你的存储库）>权限。 最多可以有两个标识，一个用于项目集合生成服务，另一个用于项目生成服务。 确保“参与”权限显示允许。

3. 如果新的默认分支具有分支策略，还应向生成标识授予推送时绕过策略权限。 此权限存在安全风险，因为恶意用户可能会创建管道，将代码偷偷放入项目的存储库中。 如果不再需要镜像，请确保移除此权限。

4. 将新文件 mirror.yml 添加到新默认分支中的存储库。 在此示例中，假定旧的默认分支为 master，新的为 main。 如果分支名称不同，则更新触发分支和 git push 行。

trigger:
  branches:
    include:
    - main
    - master
 
pool: { vmImage: ubuntu-latest }
steps:
- checkout: self
  persistCredentials: true
- script: |
    git checkout $(Build.SourceBranchName)
    git push origin HEAD:master HEAD:main
  displayName: Mirror old and new default branches

5. 创建新管道，在向导中选择“Azure Repos Git”和“现有 Azure Pipelines YAML 文件”。 选择在上一步中添加的 mirror.yml 文件。 保存并运行管道。

疑难解答

每次推送到 master 或 main 时，此管道都将运行。 只要新提交不同时到达两个分支，它们就会保持同步。

如果管道开始失败并显示错误消息“由于推送的分支提示落后于远程分支而拒绝更新”，则必须手动将旧分支合并到新分支。

1. 克隆存储库，并将 cd 克隆到其目录中。
2. 用 git checkout main 检查新的默认分支（如果 main 是新的默认分支）。
3. 创建一个新分支，用于将两个分支与 git checkout -b integrate 集成。
4. 将旧的默认分支与 git merge master 合并（如果 master 是旧的默认分支）。
5. 推送新分支，然后打开并完成拉取请求，以合并到新的默认分支。
6. 然后，镜像管道应负责将合并提交镜像回旧的默认分支。