summaryrefslogtreecommitdiff
path: root/doc/user/snippets.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user/snippets.md')
-rw-r--r--doc/user/snippets.md60
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.