diff options
Diffstat (limited to 'doc/user/snippets.md')
-rw-r--r-- | doc/user/snippets.md | 67 |
1 files changed, 64 insertions, 3 deletions
diff --git a/doc/user/snippets.md b/doc/user/snippets.md index 0372bb42038..96c8dba11e5 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -2,7 +2,7 @@ With GitLab Snippets you can store and share bits of code and text with other users. -![GitLab Snippet](img/gitlab_snippet.png) +![GitLab Snippet](img/gitlab_snippet_v13_0.png) Snippets can be maintained using [snippets API](../api/snippets.md). @@ -49,6 +49,67 @@ 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. + +### 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. @@ -87,7 +148,7 @@ snippet was created using the GitLab web interface the original line ending is W > 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 +allows us 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: @@ -111,6 +172,6 @@ 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 defined, +Embedded snippets are displayed with a header that shows the file name is 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. |