分支

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: JihuLab.com, 私有化部署

分支保持团队的开发工作有序且分离#

分支使团队的开发工作保持有序和分离。当多个人员同时开发不同功能时,分支可以防止变更发生冲突。每个分支都充当一个隔离的工作空间,在其中实施新功能、修复错误或实验想法。

使用分支,团队可以:

  • 在不干扰主代码库的情况下开发独立的功能。
  • 在变更影响项目其他部分之前进行审查。
  • 回滚有问题的变更而不影响其他工作。
  • 以可控、可预测的方式将变更部署到生产环境。

分支的开发工作流是:

  1. 创建一个分支并向其添加提交。为了简化这个过程,你应该遵循分支命名模式
  2. 当工作准备好进行审查时,创建一个合并请求,以提议将你的分支中的变更合并。
  3. 使用审查应用预览变更。
  4. 请求审查
  5. 在你的合并请求获得批准后,将你的分支合并到源分支。合并请求的合并方法决定了项目中如何处理合并请求。
  6. 在分支内容被合并后,删除已合并的分支

查看所有分支#

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

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

在此页面上,你可以:

  • 查看所有分支,或筛选以仅查看活动或过时分支。

    如果在过去三个月内向分支进行了提交,则认为该分支是活动的。否则将被视为过时。

  • 创建新分支

  • 比较分支

  • 删除已合并的分支

  • 查看指向默认分支的合并请求链接。

    指向非默认分支的合并请求的分支会显示

    New 合并请求按钮。

  • 查看分支规则

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

创建一个分支#

先决条件:

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

要从极狐GitLab 用户界面创建一个新分支:

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

在一个空项目中#

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

先决条件:

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

要将默认分支添加到空项目:

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

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

从议题创建分支#

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

先决条件:

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

要从议题创建分支:

  1. 在左侧边栏,选择 搜索或前往 并找到你的项目。
  2. 选择 计划 > 议题 并找到你的议题。
  3. 在议题描述下,选择 创建合并请求 以显示下拉列表。
  4. 选择 创建分支
  5. 在对话框中,从 来源(分支或标签) 下拉列表中选择一个源分支或标签。
  6. 查看建议的分支名称。它基于项目的议题分支名称的默认模式
  7. 可选。如果需要使用不同的分支名称,请在 分支名称 文本框中输入。
  8. 选择 创建分支

有关在空存储库中创建分支的信息,请参见空存储库行为

如果创建的分支名称以议题编号为前缀,极狐GitLab 会交叉链接议题和相关的合并请求。

从任务创建分支#

先决条件:

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

要直接从任务创建分支:

  1. 在左侧边栏,选择 搜索或前往 并找到你的项目。
  2. 选择 计划 > 议题
  3. 在议题列表中找到你的任务。
  4. 在任务描述下,选择 创建合并请求 以显示下拉列表。
  5. 选择 创建分支
  6. 在对话框中,从 来源分支或标签 下拉列表中选择一个源分支或标签。
  7. 查看建议的分支名称。它基于项目的议题分支名称的默认模式
  8. 可选。如果需要使用不同的分支名称,请在 分支名称 文本框中输入。
  9. 选择 创建分支

有关在空存储库中创建分支的信息,请参见空存储库行为

如果创建的分支名称以任务编号为前缀,极狐GitLab 会交叉链接议题和相关的合并请求。

空存储库行为#

如果你的 Git 存储库为空,极狐GitLab:

  • 创建一个默认分支。
  • 提交一个空的 README.md 文件到该分支。
  • 创建并重定向你到一个基于议题标题的新分支。
  • 如果你的项目配置了 Kubernetes 等部署服务,极狐GitLab 会提示你设置自动部署,帮助你创建 .gitlab-ci.yml 文件。

命名你的分支#

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

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

  • 分支名称中不允许出现空格。
  • 禁止分支名称使用 40 个十六进制字符,因为它们类似于 Git 提交哈希。
  • 分支名称区分大小写。

常见的软件包,如 Docker,可以强制执行额外的分支命名限制

为了与其他软件包达到最佳兼容性,只使用:

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

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

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

配置议题分支名称的默认模式#

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

先决条件:

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

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

  1. 在左侧边栏,选择 搜索或前往 并找到你的项目。
  2. 选择 设置 > 仓库
  3. 展开 分支默认值
  4. 滚动到 分支名称模板 并输入一个值。该字段支持以下变量:
    • %{id}:议题的数字 ID。
    • %{title}:议题的标题,修改为仅使用在 Git 分支名称中接受的字符。
  5. 选择 保存更改

以数字为前缀的分支名称#

为了简化合并请求的创建,请以议题或任务编号为前缀来命名 Git 分支名称,后跟连字符。例如,要链接一个分支到议题 #123,请以 123- 开始分支名称。

分支必须与议题或任务处于同一项目中。

极狐GitLab 使用此编号将数据导入合并请求:

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

管理和保护分支#

极狐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-picked 提交的变更显示为新变更。
    • 包括自源分支创建以来对目标分支的变更 显示两个分支之间的所有差异。此方法使用 git diff <from> <to> Git 命令
  6. 选择 比较 显示提交列表和更改文件。
  7. 可选。要反转 源分支目标,选择 交换修订 ()。

删除已合并的分支#

已合并的分支可以批量删除,如果它们符合以下所有条件:

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

先决条件:

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

要执行此操作:

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

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

为目标分支配置工作流#

  • Tier: 专业版, 旗舰版
  • Offering: JihuLab.com, 私有化部署
History
    • 在极狐GitLab 16.4 中引入,使用名为 target_branch_rules_flag功能标志。默认启用。
    • 在极狐GitLab 16.7 中移除功能标志。

某些项目使用多个长期分支进行开发,例如 developqa。在这些项目中,你可能希望将 main 作为默认分支,但希望合并请求指向 developqa。目标分支工作流帮助确保合并请求针对项目的适当开发分支。

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

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

先决条件:

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

要创建目标分支工作流:

  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。这种行为可能导致两个合并请求包含相同提交时出现意外结果。在此示例中,分支 BC 都从分支 A 上的相同提交 (3) 开始:

Rendering chart...

如果你合并分支 B,分支 A 也会显示为已合并(无需你采取任何行动),因为分支 A 的所有提交现在都显示在目标分支 main 中。分支 C 仍然未合并,因为提交 5 不是分支 AB 的一部分。

合并请求 A 保持合并状态,即使你尝试向其分支推送新提交也是如此。如果合并请求 A 中的任何变更仍未合并(因为它们不是合并请求 A 的一部分),请为它们打开新的合并请求。

错误:存在模糊的 HEAD 分支#

在 Git 版本早于 2.16.0 的版本中,你可以创建一个名为 HEAD 的分支。此名为 HEAD 的分支与 Git 用于描述活动(已检出的)分支的内部引用(也称为 HEAD)发生冲突。此命名冲突可能会阻止你更新存储库的默认分支:

plaintext
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 存储库中运行以下命令:

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

要获得项目中所有分支的总数,并按作者排序,请在 Git 存储库中运行以下命令:

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

错误:Failed to create branch 4:Deadline Exceeded#

此错误是由 Gitaly 中的超时引起的。当创建分支所需的时间超过配置的超时时间时,会发生此错误。

要解决此问题,请选择以下之一: