更改默认分支

2025-10-08

Azure DevOps Services |Azure DevOps Server |Azure DevOps Server 2022 |Azure DevOps Server 2020

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

我们将演练更改默认分支的过程。我们还将介绍在进行此更改时必须考虑和更新的其他事项。最后，我们将介绍一个用于缓解转换的工具。

先决条件

类别	要求
项目访问权限	项目的成员。
权限	- 查看专用项目中的代码：至少是基本访问权限。 - 克隆或参与专用项目中的代码：参与者安全组的成员或项目中的相应权限。 - 设置分支或存储库权限：管理分支或存储库的权限。 - 更改默认分支：编辑存储库的策略权限。 - 导入存储库：项目管理员安全组的成员或 Git 项目级 “创建存储库 ”权限设置为 “允许”。有关详细信息，请参阅设置 Git 存储库权限。
Services	已启用存储库。
工具	可选。使用 az repos 命令： Azure DevOps CLI。

注释

在公共项目中，具有 利益干系人 访问权限的用户具有对 Azure Repos 的完全访问权限，包括查看、克隆和参与代码。

类别	要求
项目访问权限	项目的成员。
权限	- 查看代码：至少基本访问权限。 - 克隆或参与代码：参与者安全组的成员或项目中的相应权限。
Services	已启用存储库。

设置新的默认分支

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

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

注释

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

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

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

选择名称

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

更新其他系统

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

Pipelines

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

正在进行的拉取请求

将每个打开的拉取请求重新定位到新的默认分支。

现有克隆

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

传入链接

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

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

临时镜像

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选择在上一步中添加的文件。保存并运行管道。

Troubleshooting

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

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

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

反馈

此页面是否有帮助？