分支

分支让你的团队开发工作井井有条且相互隔离。当多人同时开发不同功能时，分支可以防止变更相互冲突。每个分支都充当一个独立的工作空间，你可以在其中实现新功能、修复错误或尝试新想法。

使用分支，你的团队可以：

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

分支的开发工作流程是：

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

查看所有分支

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

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

在此页面，你可以：

• 查看所有分支，或筛选只显示活跃或过期的分支。

  如果在过去三个月内有提交到分支，则该分支被视为活跃分支。 否则被视为过期分支。

• 创建新分支。

• 比较分支。

• 删除已合并的分支。

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

  合并请求不指向默认分支的分支会显示 新建 合并请求按钮。

• 查看分支规则。

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

创建分支

先决条件：

• 你必须拥有项目至少的 Developer 角色。

要从 GitLab UI 创建新分支：

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

在空白项目中

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

先决条件：

• 你必须拥有项目至少的 Developer 角色。
• 如果你没有 Maintainer 或 Owner 角色，则 默认分支保护 必须设置为 部分保护 或 未保护，以便你能够向默认分支推送提交。

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

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

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

从问题创建

查看问题时，你可以直接从该页面创建关联的分支。这样创建的分支使用 从问题创建分支的默认模式， 包括变量。

先决条件：

• 你必须拥有项目至少的 Developer 角色。

要从问题创建分支：

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

有关在空仓库中创建分支的信息，请参阅 空仓库行为。

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

从任务创建

先决条件：

• 你必须拥有项目至少的 Developer 角色。

要从任务直接创建分支：

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 之前使用推送规则测试分支名称。
• 定义要在合并请求上运行的CI/CD 作业。

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

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

先决条件：

• 你必须拥有项目至少的 Maintainer 角色。

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

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

下载分支比较

你可以下载分支比较作为 diff 或补丁文件，以便在 GitLab 外使用。

作为 diff

要将分支比较下载为 diff，在比较 URL 中添加 format=diff：

• 如果 URL 没有查询参数，附加 ?format=diff：

  https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?format=diff

• 如果 URL 已有查询参数，附加 &format=diff：

  https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?from_project_id=2&format=diff

要下载并应用 diff：

curl "https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?format=diff" | git apply

作为补丁文件

要将分支比较下载为补丁文件，在比较 URL 中添加 format=patch：

• 如果 URL 没有查询参数，附加 ?format=patch：

  https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?format=patch

• 如果 URL 已有查询参数，附加 &format=patch：

  https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?from_project_id=2&format=patch

要使用 git am 下载并应用补丁：

# 下载并预览补丁
curl "https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?format=patch" > changes.patch
git apply --check changes.patch

# 应用补丁
git am changes.patch

你也可以在单个命令中下载并应用补丁：

curl "https://gitlab.example.com/my-group/my-project/-/compare/main...feature-branch?format=patch" | git am

删除已合并的分支

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

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

先决条件：

• 你必须拥有项目至少的 Developer 角色。

执行此操作：

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

配置目标分支的工作流

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

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

规则按"首次匹配"基础处理 - 如果两个规则匹配相同的分支名称，则应用最顶部的规则。

先决条件：

• 你必须拥有至少的 Maintainer 角色。

要创建目标分支工作流：

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

目标分支工作流示例

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

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

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

如果你的工作流最初将新功能放在 develop 而不是 main 中，这些目标分支 确保所有匹配 feature/* 或 bug/* 的分支不会错误地指向 main。

当你准备好发布到 main 时，创建一个名为 release/* 的分支， 并确保此分支指向 main。

删除目标分支工作流

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

先决条件：

• 你必须拥有至少的 Maintainer 角色。

执行此操作：

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

相关主题

• 受保护的分支
• 分支规则
• 比较合并请求中的变更
• 下载合并请求变更
• 分支 API
• 受保护分支 API
• Git 入门
• 分支简介

故障排除

包含相同提交的多个分支

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

%%{init: { "fontFamily": "GitLab Sans" }}%%
gitGraph
    accTitle: 包含相同提交的多个分支图
    accDescr: 分支 A 和 B 包含相同的提交，但分支 B 还包含其他提交。合并分支 B 使分支 A 看起来已合并，因为它的所有提交都已合并。
    commit id:"a"
    branch "branch A"
    commit id:"b"
    commit id:"c" type: HIGHLIGHT
    branch "branch B"
    commit id:"d"
    checkout "branch A"
    branch "branch C"
    commit id:"e"
    checkout main
    merge "branch B" id:"merges commits b, c, d"

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

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

错误：存在模糊的 HEAD 分支

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

错误：无法设置默认分支。你的仓库中是否有一个名为 'HEAD' 的分支？

要解决此问题：

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

错误：无法创建分支 4：超时

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

要解决此问题，选择以下之一：

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