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

将 Git 仓库克隆到你的本地计算机

你可以将 Git 仓库克隆到你的本地计算机。这个操作会创建一个仓库副本，并建立一个连接，用于同步你的计算机与 GitLab 服务器之间的更改。这个连接需要你添加凭证。你可以选择 使用 SSH 克隆 或 使用 HTTPS 克隆。SSH 是推荐的身份验证方法。

克隆仓库：

  • 下载所有项目文件、历史记录和元数据到你的本地机器。
  • 创建一个包含最新版本文件的工作目录。
  • 设置远程跟踪以同步未来的更改。
  • 提供对完整代码库的离线访问。
  • 为向项目贡献代码建立基础。

使用 SSH 克隆

当你只想进行一次身份验证时，使用 SSH 克隆。

  1. 按照 SSH 文档 中的说明与 GitLab 进行身份验证。

  2. 在左侧边栏，选择 搜索或跳转至 并找到你想要克隆的项目。

  3. 在项目的概览页面，右上角选择 Code，然后复制 使用 SSH 克隆 的 URL。

  4. 打开终端并进入你想要克隆文件的目录。 Git 会自动创建一个以仓库名命名的文件夹，并将文件下载到那里。

  5. 运行以下命令：

    git clone <复制的 URL>

  6. 要查看文件，进入新目录：

    cd <新目录>

使用 HTTPS 克隆

当你想要在每次执行计算机与 GitLab 之间的操作时都进行身份验证时，使用 HTTPS 克隆。 OAuth 凭证助手 可以减少手动身份验证的次数，使 HTTPS 体验更加无缝。

  1. 在左侧边栏，选择 搜索或跳转至 并找到你想要克隆的项目。

  2. 在项目的概览页面，右上角选择 Code，然后复制 使用 HTTPS 克隆 的 URL。

  3. 打开终端并进入你想要克隆文件的目录。

  4. 运行以下命令。Git 会自动创建一个以仓库名命名的文件夹，并将文件下载到那里。

    git clone <复制的 URL>

  5. GitLab 会请求你的用户名和密码。

    如果你在账户上启用了双因素认证（2FA），你不能使用账户密码。相反，你可以选择以下任一方法：

    如果你没有启用 2FA，请使用你的账户密码。

  6. 要查看文件，进入新目录：

    cd <新目录>

在 Windows 上，如果你多次输入密码错误并出现 “Access denied” 消息， 请将你的命名空间（用户名或组）添加到路径中： git clone https://[email protected]/gitlab-org/gitlab.git。

使用令牌克隆

如果你满足以下条件，请使用令牌通过 HTTPS 克隆：

  • 你想要使用 2FA。
  • 你想要拥有一组可撤销的、限定一个或多个仓库范围的凭证。

你可以使用以下任何令牌在通过 HTTPS 克隆时进行身份验证：

例如：

git clone https://<用户名>:<令牌>@gitlab.example.com/tanuki/awesome_project.git

克隆并在 Apple Xcode 中打开

包含 .xcodeproj 或 .xcworkspace 目录的项目可以克隆到 macOS 上的 Xcode 中。

  1. 从 GitLab 界面，转到项目的概览页面。
  2. 在右上角，选择 Code。
  3. 选择 Xcode。

项目会被克隆到你的计算机上，并提示你打开 Xcode。

克隆并在 Visual Studio Code 中打开

所有项目都可以从 GitLab 用户界面克隆到 Visual Studio Code 中，但你也可以安装 VS Code 的 GitLab Workflow 扩展 来从 Visual Studio Code 克隆。

先决条件：

  • 必须在你的本地计算机上安装 Visual Studio Code。 其他版本的 VS Code，如 VS Code Insiders 和 VSCodium，不受支持。

  • 为 IDE 协议配置你的浏览器。

  • 从 GitLab 界面：

    1. 转到项目的概览页面。

    2. 在右上角，选择 Code。

    3. 在 在你的 IDE 中打开 下，选择 Visual Studio Code (SSH) 或 Visual Studio Code (HTTPS)。

    4. 选择一个文件夹来克隆项目。

      Visual Studio Code 克隆你的项目后，会打开该文件夹。

  • 从 Visual Studio Code，安装了 扩展 后，使用扩展的 Git: Clone 命令。

克隆并在 IntelliJ IDEA 中打开

所有项目都可以从 GitLab 用户界面克隆到 IntelliJ IDEA 中。

先决条件：

操作步骤：

  1. 转到项目的概览页面。
  2. 在右上角，选择 Code。
  3. 在 在你的 IDE 中打开 下，选择 IntelliJ IDEA (SSH) 或 IntelliJ IDEA (HTTPS)。

为 IDE 协议配置浏览器

为确保 在 IDE 中打开 功能正常工作，你必须配置浏览器以处理自定义应用程序协议，如 vscode:// 或 jetbrains://。

Firefox

如果系统上安装了所需的应用程序，Firefox 会自动处理自定义协议。当你第一次选择自定义协议链接时，会打开一个对话框，询问你是否要打开应用程序。选择 打开链接 以允许 Firefox 打开应用程序。

如果你不想再次被提示，请选择复选框以记住你的选择。

如果提示对话框没有打开，你需要手动配置 Firefox：

  1. 打开 Firefox。
  2. 在右上角，选择 打开应用程序菜单（ hamburger ）。
  3. 搜索或转到 应用程序 部分。
  4. 在列表中找到并选择你想要的应用程序。例如，vscode 或 jetbrains。
  5. 从下拉列表中选择 Visual Studio Code 或 IntelliJ IDEA，或选择 使用其他… 来定位可执行文件。

如果你首选的 IDE 没有列出，当你第一次选择相应的链接时，系统会提示你选择一个应用程序。

Chrome

如果系统上安装了所需的应用程序，Chrome 会自动处理自定义协议。当你第一次在 Chrome 中选择自定义协议链接时，会打开一个对话框，询问你是否要打开应用程序。选择 打开 以允许 Chrome 打开应用程序。

如果你不想再次被提示，请选择复选框以记住你的选择。

减少克隆大小

随着 Git 仓库的增长，它们可能会变得难以使用，原因包括：

  • 必须下载的大量历史记录。
  • 它们需要的大量磁盘空间。

部分克隆 是一种性能优化，允许 Git 在没有完整仓库副本的情况下运行。这项工作的目标是让 Git 能够更好地处理极大的仓库。

需要 Git 2.22.0 或更高版本。

按文件大小过滤

通常不建议在 Git 中存储大型二进制文件，因为每次添加的大文件都会被之后克隆或获取更改的每个人下载。这些下载速度很慢且存在问题，特别是在使用慢速或不稳定的互联网连接时。

使用带文件大小过滤器的部分克隆可以解决这个问题，通过在克隆和获取时排除有问题的文件。当 Git 遇到缺失的文件时，它会按需下载。

克隆仓库时，使用 --filter=blob:limit=<size> 参数。例如，要克隆排除大于 1 兆字节的文件的仓库：

git clone --filter=blob:limit=1m [email protected]:gitlab-com/www-gitlab-com.git

这将产生以下输出：

Cloning into 'www-gitlab-com'...
remote: Enumerating objects: 832467, done.
remote: Counting objects: 100% (832467/832467), done.
remote: Compressing objects: 100% (207226/207226), done.
remote: Total 832467 (delta 585563), reused 826624 (delta 580099), pack-reused 0
Receiving objects: 100% (832467/832467), 2.34 GiB | 5.05 MiB/s, done.
Resolving deltas: 100% (585563/585563), done.
remote: Enumerating objects: 146, done.
remote: Counting objects: 100% (146/146), done.
remote: Compressing objects: 100% (138/138), done.
remote: Total 146 (delta 8), reused 144 (delta 8), pack-reused 0
Receiving objects: 100% (146/146), 471.45 MiB | 4.60 MiB/s, done.
Resolving deltas: 100% (8/8), done.
Updating files: 100% (13008/13008), done.
Filtering content: 100% (3/3), 131.24 MiB | 4.65 MiB/s, done.

输出会更长，因为 Git：

  1. 克隆排除大于 1 兆字节的文件的仓库。
  2. 下载任何缺失的、检出默认分支所需的大文件。

在更改分支时，Git 可能会下载更多缺失的文件。

按对象类型过滤

对于包含数百万个文件和长历史的仓库，你可以排除所有文件，并使用 git sparse-checkout 来减少工作副本的大小。

# 克隆排除所有文件的仓库
$ git clone --filter=blob:none --sparse [email protected]:gitlab-com/www-gitlab-com.git
Cloning into 'www-gitlab-com'...
remote: Enumerating objects: 678296, done.
remote: Counting objects: 100% (678296/678296), done.
remote: Compressing objects: 100% (165915/165915), done.
remote: Total 678296 (delta 472342), reused 673292 (delta 467476), pack-reused 0
Receiving objects: 100% (678296/678296), 81.06 MiB | 5.74 MiB/s, done.
Resolving deltas: 100% (472342/472342), done.
remote: Enumerating objects: 28, done.
remote: Counting objects: 100% (28/28), done.
remote: Compressing objects: 100% (25/25), done.
remote: Total 28 (delta 0), reused 12 (delta 0), pack-reused 0
Receiving objects: 100% (28/28), 140.29 KiB | 341.00 KiB/s, done.
Updating files: 100% (28/28), done.

$ cd www-gitlab-com

$ git sparse-checkout set data --cone
remote: Enumerating objects: 301, done.
remote: Counting objects: 100% (301/301), done.
remote: Compressing objects: 100% (292/292), done.
remote: Total 301 (delta 16), reused 102 (delta 9), pack-reused 0
Receiving objects: 100% (301/301), 1.15 MiB | 608.00 KiB/s, done.
Resolving deltas: 100% (16/16), done.
Updating files: 100% (302/302), done.

有关更多详细信息，请参阅 Git 文档中的 sparse-checkout。

按文件路径过滤

通过 --filter=sparse:oid=<blob-ish> 过滤器规范，可以实现部分克隆与稀疏检出的更深层次集成。这种过滤模式使用类似于 .gitignore 文件的格式来指定克隆和获取时要包含的文件。

使用 sparse 过滤器的部分克隆仍处于实验阶段。在克隆和获取时，它可能会很慢并显著增加 Gitaly 的资源利用率。请改用 过滤所有 blob 并使用稀疏检出，因为 git-sparse-checkout 简化了这种部分克隆的使用并克服了其局限性。

有关更多详细信息，请参阅 Git 文档中的 rev-list-options。

  1. 创建一个过滤器规范。例如，考虑一个包含许多应用程序的单体仓库，每个应用程序都在根目录的不同子目录中。创建一个文件 shiny-app/.filterspec：

    # 使用 `--filter=sparse:oid=shiny-app/.gitfilterspec` 执行部分克隆时，
# 只有文件中列出的路径才会被下载

# 显式包含配置稀疏检出所需的过滤器规范
# git config --local core.sparsecheckout true
# git show master:snazzy-app/.gitfilterspec >> .git/info/sparse-checkout
shiny-app/.gitfilterspec

# Shiny App
shiny-app/

# Dependencies
shimmery-app/
shared-component-a/
shared-component-b/

  2. 克隆并按路径过滤。克隆命令中对 --filter=sparse:oid 的支持尚未与稀疏完全集成。

    # 使用存储在服务器上的过滤器规范克隆过滤的对象集。警告：此步骤可能非常慢！
git clone --sparse --filter=sparse:oid=master:shiny-app/.gitfilterspec <URL>

# 可选：观察我们尚未获取的缺失对象
git rev-list --all --quiet --objects --missing=print | wc -l

    与 bash、Zsh 等的 Git 集成以及自动显示 Git 状态信息的编辑器通常会运行 git fetch，这会获取整个仓库。可能需要禁用或重新配置这些集成。

移除部分克隆过滤器

具有部分克隆过滤器的 Git 仓库可以移除过滤器。要移除过滤器：

  1. 获取所有被过滤器排除的内容，确保仓库完整。如果使用了 git sparse-checkout，请使用 git sparse-checkout disable 来禁用它。有关更多信息，请参阅 disable 文档。

    然后执行常规的 fetch 以确保仓库完整。要检查是否有缺失的对象需要获取，特别是当不使用 git sparse-checkout 时，可以使用以下命令：

    # 显示缺失的对象
git rev-list --objects --all --missing=print | grep -e '^\?'

# 显示没有 '?' 字符前缀的缺失对象（需要 GNU grep）
git rev-list --objects --all --missing=print | grep -oP '^\?\K\w+'

# 获取缺失的对象
git fetch origin $(git rev-list --objects --all --missing=print | grep -oP '^\?\K\w+')

# 显示缺失对象的数量
git rev-list --objects --all --missing=print | grep -e '^\?' | wc -l

  2. 重新打包所有内容。这可以通过 git repack -a -d 等命令完成。这应该只会在 .git/objects/pack/ 中留下三个文件：

    • 一个 pack-<SHA1>.pack 文件。
    • 其对应的 pack-<SHA1>.idx 文件。
    • 一个 pack-<SHA1>.promisor 文件。

  3. 删除 .promisor 文件。上一步应该只留下一个 pack-<SHA1>.promisor 文件，该文件应该是空的，应该被删除。

  4. 移除部分克隆配置。部分克隆相关的配置变量应该从 Git 配置文件中移除。通常只需要移除以下配置：

    • remote.origin.promisor。
    • remote.origin.partialclonefilter。