片段（Snippets）

使用 GitLab 片段，您可以与其他用户存储和分享代码和文本片段。 您可以对片段进行评论、克隆和使用版本控制。 片段可以包含多个文件。它们还支持语法高亮、嵌入、下载， 您可以使用片段 API来管理您的片段。

您可以通过以下方式创建和管理您的片段：

• GitLab 用户界面。
• VS Code 的 GitLab Workflow 扩展。
• glab 命令行工具。

GitLab 提供两种类型的片段：

• 个人片段：独立于任何项目创建。 您可以为您的片段设置可见性级别：公开或私有。
• 项目片段：始终与特定项目相关联。 项目片段可以公开可见，或者仅对项目成员可见。

创建片段

您可以通过多种方式创建片段，具体取决于您要创建个人片段还是项目片段：

1. 选择您要创建的片段类型：
   • 要创建个人片段，请执行以下操作之一：
     • 在片段仪表板上，选择新建片段。
     • 从项目中：在左侧边栏，选择新建（ ）。在In GitLab下，选择新建片段。
     • 从任何其他页面：在左侧边栏，选择新建（ ），然后选择新建片段。
     • 从 glab CLI，使用 glab snippet create 命令。 有关完整说明，请参阅该命令的文档。
     • 如果您安装了VS Code 的 GitLab Workflow 扩展， 请使用 Gitlab: Create snippet 命令。
   • 要创建项目片段：转到您的项目页面。选择 新建（ ）。在In this project下，选择新建片段。
2. 在标题中，添加标题。
3. 可选。在描述中，描述片段。
4. 在文件中，为您的文件提供适当的名称和扩展名，例如 example.rb 或 index.html。 具有适当扩展名的文件名将显示语法高亮。 不添加文件名可能导致已知的复制粘贴错误。 如果您不提供文件名，GitLab 会为您创建一个名称。
5. 可选。向您的片段添加多个文件。
6. 选择可见性级别，然后选择创建片段。

创建片段后，您仍然可以向其添加更多文件。 片段默认是版本化的。

发现片段

要发现 GitLab 中所有对您可见的片段，您可以：

• 查看项目的片段：

  1. 在左侧边栏，选择搜索或转到并找到您的项目。
  2. 选择代码 > 片段。

• 查看您创建的所有片段：

  1. 在左侧边栏，选择搜索或转到。
  2. 选择您的工作。
  3. 选择片段。

  在 GitLab.com 上，您也可以直接访问您的片段。

• 探索所有公开片段：

  1. 在左侧边栏，选择搜索或转到。
  2. 选择探索。
  3. 选择片段。

  在 GitLab.com 上，您也可以直接访问所有公开片段。

更改片段的默认可见性

项目片段默认已启用并可用。要更改其默认可见性：

1. 在您的项目中，转到设置 > 常规。
2. 展开可见性、项目功能、权限部分，并滚动到片段。
3. 切换默认可见性，并选择片段是否可以被所有人查看，或仅限项目成员查看。
4. 选择保存更改。

版本化的片段

个人片段和项目片段默认都使用版本控制。

这意味着所有片段在创建时都会获得一个初始化的底层存储库，并带有默认分支。每当片段的更改被保存时，都会记录对默认分支的新提交。提交消息是自动生成的。片段的存储库只有一个分支。您不能删除此分支，或创建其他分支。

文件名

片段支持基于为其提供的文件名和扩展名的语法高亮。您可以提交没有文件名和扩展名的片段，但创建内容作为存储库中的文件需要有效的文件名。

如果未为片段提供文件名和扩展名，GitLab 会添加一个格式为 snippetfile<x>.txt 的文件名，其中 <x> 代表添加到文件中的数字，从 1 开始。如果您添加更多未命名的片段，此数字会增加。

从早期版本的 GitLab 升级到 13.0 时，没有支持文件名的现有片段将被重命名为兼容格式。例如，如果片段的文件名是 http://a-weird-filename.me，它将被更改为 http-a-weird-filename-me，以便包含在片段的存储库中。由于片段按 ID 存储，更改它们的文件名会破坏片段的直接或嵌入链接。

添加或删除多个文件

单个片段最多支持 10 个文件，这有助于将相关文件放在一起，例如：

• 包含脚本及其输出的片段。
• 包含 HTML、CSS 和 JavaScript 代码的片段。
• 包含 docker-compose.yml 文件及其关联的 .env 文件的片段。
• gulpfile.js 文件和 package.json 文件，它们可以一起用于引导项目并管理其依赖项。

如果您的片段需要超过 10 个文件，您应该创建一个wiki代替。Wiki 在所有订阅级别的项目中都可用，并且在GitLab Premium的组中也可用。

包含多个文件的片段在片段列表中显示文件计数：

您可以使用 Git（因为它们由 Git 存储库版本化）、通过片段 API以及在 GitLab UI 中管理片段。

要通过 GitLab UI 向您的片段添加新文件：

1. 在 GitLab UI 中转到您的片段。
2. 在右上角选择编辑。
3. 选择添加另一个文件。
4. 在提供的表单字段中为文件添加内容。
5. 选择保存更改。

要通过 GitLab UI 从您的片段中删除文件：

1. 在 GitLab UI 中转到您的片段。
2. 在右上角选择编辑。
3. 在每个要删除的文件名旁边选择删除文件。
4. 选择保存更改。

克隆片段

为确保您收到更新，请克隆片段而不是在本地复制它。克隆保持了片段与存储库的连接。

要克隆片段：

• 选择克隆，然后复制用于 SSH 或 HTTPS 克隆的 URL。

您可以对克隆的片段进行提交更改，并将更改推送到 GitLab。

嵌入片段

公开片段可以在任何网站上共享和嵌入。您可以在多个地方重用 GitLab 片段，并且对源的任何更改都会反映在嵌入的片段中。嵌入时，用户可以下载它，或以原始格式查看片段。

要嵌入片段：

1. 确认您的片段是公开可见的：

   • 如果是项目片段，项目必须是公开的。
   • 片段是公开可见的。
   • 在您的项目中，转到设置 > 常规。展开可见性、项目功能、权限 部分，并滚动到片段。将片段权限设置为所有有访问权限的人。

2. 在您的片段的嵌入部分，选择复制以复制一行脚本， 您可以将此脚本添加到任何网站或博客文章中。例如：

   <script src="https://gitlab.com/namespace/project/snippets/SNIPPET_ID.js"></script>

3. 将您的脚本添加到您的文件中。

嵌入的片段显示一个标题，显示：

• 文件名（如果已定义）。
• 片段大小。
• 到 GitLab 的链接。
• 实际的片段内容。

例如：

下载片段

您可以下载片段的原始内容。默认情况下，它们以 Linux 风格的行结束符 (LF) 下载。如果您想保留原始行结束符，必须添加参数 line_ending=raw （例如：https://gitlab.com/snippets/SNIPPET_ID/raw?line_ending=raw）。如果片段是使用 GitLab Web 界面创建的，原始行结束符是 Windows 风格的 (CRLF)。

评论片段

使用片段，您可以就那段代码进行对话，这可以促进用户协作。

将片段标记为垃圾邮件

GitLab 自托管的管理员可以将片段标记为垃圾邮件。

先决条件：

• 您必须是您实例的管理员。
• Akismet 垃圾邮件保护必须在实例上启用。

要执行此任务：

1. 在左侧边栏，选择搜索或转到并找到您的项目。
2. 选择代码 > 片段。
3. 选择您要报告为垃圾邮件的片段。
4. 选择提交为垃圾邮件。

GitLab 将垃圾邮件转发给 Akismet。

故障排除

片段限制

• 对您可以创建的片段数量没有限制。
• 不支持二进制文件。
• 不支持创建或删除分支。仅使用默认分支。
• Git 标签在片段存储库中不受支持。
• 片段的存储库限制为 10 个文件。尝试推送超过 10 个文件会导致错误。
• 修订版在 GitLab UI 上对用户不可见，但存在一个问题用于更新。
• 片段的最大大小默认为 50 MB（截至 2024-04-17）。
• 不支持 Git LFS。

减少片段存储库大小

由于版本化的片段被视为命名空间存储大小的一部分，建议保持片段存储库尽可能紧凑。

有关压缩存储库的工具的更多信息，请参阅减少存储库大小的文档。

无法在片段文本框中输入文本

如果文件名字段后的文本区域被禁用并阻止您创建新片段，请使用此解决方法：

1. 为您的片段输入标题。
2. 滚动到文件字段的底部，然后选择 添加另一个文件。GitLab 会显示第二组字段以添加第二个文件。
3. 在第二个文件的文件名字段中，输入文件名以避免已知的复制粘贴错误。
4. 在第二个文件的文本区域中输入任何字符串。
5. 滚回到第一个文件名，然后选择删除文件。
6. 创建其余的文件，完成后选择创建片段。

相关主题

• 配置片段设置（在 GitLab 自托管上）