Help us learn about your current experience with the documentation. Take the survey.

分支

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Fork 是另一个 Git 仓库的个人副本，放置在您选择的命名空间中。 您的副本包含上游仓库的内容，包括所有分支、标签和 CI/CD 作业配置。 您可以从您的 fork 创建合并请求，以定位到上游仓库。 单个提交也可以从您的 fork cherry-picked 到上游仓库。

如果您对原始仓库有写入权限，则不需要 fork。 相反，使用分支来管理工作。 如果您想要贡献的仓库没有写入权限，请 fork 它。 在您的 fork 中进行更改，然后通过合并请求提交到上游仓库。

要创建 confidential merge request， 请使用公共仓库的个人 fork。

如果上游项目被归档，fork 关系将自动移除。 由于 fork 关系中断而关闭的合并请求不会重新打开， 即使 fork 关系后来被恢复。

有关更多信息，请参阅 Archive a project。

创建 fork

要在 GitLab 中 fork 现有项目：

  1. 在项目主页的右上角，选择 Fork ( fork )。
  2. 可选。编辑 Project name。
  3. 对于 Project URL，选择您的 fork 应该所属的 namespace。
  4. 添加一个 Project slug。此值将成为您 fork URL 的一部分。 它在命名空间中必须是唯一的。
  5. 可选。添加一个 Project description。
  6. 选择一个 Branches to include 选项：
    • All branches (默认)。
    • Only the default branch。使用 --single-branch 和 --no-tags Git options。
  7. 为您的 fork 选择 Visibility level。有关 可见性级别的更多信息，请阅读 Project and group visibility。
  8. 选择 Fork project。

GitLab 会创建您的 fork，将您重定向到新 fork 的页面，并在 audit log 中记录 fork 的创建。

如果您打算频繁向上游贡献更改，请考虑为您的 fork 设置一个 default target。

更新您的 fork

Fork 可能会与其上游仓库不同步，需要更新：

  • Ahead：您的 fork 包含上游仓库中不存在的新提交。 要同步您的 fork，请创建合并请求以将您的更改推送到上游仓库。
  • Behind：上游仓库包含您的 fork 中不存在的新提交。 要同步您的 fork，请将新提交拉取到您的 fork 中。
  • Ahead and behind：上游仓库和您的 fork 都包含彼此中不存在的新提交。 要完全同步您的 fork，请创建合并请求以推送您的更改，并将上游仓库的新更改拉取到您的 fork 中。

要将您的 fork 与其上游仓库同步，请从 GitLab UI 或命令行更新它。 GitLab Premium 和 Ultimate 版本还可以通过 将 fork 配置为上游仓库的拉取镜像 来自动更新。

从 UI 更新

先决条件：

要从 GitLab UI 更新您的 fork：

  1. 在左侧边栏，选择 Search or go to。

  2. 选择 View all my projects。

  3. 选择您要更新的 fork。

  4. 在分支名称的下拉列表下方，找到 Forked from ( fork ) 信息框，以确定您的 fork 是领先、落后还是两者兼有。在此示例中， fork 落后于上游仓库：

    Information box for a fork some commits behind the upstream repository

  5. 如果您的 fork 领先 于上游仓库，请选择 Create merge request 以提议将您的 fork 的更改添加到上游仓库。

  6. 如果您的 fork 落后 于上游仓库，请选择 Update fork 以从上游仓库拉取更改。

  7. 如果您的 fork 领先和落后 于上游仓库，只有在 GitLab 检测到没有合并冲突时才能从 UI 更新：

    • 如果您的 fork 不包含合并冲突，您可以选择 Create merge request 以提议将您的更改推送到上游仓库，Update fork 以将更改拉取到您的 fork，或两者都选。您 fork 中的更改类型 决定了哪些操作是合适的。
    • 如果您的 fork 包含合并冲突，GitLab 会显示一个逐步指南，指导您从命令行更新您的 fork。

从命令行更新

您也可以选择从命令行更新您的 fork。

先决条件：

要从命令行更新您的 fork，请按照 使用 Git 更新 fork 中的说明操作。

使用仓库镜像

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

如果满足以下所有条件，可以将 fork 配置为上游的镜像：

  1. 您的订阅是 GitLab Premium 或 GitLab Ultimate。
  2. 您在分支中创建所有更改（不是 main）。
  3. 您不处理 confidential issues 的合并请求， 这需要对 main 进行更改。

Repository mirroring 保持您的 fork 与原始仓库同步。 此方法每小时更新您的 fork 一次，无需手动 git pull。 有关说明，请阅读 Configure pull mirroring。

使用镜像时，在批准合并请求之前，系统会要求您同步。您应该自动化它。

将更改合并回上游

当您准备将代码发送回上游仓库时，请按照 When you work in a fork 中的描述创建新的合并请求。 成功合并后，您的更改将被添加到您正在合并到的仓库和分支中。

取消链接 fork

移除 fork 关系会将您的 fork 与其上游仓库取消链接。 您的 fork 然后成为一个独立的仓库。

先决条件：

  • 您必须是项目所有者才能取消链接 fork。

如果您移除 fork 关系，您无法向源发送新的合并请求。 任何从 fork 到源的开放合并请求也将被关闭。 如果任何人 fork 了您的仓库，他们的 fork 也会失去关系。 要恢复 fork 关系，使用 API。

要移除 fork 关系：

  1. 在左侧边栏，选择 Search or go to 并找到您的项目。
  2. 选择 Settings > General。
  3. 展开 Advanced。
  4. 在 Remove fork relationship 部分，选择 Remove fork relationship。
  5. 确认，输入项目路径并选择 Confirm。

GitLab 在 audit log 中记录取消链接操作。 当您取消链接使用 hashed storage pool 与另一个仓库共享对象的 fork 时：

  • 所有对象都会从池复制到您的 fork 中。
  • 复制过程完成后，不会再有来自存储池的更新传播到您的 fork。

检查 fork 的存储使用情况

您的 fork 使用去重策略 来减少其所需的存储空间。您的 fork 可以访问连接到源仓库的对象池。

有关更多信息并检查存储使用情况，请参阅 View project fork storage usage。

相关主题

故障排除

错误：An error occurred while forking the project. Please try again

此错误可能是由于 fork 项目和新命名空间之间的实例 runner 设置不匹配造成的。 有关更多信息，请参阅 Runner 文档中的 Forks。

移除 fork 关系失败

如果通过 UI 或 API 移除 fork 不起作用，您可以尝试在 Rails console session 中 移除 fork 关系：

p = Project.find_by_full_path('<project_path>')
u = User.find_by_username('<username>')
Projects::UnlinkForkService.new(p, u).execute