默认分支

当你创建一个新的 project 时，GitLab 会在仓库中创建一个默认分支。默认分支拥有其他分支所没有的特殊配置选项：

• 它不能被删除。
• 它 初始受保护，防止强制推送。
• 当合并请求使用 issue closing pattern 关闭 issue 时，工作内容会被合并到这个分支。

你的 new project’s 默认分支名称取决于你的 GitLab 管理员对实例或组所做的任何配置更改。GitLab 首先检查特定的自定义设置，然后在更广泛的级别进行检查，只有在没有设置自定义时才使用 GitLab 默认值：

1. 项目特定的 自定义默认分支名称。
2. 在项目的直接子组中指定的 自定义组默认分支名称。
3. 在项目的顶级组中指定的自定义组默认分支名称。
4. 为 instance 设置的自定义默认分支名称。
5. 如果在任何级别都没有设置自定义默认分支名称，GitLab 默认使用 main。

在 GitLab UI 中，你可以在任何级别更改默认设置。GitLab 还提供了 你需要的 Git 命令 来更新你的仓库副本。

更改项目的默认分支名称

前提条件：

• 你拥有项目的 Owner 或 Maintainer 角色。

要更新单个 project 的默认分支：

1. 在左侧边栏，选择 Search or go to 并找到你的项目。
2. 选择 Settings > Repository。
3. 展开 Branch defaults。对于 Default branch，选择一个新的默认分支。
4. 可选。勾选 Auto-close referenced issues on default branch 复选框，以便在合并请求 使用关闭模式 时关闭 issue。
5. 选择 Save changes。

API 用户也可以在创建或编辑项目时使用 Projects API 的 default_branch 属性。

更改实例中新建项目的默认分支名称

GitLab Self-Managed 的 Administrators 可以 自定义在该实例上托管的项目的初始分支。单独的组和子组可以覆盖其实例的默认设置。

1. 在左侧边栏底部，选择 Admin。
2. 选择 Settings > Repository。
3. 展开 Default branch。
4. 对于 Initial default branch name，选择一个新的默认分支。
5. 选择 Save changes。

更改设置后，在此实例上创建的项目将使用自定义分支名称，除非组或子组配置覆盖了它。

更改组中新建项目的默认分支名称

前提条件：

• 你必须拥有组和子组的 Owner 角色。

要更改组中新建项目的默认分支名称：

1. 在左侧边栏，选择 Search or go to 并找到你的组。
2. 选择 Settings > Repository。
3. 展开 Default branch。
4. 对于 Initial default branch name，选择一个新的默认分支。
5. 选择 Save changes。

更改设置后，在此组中创建的项目将使用自定义分支名称，除非子组配置覆盖了它。

保护初始默认分支

GitLab 管理员和组所有者可以定义 branch protections 应用于实例或单个组的每个仓库的默认分支，使用以下选项之一：

• Fully protected - 默认值。开发者不能推送新的提交，但维护者可以。 没有人可以强制推送。
• Fully protected after initial push - 开发者可以推送初始提交 到仓库，但之后不能。维护者总是可以推送。没有人可以强制推送。
• Protected against pushes - 开发者不能推送新的提交，但 允许接受合并请求到该分支。维护者可以推送到该分支。
• Partially protected - 开发者和维护者都可以推送新的提交， 但不能强制推送。
• Not protected - 开发者和维护者都可以推送新的提交 和强制推送。

为实例中的所有项目

此设置仅适用于每个仓库的默认分支。要保护其他分支，你必须：

• 在仓库中配置 branch protection。
• 为组配置 branch protection。

GitLab Self-Managed 实例的管理员可以自定义在该实例上托管的项目的初始默认分支保护。单独的组和子组可以覆盖其实例的默认设置。

1. 在左侧边栏底部，选择 Admin。
2. 选择 Settings > Repository。
3. 展开 Default branch。
4. 选择 Initial default branch protection。
5. 要允许组所有者覆盖实例的默认分支保护，选择 Allow owners to manage default branch protection per group。
6. 选择 Save changes。

防止覆盖默认分支保护

组所有者可以按组覆盖为整个实例设置的默认分支保护。在 GitLab Premium or Ultimate 中，GitLab 管理员可以 禁用组所有者的此权限，强制执行为实例设置的保护规则：

1. 在左侧边栏底部，选择 Admin。
2. 选择 Settings > Repository。
3. 展开 Default branch 部分。
4. 取消勾选 Allow owners to manage default branch protection per group 复选框。
5. 选择 Save changes。

为组中的所有项目

组所有者可以按组覆盖为整个实例设置的默认分支保护。在 GitLab Premium or Ultimate 中，GitLab 管理员可以 强制保护初始默认分支， 这会锁定组所有者的此设置。

1. 在左侧边栏，选择 Search or go to 并找到你的组。
2. 选择 Settings > Repository。
3. 展开 Default branch。
4. 选择 Initial default branch protection。
5. 选择 Save changes。

更新仓库中的默认分支名称

当你更改现有仓库的默认分支名称时，不要创建新分支。通过重命名来保留默认分支的历史。此示例重命名 Git 仓库（example）的默认分支：

1. 在你的本地命令行中，进入你的 example 仓库，并确保 你在默认分支上：

   cd example
   git checkout master

2. 将现有的默认分支重命名为新名称（main）。参数 -m 将所有提交历史转移到新分支：

   git branch -m master main

3. 将新创建的 main 分支推送到上游，并设置你的本地分支以跟踪 同名的远程分支：

   git push -u origin main

4. 如果计划删除旧的默认分支，更新 HEAD 以指向你的新默认分支 main：

   git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main

5. 使用至少 Maintainer 角色登录 GitLab，并按照说明 更改此项目的默认分支。 选择 main 作为你的新默认分支。

6. 按照 protected branches documentation 中的描述保护你的新 main 分支。

7. 可选。如果要删除旧的默认分支：

   1. 确保没有东西指向它。

   2. 删除远程分支：

      git push origin --delete master

      确认新默认分支按预期工作后，你可以稍后删除该分支。

8. 通知你的项目贡献者此变更，因为他们也必须采取一些步骤：

   • 贡献者应该将新的默认分支拉取到他们的仓库本地副本中。
   • 有针对旧默认分支的开放合并请求的贡献者应该手动 重新指向合并请求以使用 main。

9. 在你的仓库中，更新代码中对旧分支名称的任何引用。

10. 更新位于你仓库外部的相关代码和脚本中对旧分支名称的引用，例如辅助工具和集成。

默认分支重命名重定向

项目中特定文件或目录的 URL 嵌入了项目的默认分支名称，通常出现在文档或浏览器书签中。当你 更新仓库中的默认分支名称 时， 这些 URL 会更改，必须更新。

为了过渡期，每当项目的默认分支被更改时，GitLab 会记录旧默认分支的名称。如果该分支被删除， 尝试查看其上的文件或目录会被重定向到当前默认分支，而不是显示"未找到"页面。

相关主题

• 为你的 wiki 配置默认分支
• Git 邮件列表上的默认分支重命名讨论
• 2021年3月博客文章：新的 Git 默认分支名称

故障排除

无法更改默认分支：重置为当前分支

我们在 issue 20474 中跟踪此问题。 当仓库中存在名为 HEAD 的分支时，此问题经常发生。要修复此问题：

1. 在你的本地仓库中，创建一个新的临时分支并推送它：

   git checkout -b tmp_default && git push -u origin tmp_default

2. 在 GitLab 中，继续 更改默认分支 到该临时分支。

3. 从你的本地仓库中，删除 HEAD 分支：

   git push -d origin HEAD

4. 在 GitLab 中，更改默认分支 到你打算使用的分支。

使用 GraphQL 查询默认分支

你可以使用 GraphQL query 来检索组中所有项目的默认分支。

要在单个结果页面中返回所有项目，将 GROUPNAME 替换为你的组的完整路径。GitLab 返回第一页结果。如果 hasNextPage 为 true，你可以通过将 after: null 中的 null 替换为 endCursor 的值来请求下一页：

{
 group(fullPath: "GROUPNAME") {
   projects(after: null) {
     pageInfo {
       hasNextPage
       endCursor
     }
     nodes {
       name
       repository {
         rootRef
       }
     }
   }
 }
}

新子组不会从更高级别的子组继承默认分支名称

当你在包含另一个包含项目的子组的子组中配置默认分支时，默认分支不会被继承。

我们在 issue 327208 中跟踪此问题。