summaryrefslogtreecommitdiff
path: root/doc/user/snippets.md
blob: 15391f034a8ad5ea3fd6321cf0c3d091ab3be976 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
---
stage: Create
group: Editor
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers"
type: reference
---

# Snippets

With GitLab Snippets you can store and share bits of code and text with other users.

![GitLab Snippet](img/gitlab_snippet_v13_0.png)

Snippets can be maintained using [snippets API](../api/snippets.md).

There are two types of snippets:

- Personal snippets.
- Project snippets.

## Personal snippets

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.

## Project snippets

Project snippets are always related to a specific project.
See [Project features](project/index.md#project-features) for more information.

## 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).

## Versioned Snippets

> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/239) in GitLab 13.0.

Starting in 13.0, snippets (both personal and project snippets)
have version control enabled by default.

This means that all snippets get their own underlying repository initialized with
a `master` branch at the moment the snippet is created. Whenever a change to the snippet is saved, a
new commit to the master branch is recorded. Commit messages are automatically
generated. The snippet's repository has only one branch (master) by default, deleting
it or creating other branches is not supported.

Existing snippets will be automatically migrated in 13.0. Their current
content will be saved as the initial commit to the snippets' repository.

### File names

Snippets support syntax highlighting based on the filename and
extension provided for them. While it is possible to submit a snippet
without specifying a filename and extension, it needs a valid name so the
content can be created as a file in the snippet's repository.

In case the user does not attribute a filename and extension to a snippet,
GitLab automatically adds a filename in the format `snippetfile<x>.txt`
where `<x>` represents a number added to the file, starting with 1. This
number increases incrementally when more snippets without an attributed
filename are added.

When upgrading from an earlier version of GitLab to 13.0, existing snippets
without a supported filename will be renamed to a compatible format. For
example, if the snippet's filename is `http://a-weird-filename.me` it will
be changed to `http-a-weird-filename-me` to be included in the snippet's
repository. As snippets are stored by ID, changing their filenames will not break
direct or embedded links to the snippet.

### Cloning snippets

Snippets can be cloned as a regular Git repository using SSH or HTTPS. Click the **Clone**
button above the snippet content to copy the URL of your choice.

![Clone Snippet](img/snippet_clone_button_v13_0.png)

This allows you to have a local copy of the snippet's repository and make
changes as needed. You can commit those changes and push them to the remote
master branch.

### Reduce snippets repository size

Since versioned Snippets are considered as part of the [namespace storage size](../user/admin_area/settings/account_and_limit_settings.md),
it's recommended to keep snippets' repositories as compact as possible.

For more information about tools to compact repositories,
see the documentation on [reducing repository size](../user/project/repository/reducing_the_repo_size_using_git.md).

### Limitations

- Binary files are not supported.
- Creating or deleting branches is not supported. Only a default *master*.
branch is used.
- Git tags are not supported in snippet repositories.
- Snippets' repositories are limited to one file. Attempting to push more
than one file will result in an error.
- Revisions are not *yet* visible to the user on the GitLab UI, but
it's planned to be added in future iterations. See the [revisions tab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/39271)
for updates.
- The [maximum size for a snippet](../administration/snippets/index.md#snippets-content-size-limit)
is 50 MB, by default.

## Discover snippets

There are two main ways of how you can discover snippets in GitLab.

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.
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.

## Snippet comments

> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/12910) in GitLab 9.2.

With GitLab Snippets you engage in a conversation about that piece of code,
facilitating the collaboration among users.

## Downloading snippets

You can download the raw content of a snippet.

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`).

## Embedded snippets

> Introduced in GitLab 10.8.

Public snippets can not only be shared, but also embedded on any website. With
this, you can 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**

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
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:

<script src="https://gitlab.com/gitlab-org/gitlab-foss/snippets/1717978.js"></script>

Embedded snippets are displayed with a header that shows the file name if it's 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.