极狐GitLab 分支管理功能介绍

极狐GitLab 是 GitLab 在中国的发行版，关于中文参考文档和资料有：

• 极狐GitLab 中文文档
• 极狐GitLab 中文论坛
• 极狐GitLab 官网

分支 (BASIC ALL)

分支是项目工作树的一个版本。分支是项目开发的基础。当你创建一个新的项目时，极狐GitLab 会为你的仓库创建一个默认分支。默认分支设置可以在项目、子组、组或实例中配置。

随着项目的增长，团队会创建更多的分支。每个分支代表一组更改，这允许并行进行开发工作。一个分支中的开发工作不会影响另一个分支。

分支的开发工作流程是：

1.创建一个分支并向其添加提交。为了简化这个过程，你应该遵循分支命名模式。
2.当工作准备好进行审查时，创建一个合并请求以提议将分支中的更改合并。
3.使用审查应用预览更改。

4.请求审查。
5.在你的合并请求获得批准后，将你的分支合并到源分支。合并请求的合并方法决定了项目中如何处理合并请求。
6.在分支内容合并后，删除已合并的分支。

查看所有分支

要在极狐GitLab 用户界面中查看和管理分支：

1.在左侧边栏中，选择 搜索或转到 并找到你的项目。
2.在左侧边栏中，选择 代码 > 分支。

在此页面，你可以：

• 查看所有分支，或筛选以仅查看活跃或过时的分支。

• 如果在过去三个月内对分支进行了提交，则该分支被视为活跃分支。否则，它被视为过时分支。

• 创建新分支。

• 比较分支。

• 删除已合并的分支。

• 查看指向默认分支的合并请求链接。
  指向非默认分支的合并请求的分支会显示 {merge-request} 新建 合并请求按钮。

• 查看分支规则。

• 查看分支的最新流水线状态。

创建分支

在极狐GitLab UI 中创建新分支

前提条件：

• 你必须至少拥有项目的开发者角色。

要从极狐GitLab UI 创建新分支：

1.在左侧边栏中，选择 搜索或转到 并找到你的项目。
2.选择 代码 > 分支。
3.在右上角，选择 新建分支。
4.输入 分支名称。
5.在 创建自 中，选择分支的基础：现有分支、现有标签或提交 SHA。
6.选择 创建分支。

在空白项目中

一个空白项目不包含分支，但你可以添加一个。

前提条件：

• 你必须至少拥有项目的开发者角色。
• 如果你没有维护者或所有者角色，默认分支保护必须设置为部分保护或不保护，以便你可以向默认分支推送提交。

要向空白项目添加默认分支：

1.在左侧边栏中，选择 搜索或转到 并找到你的项目。
2.滚动到 此项目的存储库为空 并选择你想要添加的文件类型。
3.在 Web IDE 中，对该文件进行任何所需的更改，然后选择 创建提交。
4.输入提交消息，然后选择 提交。

极狐GitLab 会创建一个默认分支并将你的文件添加到其中。

从议题创建分支

在查看议题时，你可以直接从该页面创建关联的分支。以这种方式创建的分支使用从议题中创建分支的默认命名模式，包括变量。

前提条件：

• 你必须至少拥有项目的开发者角色。

要从议题中创建分支：

1.在左侧边栏中，选择 搜索或转到 并找到你的项目。
2.选择 计划 > 议题 并找到你的议题。
3.在议题描述下方，找到 创建合并请求 下拉列表，并选择 {chevron-down} 以显示下拉列表。
4.选择 创建分支。根据项目的默认命名模式，提供了一个默认的 分支名称。如果需要，输入不同的 分支名称。
5.选择 创建分支 以基于项目的默认分支创建分支。

命名您的分支

Git 强制执行分支命名规则，以确保分支名称与其他工具兼容。极狐GitLab 增加了额外的分支命名要求，并为结构良好的分支名称提供了额外的好处。

极狐GitLab 对所有分支强制执行以下额外规则：

• 分支名称中不允许有空格。
• 禁止使用包含 40 个十六进制字符的分支名称，因为它们与 Git 提交哈希值相似。
• 分支名称区分大小写。

常见的软件包（如 Docker）可能会强制执行额外的分支命名限制。

为了与其他软件包保持最佳兼容性，请仅使用：

• 数字
• 连字符 (-)
• 下划线 (_)
• ASCII 标准表中的小写字母

你可以在分支名称中使用正斜杠 (/) 和表情符号，但不能保证与其他软件包的兼容性。

具有特定格式的分支名称提供额外的好处：

• 通过在分支名称前加上议题编号简化合并请求工作流程。
• 根据分支名称自动化分支保护。
• 在将分支推送到 GitLab 之前，使用推送规则测试分支名称。
• 定义在合并请求上运行的CI/CD 作业。

配置从议题创建分支的默认模式

默认情况下，极狐GitLab 在从议题创建分支时使用模式 %{id}-%{title}，但你可以更改此模式。

前提条件：

• 你必须至少拥有项目的维护者角色。

要更改从议题创建分支的默认模式：

1.在左侧边栏中，选择 搜索或转到 并找到你的项目。
2.选择 设置 > 仓库。
3.展开 分支默认值。
4.滚动到 分支名称模板 并输入一个值。该字段支持以下变量：

• %{id}：议题的数字 ID。

• %{title}：议题的标题，修改为仅使用 Git 分支名称中可接受的字符。

5.选择 保存更改。

在分支名称前加上议题编号

为了简化合并请求的创建，请以议题编号开头命名 Git 分支名称，后跟连字符。

例如，要将分支链接到议题 #123，请以 123- 开头命名分支。
议题和分支必须在同一个项目中。

极狐GitLab 使用议题编号将数据导入合并请求：

• 议题被标记为与合并请求相关。议题和合并请求显示相互链接。
• 分支连接到议题。
• 如果你的项目配置了默认关闭模式，合并合并请求时也会关闭相关议题。
• 如果合并请求在同一个项目中，而不是一个分叉，议题的里程碑和标签会被复制到合并请求中。

管理和保护分支

极狐GitLab 提供多种方法来保护各个分支。这些方法确保您的分支从创建到删除都能得到监督和质量检查。要查看和编辑分支保护，请参阅分支规则。

比较分支

要比较存储库中的分支：

1.在左侧边栏中，选择 搜索或转到 并找到你的项目。
2.选择 代码 > 比较修订。
3.选择 源 分支以搜索所需的分支。精确匹配优先显示。您可以使用以下运算符来优化搜索：

• ^ 匹配分支名称的开头：^feat 匹配 feat/user-authentication。

• $ 匹配分支名称的结尾：widget$ 匹配 feat/search-box-widget。

• *使用通配符匹配 ：branch*cache* 匹配 fix/branch-search-cache-expiration。

• 您可以组合运算符：^chore/*migration$ 匹配 chore/user-data-migration。

4.选择 目标 存储库和分支。精确匹配优先显示。
5.在 显示更改 下，选择比较分支的方法：

• 仅显示源分支的传入更改（默认）显示自两个分支的最新共同提交以来源分支的差异。它不包括源分支创建后对目标分支进行的无关更改。此方法使用 git diff <from>...<to> Git 命令。为了比较分支，此方法使用合并基而不是实际提交，因此从 cherry-pick 的提交中更改会显示为新更改。

• 包括源分支创建以来对目标分支的更改 显示两个分支之间的所有差异。此方法使用 git diff <from> <to> Git 命令。

6.选择 比较 以显示提交列表和更改的文件。
7.可选。要反转 源 和 目标，选择 交换修订（{substitute}）。

删除已合并的分支

如果已合并的分支满足以下所有条件，则可以批量删除：

• 它们不是受保护的分支。
• 它们已合并到项目的默认分支。

前提条件：

• 您必须至少拥有项目的开发者角色。

操作步骤：

1.在左侧边栏中，选择 搜索或转到 并找到你的项目。
2.选择 代码 > 分支。
3.在页面右上角，选择 更多 {ellipsis_v}。
4.选择 删除已合并的分支。
5.在对话框中，输入单词 delete 以确认，然后选择 删除已合并的分支。

注意：删除分支不会完全擦除所有相关数据。某些信息会保留以维护项目历史记录并支持恢复过程。有关更多信息，请参阅处理敏感信息。

为目标分支配置工作流 (PREMIUM ALL)

• 在 GitLab 16.4 中引入，带有名为 target_branch_rules_flag 的标志。默认启用。

• 在 GitLab 16.7 中移除功能标志。

一些项目使用多个长期分支进行开发，如 develop 和 qa。
在这些项目中，你可能希望将 main 保持为默认分支，但希望合并请求目标指向 develop 或 qa。目标分支工作流有助于确保合并请求针对项目的适当开发分支。

当你创建合并请求时，工作流会检查分支名称。如果分支名称与工作流匹配，合并请求将针对你指定的分支。如果分支名称不匹配，合并请求将针对项目的默认分支。

规则按“首次匹配”原则处理 - 如果两个规则匹配同一个分支名称，则应用最上面的规则。

前提条件：

• 你必须至少拥有维护者角色。

要创建目标分支工作流：

1.在左侧边栏中，选择 搜索或转到 并找到你的项目。
2.选择 设置 > 合并请求。
3.向下滚动到 合并请求分支工作流
4.选择 添加分支目标。
5.对于 分支名称模式，提供一个字符串或通配符以与分支名称进行比较。
6.选择 目标分支，当分支名称与 分支名称模式 匹配时使用。
7.选择 保存。

目标分支工作流示例

你可以将项目配置为具有以下目标分支工作流：

分支名称模式	目标分支
feature/*	develop
bug/*	develop
release/*	main

这些目标分支简化了为项目创建合并请求的过程，该项目：

• 使用 main 表示应用程序的已部署状态。
• 在另一个长期运行的分支（如 develop）中跟踪当前未发布的开发工作。

如果你的工作流最初将新功能放在 develop 而不是 main 中，这些目标分支确保所有匹配 feature/* 或 bug/* 的分支不会错误地针对 main。
当你准备发布到 main 时，创建一个名为 release/* 的分支，并确保该分支针对 main。

删除目标分支工作流

当你删除目标分支工作流时，现有的合并请求保持不变。
前提条件：

• 你必须至少拥有维护者角色。

操作步骤：

1.在左侧边栏中，选择 搜索或转到 并找到你的项目。
2.选择 设置 > 合并请求。
3.在你要删除的分支目标上选择 删除。

故障排除

包含相同提交的多个分支
从更深的技术层面来看，Git 分支不是独立的实体，而是附加到一组提交 SHA 的标签。当极狐GitLab 确定分支是否已合并时，它会检查目标分支是否存在这些提交 SHA。
这种行为可能会在两个合并请求包含相同提交时导致意外结果。在此示例中，分支 B 和 C 都从分支 A 的相同提交 (3) 开始：

如果你合并分支 B，分支 A 也会显示为已合并（无需任何操作），因为分支 A 的所有提交现在都出现在目标分支 main 中。分支 C 仍然未合并，因为提交 5 不是分支 A 或 B 的一部分。

合并请求 A 保持合并状态，即使你尝试将新提交推送到其分支。如果合并请求 A 中的任何更改未合并（因为它们不是合并请求 A 的一部分），请为它们打开一个新的合并请求。

错误：存在歧义的 HEAD 分支

在 2.16.0 之前的 Git 版本中，你可以创建一个名为 HEAD 的分支。
这个名为 HEAD 的分支与 Git 用于描述活动（已检出）分支的内部引用（也名为 HEAD）发生冲突。此命名冲突可能会阻止你更新存储库的默认分支：

Error: Could not set the default branch. Do you have a branch named 'HEAD' in your repository?

要解决此问题：

1.在左侧边栏中，选择 搜索或转到 并找到你的项目。
2.选择 代码 > 分支。
3.搜索名为 HEAD 的分支。
4.确保该分支没有未提交的更改。
5.选择 删除分支，然后选择 是，删除分支。

Git 版本 2.16.0 及更高版本，防止你创建具有此名称的分支。

查找你创建的所有分支

要在项目中查找你创建的所有分支，请在 Git 存储库中运行此命令：

git for-each-ref --format='%(authoremail) %(refname:short)' | grep $(git config --get user.email)

要获取项目中所有分支的总数，并按作者排序，请在 Git 存储库中运行此命令：

git for-each-ref --format='%(authoremail)'  | sort | uniq -c | sort -g

错误：Failed to create branch 4:Deadline Exceeded

此错误是由 Gitaly 中的超时引起的。当创建分支所需时间超过配置的超时时间时，会发生此错误。
要解决此问题，请选择以下方法之一：

• 禁用耗时的服务器钩子。请参阅 Git 服务器钩子。
• 增加 Gitaly 的超时设置。请参阅 Gitaly 超时。