diff options
Diffstat (limited to 'doc/user/snippets.md')
| -rw-r--r-- | doc/user/snippets.md | 60 |
1 files changed, 32 insertions, 28 deletions
diff --git a/doc/user/snippets.md b/doc/user/snippets.md index af499221da6..e919e73f404 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -65,8 +65,8 @@ 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 +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 are automatically migrated in 13.0. Their current @@ -75,14 +75,14 @@ content is saved as the initial commit to the snippets' repository. ### Filenames Snippets support syntax highlighting based on the filename and -extension provided for them. While it is possible to submit a snippet +extension provided for them. While you can 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` +If you don't attribute a filename and extension to a snippet, +GitLab 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 +number increments when more snippets without an attributed filename are added. When upgrading from an earlier version of GitLab to 13.0, existing snippets @@ -96,14 +96,15 @@ direct or embedded links to the snippet. > [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2829) in GitLab 13.5. -GitLab Snippets support multiple files in one single snippet. It can be very handy +GitLab Snippets support multiple files in one single snippet. This is helpful when your code snippet is composed of multiple parts or when they relate to a certain context. For example: - A snippet that includes a script and its output. - A snippet that includes HTML, CSS, and JS code. - A snippet with a `docker-compose.yml` file and its associated `.env` file. -- A `gulpfile.js` file coupled with a `package.json` file, which together can be used to bootstrap a project and manage its dependencies. +- A `gulpfile.js` file coupled with a `package.json` file, which together can be + used to bootstrap a project and manage its dependencies. Snippets support between 1 and 10 files. They can be managed via Git (because they're [versioned](#versioned-snippets) by a Git repository), through the [Snippets API](../api/snippets.md), or in the GitLab UI. @@ -135,7 +136,7 @@ button above the snippet content to copy the URL of your choice. 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. +`master` branch. ### Reduce snippets repository size @@ -148,15 +149,15 @@ see the documentation on [reducing repository size](../user/project/repository/r ### Limitations - Binary files are not supported. -- Creating or deleting branches is not supported. Only a default *master* branch is used. +- 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 10 files. Attempting to push more -than 10 files results 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. + than 10 files results in an error. +- Revisions are not visible to the user on the GitLab UI, but this feature is planned + 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. + is 50 MB, by default. - Git LFS is not supported. ## Discover snippets @@ -168,10 +169,10 @@ dashboard of your GitLab instance via the top navigation. For GitLab.com you can navigate to an [overview]((https://gitlab.com/dashboard/snippets)) 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 discover snippets that belong to a specific project, 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 +Project snippets are enabled and available by default. You can +disable them 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. @@ -181,7 +182,7 @@ different visibility level from the dropdown menu. > [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. +encouraging user collaboration. ## Downloading snippets @@ -207,20 +208,23 @@ To embed a snippet, first make sure that: - In **Project > Settings > Permissions**, the snippets permissions are set to **Everyone with access** -After the above conditions are met, the "Embed" section appears 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: +After the above conditions are met, the **Embed** section appears in your +snippet. Click the **Copy** button to copy a one-line +script that you can add to any website or blog post. For example: ```html <script src="https://gitlab.com/namespace/project/snippets/SNIPPET_ID.js"></script> ``` -Here's how an embedded snippet looks like: +Here's what 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 filename 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. +Embedded snippets are displayed with a header that shows: + +- The filename, if defined. +- The snippet size. +- A link to GitLab. +- The actual snippet content. + +Actions in the header enable users to see the snippet in raw format, and download it. |