Skip to content

G
gitlab-ce
Commit 015f61fc authored by Amy Qualls's avatar Amy Qualls Committed by Craig Norris
Browse files
Options

Complete rewrite of snippets page 

The page needed major reworking to have some sort of logical flow,
and follow CTRT. It also needed several old screenshots removed.
parent 0f600368
Hide whitespace changes
Inline Side-by-side
Showing with 133 additions and 147 deletions
doc/administration/geo/replication/datatypes.md
View file @ 015f61fc
......@@ -178,8 +178,8 @@ successfully, you must replicate their data using some other means.
| [Group wiki repository](../../../user/group/index.md#group-wikis) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/208147) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/208147) | No | |
| [Uploads](../../uploads.md) | **Yes** (10.2) | [No](https://gitlab.com/groups/gitlab-org/-/epics/1817) | No | Verified only on transfer or manually using [Integrity Check Rake Task](../../raketasks/check.md) on both nodes and comparing the output between them. |
| [LFS objects](../../lfs/index.md) | **Yes** (10.2) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8922) | Via Object Storage provider if supported. Native Geo support (Beta). | Verified only on transfer or manually using [Integrity Check Rake Task](../../raketasks/check.md) on both nodes and comparing the output between them. GitLab versions 11.11.x and 12.0.x are affected by [a bug that prevents any new LFS objects from replicating](https://gitlab.com/gitlab-org/gitlab/-/issues/32696). |
| [Personal snippets](../../../user/snippets.md#personal-snippets) | **Yes** (10.2) | **Yes** (10.2) | No | |
| [Project snippets](../../../user/snippets.md#project-snippets) | **Yes** (10.2) | **Yes** (10.2) | No | |
| [Personal snippets](../../../user/snippets.md) | **Yes** (10.2) | **Yes** (10.2) | No | |
| [Project snippets](../../../user/snippets.md) | **Yes** (10.2) | **Yes** (10.2) | No | |
| [CI job artifacts (other than Job Logs)](../../../ci/pipelines/job_artifacts.md) | **Yes** (10.4) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8923) | Via Object Storage provider if supported. Native Geo support (Beta) . | Verified only manually using [Integrity Check Rake Task](../../raketasks/check.md) on both nodes and comparing the output between them |
| [Job logs](../../job_logs.md) | **Yes** (10.4) | [No](https://gitlab.com/gitlab-org/gitlab/-/issues/8923) | Via Object Storage provider if supported. Native Geo support (Beta). | Verified only on transfer or manually using [Integrity Check Rake Task](../../raketasks/check.md) on both nodes and comparing the output between them |
| [Object pools for forked project deduplication](../../../development/git_object_deduplication.md) | **Yes** | No | No | |
......
doc/user/profile/index.md
View file @ 015f61fc
......@@ -40,7 +40,7 @@ On your profile page, you can see the following information:
- Contributed projects: [projects](../project/index.md) you contributed to
- Personal projects: your personal projects (respecting the project's visibility level)
- Starred projects: projects you starred
- Snippets: your personal code [snippets](../snippets.md#personal-snippets)
- Snippets: your personal code [snippets](../snippets.md)
- Followers: people [following](../index.md#user-activity) you
- Following: people you are [following](../index.md#user-activity)
......
doc/user/snippets.md
View file @ 015f61fc
......@@ -7,83 +7,98 @@ type: reference
# Snippets **(FREE)**
With GitLab Snippets you can store and share bits of code and text with other users.
With GitLab snippets, you can store and share bits of code and text with other users.
You can [comment on](#comment-on-snippets), [clone](#clone-snippets), and
[use version control](#versioned-snippets) in snippets. They can
[contain multiple files](#add-or-remove-multiple-files). They also support
[syntax highlighting](#filenames), [embedding](#embed-snippets), [downloading](#download-snippets),
and you can maintain your snippets with the [snippets API](../api/snippets.md).
GitLab provides two types of snippets:
- **Personal snippets**: Created independent of any project.
You can set a [visibility level](../public_access/public_access.md)
for your snippet: public, internal, or private.
- **Project snippets**: Always related to a specific project.
Project snippets can be visible publicly or to only group members.
## Create snippets
You can create snippets in multiple ways, depending on whether you want to create a personal or project snippet:
1. Select the kind of snippet you want to create:
- **To create a personal snippet**:
- *If you're on a project's page,* select the plus icon (**{plus-square-o}**)
in the top navigation bar, then select **New snippet** from the **GitLab** (for GitLab.com)
or **Your Instance** (self-managed) section of the same dropdown menu.
- *For all other pages,* select the plus icon (**{plus-square-o}**)
in the top navigation bar, then select **New snippet** from the dropdown menu.
- **To create a project snippet**: Go to your project's page. Select the plus icon
(**{plus-square-o}**), then select **New snippet** from the **This project** section
of the dropdown menu.
1. Add a **Title** and **Description**.
1. Name your **File** with an appropriate extension, such as `example.rb` or `index.html`.
Filenames with appropriate extensions display [syntax highlighting](#filenames).
Failure to add a filename can cause a known
[copy-pasting bug](https://gitlab.com/gitlab-org/gitlab/-/issues/22870). If you don't provide a filename, GitLab [creates a name for you](#filenames).
1. (Optional) Add [multiple files](#add-or-remove-multiple-files) to your snippet.
1. Select a visibility level, and select **Create snippet**.
After you create a snippet, you can still [add more files to it](#add-or-remove-multiple-files).
In GitLab versions 13.0 and later, snippets are [versioned by default](#versioned-snippets).
![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):
## Discover snippets
![New personal snippet from project pages](img/new_personal_snippet_from_project_v12_10.png)
To discover all snippets visible to you in GitLab, you can:
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**).
- **View all snippets visible to you**: In the top navigation bar of your GitLab
instance, go to **More > Snippets** to view your snippets dashboard.
- **Visit [GitLab snippets](http://snippets.gitlab.com/)** for your snippets on GitLab.com.
- **Explore all public snippets**: In the top navigation bar of your GitLab
instance, go to **More > Snippets** and select **Explore snippets** to view
[all public snippets](https://gitlab.com/explore/snippets).
- **View a project's snippets**: In your project,
go to **Snippets**.
![New personal snippet from project pages](img/new_project_snippet_from_project_v12_10.png)
## Change default visibility of snippets
From there, add the **Title**, **Description**, and a **File** name with the
appropriate extension (for example, `example.rb`, `index.html`).
Project snippets are enabled and available by default. To change their
default visibility:
WARNING:
Make sure to add the filename to get code highlighting and to avoid this
[copy-pasting bug](https://gitlab.com/gitlab-org/gitlab/-/issues/22870).
1. In your project,
go to **Settings**.
1. Expand the **Visibility, project features, permissions** section, and scroll to **Snippets**.
1. Toggle the default visibility, and select whether snippets can be viewed by
everyone, or only project members.
1. Select **Save changes**.
## Versioned 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)
In GitLab versions 13.0 and later, 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.
a default branch at the moment the snippet is created. Whenever a change to the snippet is saved, a
new commit to the default branch is recorded. Commit messages are automatically
generated. The snippet's repository has only one branch. You can't delete this branch,
or create other branches.
Existing snippets are automatically migrated in 13.0. Their current
content is saved as the initial commit to the snippets' repository.
Existing snippets were automatically migrated in 13.0. Their current
content was saved as the initial commit to the snippets' repository.
### Filenames
## Filenames
Snippets support syntax highlighting based on the filename and
extension provided for them. While you can submit a snippet
without specifying a filename and extension, it needs a valid name so the
without a filename and extension, it needs a valid name so the
content can be created as a file in the snippet's repository.
If you don't attribute a filename and extension to a snippet,
If you don't give a snippet a filename and extension,
GitLab adds a filename in the format `snippetfile<x>.txt`
where `<x>` represents a number added to the file, starting with 1. This
number increments when more snippets without an attributed
filename are added.
number increments if you add more unnamed snippets.
When upgrading from an earlier version of GitLab to 13.0, existing snippets
without a supported filename are renamed to a compatible format. For
......@@ -92,139 +107,110 @@ changed to `http-a-weird-filename-me` to be included in the snippet's
repository. As snippets are stored by ID, changing their filenames breaks
direct or embedded links to the snippet.
### Multiple files by Snippet
## Add or remove multiple files
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2829) in GitLab 13.5.
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 single snippet can support up to 10 files, which helps keep related files together, such as:
- A snippet that includes a script and its output.
- A snippet that includes HTML, CSS, and JS code.
- A snippet that includes HTML, CSS, and JavaScript 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
- A `gulpfile.js` file and 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.
![Multi-file Snippet](img/gitlab_snippet_v13_5.png)
You can manage these by using Git (because they're [versioned](#versioned-snippets)
by a Git repository), through the [Snippets API](../api/snippets.md), and in the GitLab UI.
To add a new file to your snippet through the GitLab UI:
1. Go to your snippet in the GitLab UI.
1. Click **Edit** in the top right.
1. Select **Edit** in the top right corner.
1. Select **Add another file**.
1. Add your content to the file in the form fields provided.
1. Click **Save changes**.
1. Select **Save changes**.
To delete a file from your snippet through the GitLab UI:
1. Go to your snippet in the GitLab UI.
1. Click **Edit** in the top right.
1. Select **Edit** in the top right corner.
1. Select **Delete file** alongside the filename of each file
you wish to delete.
1. Click **Save changes**.
### 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.
1. Select **Save changes**.
![Clone Snippet](img/snippet_clone_button_v13_0.png)
## Clone snippets
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.
Instead of copying a snippet to a local file, you may want to clone a snippet to
preserve its relationship with the repository, so you can receive or make updates
as needed. Select the **Clone** button on a snippet to display the URLs to clone with SSH or HTTPS:
### Reduce snippets repository size
![Clone snippet](img/snippet_clone_button_v13_0.png)
Because 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.
You can commit changes to a cloned snippet, and push the changes to GitLab.
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).
## Embed snippets
### Limitations
Public snippets can be shared and embedded on any website. You can reuse a GitLab snippet in multiple places, and any change to the source
is reflected in the embedded snippets. When embedded, users can download it, or view the snippet in raw format.
- 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 10 files. Attempting to push more
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.
- Git LFS is not supported.
To embed a snippet:
## Discover snippets
1. Confirm your snippet is publicly visible:
- *If it's a project snippet*, the project must be public.
- The snippet is publicly visible.
- In **Project > Settings > Permissions**, the snippets
permissions are set to **Everyone with access**.
1. In your snippet's **Embed** section, select **Copy** to copy a one-line script you can add to any website or blog post. For example:
There are two main ways of how you can discover snippets in GitLab.
```html
<script src="https://gitlab.com/namespace/project/snippets/SNIPPET_ID.js"></script>
```
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
visit [GitLab Snippets](http://snippets.gitlab.com/) or navigate to an [overview]((https://gitlab.com/dashboard/snippets)) that shows snippets
you created and allows you to explore all snippets.
1. Add your script to your file.
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. 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.
Embedded snippets display a header that shows:
## Snippet comments
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/12910) in GitLab 9.2.
- The filename, if defined.
- The snippet size.
- A link to GitLab.
- The actual snippet content.
With GitLab Snippets you engage in a conversation about that piece of code,
encouraging user collaboration.
For example:
## Downloading snippets
<script src="https://gitlab.com/gitlab-org/gitlab-foss/snippets/1717978.js"></script>
You can download the raw content of a snippet.
## Download snippets
By default snippets are downloaded with Linux-style line endings (`LF`). If
You can download the raw content of a snippet. By default, they download with Linux-style line endings (`LF`). If
you want to preserve the original line endings you need to add a parameter `line_ending=raw`
(For example: `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.
## Comment on snippets
To embed a snippet, first make sure that:
With snippets, you engage in a conversation about that piece of code,
which can encourage user collaboration.
- 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**
## Troubleshooting
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:
### Snippet limitations
```html
<script src="https://gitlab.com/namespace/project/snippets/SNIPPET_ID.js"></script>
```
Here's what an embedded snippet looks like:
<script src="https://gitlab.com/gitlab-org/gitlab-foss/snippets/1717978.js"></script>
- Binary files are not supported.
- Creating or deleting branches is not supported. Only the default 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 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.
- Git LFS is not supported.
Embedded snippets are displayed with a header that shows:
### Reduce snippets repository size
- The filename, if defined.
- The snippet size.
- A link to GitLab.
- The actual snippet content.
Because 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.
Actions in the header enable users to see the snippet in raw format, and download it.
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).
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7