Commit 50056424 authored by Amparo Luna's avatar Amparo Luna Committed by Marcia Ramos

Add documentation about Versioned Snippets

parent 307ebe6d
......@@ -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).
......@@ -11,6 +11,67 @@ There are two types of snippets:
- Personal snippets.
- Project snippets.
## 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 50MB, by default.
## Personal snippets
Personal snippets are not related to any project and can be created completely
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment