更改默认分支

项目
04/16/2024

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

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

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

设置新默认分支

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

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

注意

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

在项目存储库下，选择分支。
在分支页上，选择所需新默认分支旁边的更多选项，然后选择设为默认分支。
设置新的默认分支后，可以根据需要删除以前的默认值。

选择项目左下角的设置按钮，打开项目管理页面。
选择存储库。
选择 Git 存储库。分支显示在存储库下。
选择要设置为默认分支的分支旁边的 ...，然后选择设置为默认分支。
设置新默认分支后，可以根据需要删除以前的默认分支。

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

选择名称

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 会使说明更难以理解。

镜像管道

注意

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

警告

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

对于所有现有 CI 生成，请将其更新为针对新的默认分支而非旧的默认分支触发。
向生成标识授予存储库的参与者权限。导航到项目设置>存储库>（你的存储库）>权限。最多可以有两个标识，一个用于项目集合生成服务，另一个用于项目生成服务。确保“参与”权限显示允许。

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

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

疑难解答

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

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

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

通过