debian-mirror-gitlab/doc/user/snippets.md

117 lines
4.6 KiB
Markdown
Raw Normal View History

2017-08-17 22:00:37 +05:30
# Snippets
2018-11-08 19:23:39 +05:30
With GitLab Snippets you can store and share bits of code and text with other users.
2017-08-17 22:00:37 +05:30
![GitLab Snippet](img/gitlab_snippet.png)
2019-07-07 11:18:12 +05:30
Snippets can be maintained using [snippets API](../api/snippets.md).
There are two types of snippets:
- Personal snippets.
- Project snippets.
2017-08-17 22:00:37 +05:30
2018-11-08 19:23:39 +05:30
## Personal snippets
2017-08-17 22:00:37 +05:30
2018-11-08 19:23:39 +05:30
Personal snippets are not related to any project and can be created completely
independently. There are 3 visibility levels that can be set, public, internal
and private. See [Public access](../public_access/public_access.md) for more information.
2017-08-17 22:00:37 +05:30
## Project snippets
2018-11-08 19:23:39 +05:30
Project snippets are always related to a specific project.
2019-07-07 11:18:12 +05:30
See [Project features](project/index.md#project-features) for more information.
2017-08-17 22:00:37 +05:30
2020-04-22 19:07:51 +05:30
## Create a snippet
To create a personal snippet, click the plus icon (**{plus-square-o}**)
on the top navigation and select **New snippet** from the dropdown menu:
![New personal snippet from non-project pages](img/new_personal_snippet_v12_10.png)
If you're on a project's page but you want to create a new personal snippet,
click the plus icon (**{plus-square-o}**) and select **New snippet** from the
lower part of the dropdown (**GitLab** on GitLab.com; **Your Instance** on
self-managed instances):
![New personal snippet from project pages](img/new_personal_snippet_from_project_v12_10.png)
To create a project snippet, navigate to your project's page and click the
plus icon (**{plus-square-o}**), then select **New snippet** from the upper
part of the dropdown (**This project**).
![New personal snippet from project pages](img/new_project_snippet_from_project_v12_10.png)
From there, add the **Title**, **Description**, and a **File** name with the
appropriate extension (for example, `example.rb`, `index.html`).
CAUTION: **Warning:**
Make sure to add the file name to get code highlighting and to avoid this
[copy-pasting bug](https://gitlab.com/gitlab-org/gitlab/-/issues/22870).
2018-11-08 19:23:39 +05:30
## Discover snippets
There are two main ways of how you can discover snippets in GitLab.
2017-08-17 22:00:37 +05:30
2018-11-08 19:23:39 +05:30
For exploring all snippets that are visible to you, you can go to the Snippets
dashboard of your GitLab instance via the top navigation. For GitLab.com you can
find it [here](https://gitlab.com/dashboard/snippets). This navigates you to an
overview that shows snippets you created and allows you to explore all snippets.
If you want to discover snippets that belong to a specific project, you can navigate
to the Snippets page via the left side navigation on the project page.
2019-12-04 20:38:33 +05:30
Project snippets are enabled and available by default, but they can
be disabled by navigating to your project's **Settings**, expanding
**Visibility, project features, permissions** and scrolling down to
**Snippets**. From there, you can toggle to disable them or select a
different visibility level from the dropdown menu.
2018-11-08 19:23:39 +05:30
## Snippet comments
2019-12-04 20:38:33 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/12910) in GitLab 9.2.
2018-11-08 19:23:39 +05:30
With GitLab Snippets you engage in a conversation about that piece of code,
facilitating the collaboration among users.
2017-08-17 22:00:37 +05:30
## Downloading snippets
You can download the raw content of a snippet.
2018-11-08 19:23:39 +05:30
By default snippets will be downloaded with Linux-style line endings (`LF`). If
you want to preserve the original line endings you need to add a parameter `line_ending=raw`
(e.g., `https://gitlab.com/snippets/SNIPPET_ID/raw?line_ending=raw`). In case a
snippet was created using the GitLab web interface the original line ending is Windows-like (`CRLF`).
2018-10-15 14:42:47 +05:30
2018-11-08 19:23:39 +05:30
## Embedded snippets
2018-10-15 14:42:47 +05:30
> Introduced in GitLab 10.8.
Public snippets can not only be shared, but also embedded on any website. This
allows to reuse a GitLab snippet in multiple places and any change to the source
is automatically reflected in the embedded snippet.
To embed a snippet, first make sure that:
- The project is public (if it's a project snippet)
- The snippet is public
- In **Project > Settings > Permissions**, the snippets permissions are
set to **Everyone with access**
2019-12-21 20:55:43 +05:30
Once the above conditions are met, the "Embed" section will appear in your
snippet where you can simply click on the "Copy" button. This copies a one-line
2018-10-15 14:42:47 +05:30
script that you can add to any website or blog post.
Here's how an example code looks like:
```html
<script src="https://gitlab.com/namespace/project/snippets/SNIPPET_ID.js"></script>
```
Here's how an embedded snippet looks like:
2019-12-04 20:38:33 +05:30
<script src="https://gitlab.com/gitlab-org/gitlab-foss/snippets/1717978.js"></script>
2018-10-15 14:42:47 +05:30
Embedded snippets are displayed with a header that shows the file name if defined,
the snippet size, a link to GitLab, and the actual snippet content. Actions in
the header allow users to see the snippet in raw format and download it.