diff options
Diffstat (limited to 'doc/user/project/repository')
29 files changed, 729 insertions, 182 deletions
diff --git a/doc/user/project/repository/branches/default.md b/doc/user/project/repository/branches/default.md index b33dc4450a9..e58cc0bf6a4 100644 --- a/doc/user/project/repository/branches/default.md +++ b/doc/user/project/repository/branches/default.md @@ -134,7 +134,7 @@ groups and subgroups can override this instance-wide setting for their projects. Instance-level protections for default branches can be overridden on a per-group basis by the group's owner. In -[GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can +[GitLab Premium or Ultimate](https://about.gitlab.com/pricing/), GitLab administrators can disable this privilege for group owners, enforcing the instance-level protection rule: 1. On the top bar, select **Main menu > Admin**. @@ -153,7 +153,7 @@ GitLab administrators can still update the default branch protection of a group. Instance-level protections for [default branch](#default-branch) can be overridden on a per-group basis by the group's owner. In -[GitLab Premium or higher](https://about.gitlab.com/pricing/), GitLab administrators can +[GitLab Premium or Ultimate](https://about.gitlab.com/pricing/), GitLab administrators can [enforce protection of initial default branches](#prevent-overrides-of-default-branch-protection) which locks this setting for group owners. diff --git a/doc/user/project/repository/branches/img/branch_filter_search_box_v13_12.png b/doc/user/project/repository/branches/img/branch_filter_search_box_v13_12.png Binary files differdeleted file mode 100644 index a1cf9f10122..00000000000 --- a/doc/user/project/repository/branches/img/branch_filter_search_box_v13_12.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/compare_branches_v13_12.png b/doc/user/project/repository/branches/img/compare_branches_v13_12.png Binary files differdeleted file mode 100644 index 29627406729..00000000000 --- a/doc/user/project/repository/branches/img/compare_branches_v13_12.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/repository_filter_search_box_v13_12.png b/doc/user/project/repository/branches/img/repository_filter_search_box_v13_12.png Binary files differdeleted file mode 100644 index 230abf0d875..00000000000 --- a/doc/user/project/repository/branches/img/repository_filter_search_box_v13_12.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/swap_revisions_after_v13_12.png b/doc/user/project/repository/branches/img/swap_revisions_after_v13_12.png Binary files differdeleted file mode 100644 index 7eb10d10938..00000000000 --- a/doc/user/project/repository/branches/img/swap_revisions_after_v13_12.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/swap_revisions_before_v13_12.png b/doc/user/project/repository/branches/img/swap_revisions_before_v13_12.png Binary files differdeleted file mode 100644 index f92c4279871..00000000000 --- a/doc/user/project/repository/branches/img/swap_revisions_before_v13_12.png +++ /dev/null diff --git a/doc/user/project/repository/branches/img/view_branch_protections_v15_10.png b/doc/user/project/repository/branches/img/view_branch_protections_v15_10.png Binary files differnew file mode 100644 index 00000000000..8472015c21b --- /dev/null +++ b/doc/user/project/repository/branches/img/view_branch_protections_v15_10.png diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 60504b94502..7c09ce5c580 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -6,142 +6,260 @@ info: "To determine the technical writer assigned to the Stage/Group associated # Branches **(FREE)** -A branch is a version of a project's working tree. You create a branch for each -set of related changes you make. This keeps each set of changes separate from -each other, allowing changes to be made in parallel, without affecting each -other. +Branches are versions of a project's working tree. When you create a new +[project](../../index.md), GitLab creates a [default branch](default.md) (which +cannot be deleted) for your repository. Default branch settings can be configured +at the project, subgroup, group, or instance level. -After pushing your changes to a new branch, you can: +As your project grows, your team [creates](../web_editor.md#create-a-branch) more +branches, preferably by following [branch naming patterns](#prefix-branch-names-with-issue-numbers). +Each branch represents a set of changes, which allows development work to be done +in parallel. Development work in one branch does not affect another branch. -- Create a [merge request](../../merge_requests/index.md). You can streamline this process - by following [branch naming patterns](#naming). -- Perform inline code review. -- [Discuss](../../../discussions/index.md) your implementation with your team. -- Preview changes submitted to a new branch with [Review Apps](../../../../ci/review_apps/index.md). +Branches are the foundation of development in a project: -You can also request [approval](../../merge_requests/approvals/index.md) -from your managers. +1. To get started, create a branch and add commits to it. +1. When the work is ready for review, create a [merge request](../../merge_requests/index.md) to propose + merging the changes in your branch. To streamline this process, you should follow + [branch naming patterns](#prefix-branch-names-with-issue-numbers). +1. Preview changes in a branch with a [review app](../../../../ci/review_apps/index.md). +1. After the contents of your branch are merged, [delete the merged branch](#delete-merged-branches). -For more information on managing branches using the GitLab UI, see: +## Create branch -- [Default branches](default.md): When you create a new [project](../../index.md), GitLab creates a - default branch for the repository. You can change this setting at the project, - subgroup, group, or instance level. -- [Create a branch](../web_editor.md#create-a-branch) -- [Protected branches](../../protected_branches.md#protected-branches) -- [Delete merged branches](#delete-merged-branches) -- [Branch filter search box](#branch-filter-search-box) +To create a new branch from the GitLab UI: -You can also manage branches using the -[command line](../../../../gitlab-basics/start-using-git.md#create-a-branch). +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Branches**. +1. On the top right, select **New branch**. +1. Enter a **Branch name**. +1. In **Create from**, select the base of your branch: an existing branch, an existing + tag, or a commit SHA. +1. Select **Create branch**. -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>Watch the video [GitLab Flow](https://www.youtube.com/watch?v=InKNIvky2KE). +### In a blank project -See also: +A [blank project](../../index.md#create-a-blank-project) does not contain a branch, but +you can add one. -- [Branches API](../../../../api/branches.md), for information on operating on repository branches using the GitLab API. -- [GitLab Flow](../../../../topics/gitlab_flow.md) documentation. -- [Getting started with Git](../../../../topics/git/index.md) and GitLab. +Prerequisites: -## Naming +- You must have at least the Developer role in the project. +- Unless you have the Maintainer or Owner roles, the + [default branch protection](../../../group/manage.md#change-the-default-branch-protection-of-a-group) + must be set to `Partially protected` or `Not protected` for you to push a commit + to the default branch. -Prefix a branch name with an issue number to streamline merge request creation. -When you create a merge request for a branch with a name beginning with an issue -number, GitLab: +To add a [default branch](default.md) to an empty project: -- Marks the issue as related. If your project is configured with a - [default closing pattern](../../issues/managing_issues.md#default-closing-pattern), - merging this merge request [also closes](../../issues/managing_issues.md#closing-issues-automatically) - the related issue. -- Copies label and milestone metadata from the issue. +1. On the top bar, select **Main menu > Projects** and find your project. +1. Scroll to **The repository for this project is empty** and select the type of + file you want to add. +1. In the Web IDE, make any desired changes to this file, then select **Create commit**. +1. Enter a commit message, and select **Commit**. -## Compare +GitLab creates a default branch and adds your file to it. -To compare branches in a repository: +### From an issue -1. Navigate to your project's repository. -1. Select **Repository > Compare** in the sidebar. -1. Select the target repository to compare with the [repository filter search box](#repository-filter-search-box). -1. Select branches to compare using the [branch filter search box](#branch-filter-search-box). -1. Select **Compare** to view the changes inline: +When viewing an issue, you can create an associated branch directly from that page. -  +Prerequisites: -## Delete merged branches +- You must have at least the Developer role in the project. - +To create a branch from an issue: -This feature allows merged branches to be deleted in bulk. Only branches that -have been merged into the project's default branch and -[are not protected](../../protected_branches.md) are deleted as part of -this operation. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Issues** (**{issues}**) and find your issue. +1. Below the issue description, find the **Create merge request** dropdown list, and select + **{chevron-down}** to display the dropdown list. +1. Select **Create branch**. A default **Branch name** is provided, based on the + [default pattern](#configure-default-pattern-for-branch-names-from-issues) for + this project. If desired, enter a different **Branch name**. +1. Select **Create branch** to create the branch based on your project's + [default branch](default.md). -It's particularly useful to clean up old branches that were not deleted -automatically when a merge request was merged. +## Manage and protect branches + +GitLab provides you multiple methods to protect individual branches. These methods +ensure your branches receive oversight and quality checks from their creation to their deletion: -## Repository filter search box +- The [default branch](default.md) in your project receives extra protection. +- Configure [protected branches](../../protected_branches.md#protected-branches) + to restrict who can commit to a branch, merge other branches into it, or merge + the branch itself into another branch. +- Configure [approval rules](../../merge_requests/approvals/rules.md) to set review + requirements, including [security-related approvals](../../merge_requests/approvals/rules.md#security-approvals), before a branch can merge. +- Integrate with third-party [status checks](../../merge_requests/status_checks.md) + to ensure your branch contents meet your standards of quality. -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52967) in GitLab 13.10. +You can manage your branches: -This feature allows you to search and select a repository quickly when [comparing branches](#compare). +- With the GitLab user interface. +- With the [command line](../../../../gitlab-basics/start-using-git.md#create-a-branch). +- With the [Branches API](../../../../api/branches.md). - +### View all branches -Search results appear in the following order: +To view and manage your branches in the GitLab user interface: -- Repositories with names exactly matching the search terms. -- Other repositories with names that include search terms, sorted alphabetically. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Branches**. -## Branch filter search box +On this page, you can: - +- See all branches, active branches, or stale branches. +- Create new branches. +- [Compare branches](#compare-branches). +- Delete merged branches. -This feature allows you to search and select branches quickly. Search results appear in the following order: +### View branches with configured protections -- Branches with names that matched search terms exactly. -- Other branches with names that include search terms, sorted alphabetically. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) in GitLab 15.1 with a flag named `branch_rules`. Disabled by default. +> - [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/issues/363170) in GitLab 15.10. +> - [Enabled on self-managed](https://gitlab.com/gitlab-org/gitlab/-/issues/363170) in GitLab 15.11 -Sometimes when you have hundreds of branches you may want a more flexible matching pattern. In such cases you can use the following operators: +FLAG: +On self-managed GitLab, by default this feature is available. To hide the feature, ask an administrator to [disable the feature flag](../../../feature_flags.md) named `branch_rules`. +On GitLab.com, this feature is available. -- `^` matches beginning of branch name, for example `^feat` would match `feat/user-authentication` -- `$` matches end of branch name, for example `widget$` would match `feat/search-box-widget` -- `*` wildcard matcher, for example `branch*cache*` would match `fix/branch-search-cache-expiration` +Branches in your repository can be [protected](../../protected_branches.md) in multiple ways. You can: -These operators can be mixed, for example `^chore/*migration$` would match `chore/user-data-migration` +- Limit who can push to the branch. +- Limit who can merge the branch. +- Require approval of all changes. +- Require external tests to pass. -## Swap revisions +The **Branch rules overview** page shows all branches with any configured protections, +and their protection methods: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60491) in GitLab 13.12. + - +Prerequisites: -The Swap revisions feature allows you to swap the Source and Target revisions. When the Swap revisions button is selected, the selected revisions for Source and Target is swapped. +- You must have at least the Maintainer role in the project. - +To view the **Branch rules overview** list: -## View branches with configured protections **(FREE SELF)** +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Branch Rules** to view all branches with protections. + - To add protections to a new branch: + 1. Select **Add branch rule**. + 1. Select **Create protected branch**. + - To view more information about protections on an existing branch: + 1. Identify the branch you want more information about. + 1. Select **Details** to see information about its: + - [Branch protections](../../protected_branches.md). + - [Approval rules](../../merge_requests/approvals/rules.md). + - [Status checks](../../merge_requests/status_checks.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/88279) in GitLab 15.1 with a flag named `branch_rules`. Disabled by default. +## Name your branch -FLAG: -On self-managed GitLab, by default this feature is not available. To make it available, ask an administrator to [enable the feature flag](../../../feature_flags.md) named `branch_rules`. -On GitLab.com, this feature is not available. -This feature is not ready for production use. +Git enforces [branch name rules](https://git-scm.com/docs/git-check-ref-format) +to help ensure branch names remain compatible with other tools. GitLab +adds extra requirements for branch names, and provides benefits for well-structured branch names. -Branches in your repository can be [protected](../../protected_branches.md) by limiting -who can push to a branch, require approval for those pushed changes, or merge those changes. -To help you track the protections for all branches, the **Branch rules overview** -page shows your branches with their configured rules. +GitLab enforces these additional rules on all branches: -To view the **Branch rules overview** list: +- No spaces are allowed in branch names. +- Branch names with 40 hexadecimal characters are prohibited, because they are similar to Git commit hashes. + +Common software packages, like Docker, may enforce +[additional branch naming restrictions](../../../../administration/packages/container_registry.md#docker-connection-error). + +For best compatibility with other software packages, use only numbers, hyphens (`-`), +underscores (`_`), and lower-case letters from the ASCII standard table. You +can use forward slashes (`/`) and emoji in branch names, but compatibility with other +software packages cannot be guaranteed. + +Branch names with specific formatting offer extra benefits: + +- Streamline your merge request workflow by + [prefixing branch names with issue numbers](#prefix-branch-names-with-issue-numbers). +- Automate [branch protections](../../protected_branches.md) based on branch name. +- Test branch names with [push rules](../push_rules.md) before branches are pushed up to GitLab. +- Define which [CI/CD jobs](../../../../ci/jobs/index.md) to run on merge requests. + +### Configure default pattern for branch names from issues + +By default, GitLab uses the pattern `%{id}-%{title}` when creating a branch from +an issue, but you can change this pattern. + +Prerequisites: + +- You must have at least the Maintainer role for the project. + +To change the default pattern for branches created from issues: 1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > Repository**. -1. Expand **Branch Rules** to view all branches with protections. -1. Select **Details** next to your desired branch to show information about its: - - [Branch protections](../../protected_branches.md). - - [Approval rules](../../merge_requests/approvals/rules.md). - - [Status checks](../../merge_requests/status_checks.md). +1. On the left sidebar, select **Settings > Repository** and expand **Branch defaults**. +1. Scroll to **Branch name template** and enter a value. The field supports these variables: + - `%{id}`: The numeric ID of the issue. + - `%{title}`: The title of the issue, modified to use only characters acceptable in Git branch names. +1. Select **Save changes**. + +### Prefix branch names with issue numbers + +To streamline the creation of merge requests, start your branch name with an +issue number. GitLab uses the issue number to import data into the merge request: + +- The issue is marked as related to the merge request. The issue and merge request + display links to each other. +- The branch is connected to the issue. +- If your project is configured with a + [default closing pattern](../../issues/managing_issues.md#default-closing-pattern), + merging the merge request [also closes](../../issues/managing_issues.md#closing-issues-automatically) + the related issue. +- Issue milestone and labels are copied to the merge request. + +## Compare branches + +> - Repository filter search box [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52967) in GitLab 13.10. +> - Revision swapping [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/60491) in GitLab 13.12. + +The default compare mode uses the `git diff from...to` method, instead of the +`git diff from to` method, to compare branches. The `git diff from...to` method +provides a more human-readable diff, because it does not include unrelated changes +made to the target branch after the source branch was created. + +NOTE: +The `git diff from...to` method shows all changes from a cherry-picked commit as +new changes. It uses the merge base, not the actual commit content, to compare branches. + +To compare branches in a repository: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Compare revisions**. +1. Select the **Source** branch to search for your desired branch. Exact matches are + shown first. You can refine your search with operators: + - `^` matches the beginning of the branch name: `^feat` matches `feat/user-authentication`. + - `$` matches the end of the branch name: `widget$` matches `feat/search-box-widget`. + - `*` matches using a wildcard: `branch*cache*` matches `fix/branch-search-cache-expiration`. + - You can combine operators: `^chore/*migration$` matches `chore/user-data-migration`. +1. Select the **Target** repository and branch. Exact matches are shown first. +1. Select **Compare** to show the list of commits, and changed files. To reverse + the **Source** and **Target**, select **Swap revisions**. + +## Delete merged branches + + + +This feature allows merged branches to be deleted in bulk. Only branches that +have been merged into the project's default branch and +[are not protected](../../protected_branches.md) are deleted as part of +this operation. + +It's particularly useful to clean up old branches that were not deleted +automatically when a merge request was merged. + +## Related topics + +- [Protected branches](../../protected_branches.md) +- [Branches API](../../../../api/branches.md) +- [Protected Branches API](../../../../api/protected_branches.md) +- [Getting started with Git](../../../../topics/git/index.md) ## Troubleshooting diff --git a/doc/user/project/repository/code_suggestions.md b/doc/user/project/repository/code_suggestions.md new file mode 100644 index 00000000000..5de55db5ad4 --- /dev/null +++ b/doc/user/project/repository/code_suggestions.md @@ -0,0 +1,182 @@ +--- +stage: ModelOps +group: AI Assisted +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +type: index, reference +--- + +# Code Suggestions (Beta) **(FREE SAAS)** + +> - [Introduced](https://about.gitlab.com/releases/2023/02/22/gitlab-15-9-released/#code-suggestions-available-in-closed-beta) in GitLab 15.9 as [Beta](/ee/policy/alpha-beta-support.md#beta) for early access Ultimate customers. +> - [Enabled](https://gitlab.com/gitlab-org/gitlab/-/issues/408104) as opt-in with GitLab 15.11 as [Beta](/ee/policy/alpha-beta-support.md#beta). +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/408158) from GitLab Ultimate to GitLab Premium in 16.0. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/410801) from GitLab Premium to GitLab Free in 16.0. + +WARNING: +This feature is in [Beta](/ee/policy/alpha-beta-support.md#beta). +Code Suggestions use generative AI to suggest code while you're developing. +Due to high demand, this feature will have unscheduled downtime and code suggestions in VS Code may be delayed. +Code Suggestions may produce [low-quality or incomplete suggestions](#model-accuracy-and-quality). +Beta users should read about the [known limitations](#known-limitations). We look forward to hearing your feedback. + +Use Code Suggestions to write code more efficiently by viewing code suggestions +as you type. Depending on the cursor position, the extension either: + +- Provides entire code snippets, like generating functions. +- Completes the current line. + +To accept a suggestion, press <kbd>Tab</kbd>. + +Code Suggestions are available in Visual Studio Code when you have the GitLab Workflow extension installed. + +## Supported languages + +Code Suggestions may produce [low-quality or incomplete suggestions](#model-accuracy-and-quality). The best results from Code Suggestions are expected for these languages: + +- C/C++ +- C# +- Go +- Java +- JavaScript +- Python +- PHP +- Ruby +- Rust +- Scala +- TypeScript + +Suggestions may be mixed for other languages. Using natural language code comments to request completions may also not function as expected. + +GitLab is continuously improving the model and expects to support an additional seven languages soon, as well as natural language code comments. + +Usage of Code Suggestions is governed by the [GitLab Testing Agreement](https://about.gitlab.com/handbook/legal/testing-agreement/). Learn about [data usage when using Code Suggestions](#code-suggestions-data-usage). + +## Enable Code Suggestions in VS Code + +Prerequisites: + +- Your group owner must enable the [group level code suggestions setting](../../group/manage.md#group-code-suggestions). +- You must have [a personal access token](../../profile/personal_access_tokens.md#create-a-personal-access-token) with the `read_api` and `read_user` scopes. + +To enable Code Suggestions in VS Code: + +1. Download and configure the + [GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) + for Visual Studio Code. +1. In **GitLab: Add Account to VS Code on Mac**, add your GitLab work account to the VS Code extension: + - In macOS, press <kbd>Shift</kbd> + <kbd>Command</kbd> + <kbd>P</kbd>. + - In Windows, press <kbd>Shift</kbd> + <kbd>Control</kbd> + <kbd>P</kbd>. +1. Provide your GitLab instance URL. A default is provided. +1. Provide your personal access token. +1. After your GitLab account connects successfully, in the left sidebar, select **Extensions**. +1. Find the **GitLab workflow** extension, select **Settings** (**{settings}**), and select **Extension Settings**. +1. Enable **GitLab > AI Assisted Code Suggestions**. + +Start typing and receive suggestions for your GitLab projects. + +<div class="video-fallback"> + See an end-to-end demo: <a href="https://www.youtube.com/watch?v=WnxBYxN2-p4">Get started with GitLab Code Suggestions in VS Code</a>. +</div> +<figure class="video-container"> + <iframe src="https://www.youtube-nocookie.com/embed/WnxBYxN2-p4" frameborder="0" allowfullscreen> </iframe> +</figure> + +## Code Suggestions data usage + +Code Suggestions is a generative artificial intelligence (AI) model hosted on GitLab.com. + +Your personal access token enables a secure API connection to GitLab.com. +This API connection securely transmits a context window from VS Code to the Code Suggestions ML model for inference, +and the generated suggestion is transmitted back to VS Code. + +### Data privacy + +Code Suggestions operate completely in the GitLab.com infrastructure, providing the same level of +[security](https://about.gitlab.com/security/) as any other feature of GitLab.com, and processing any personal +data in accordance with our [Privacy Statement](https://about.gitlab.com/privacy/). + +No new additional data is collected to enable this feature. The content of your GitLab hosted source code is +not used as training data. Source code inference against the Code Suggestions model is not used to re-train the model. +Your data also never leaves GitLab.com. All training and inference is done in GitLab.com infrastructure. + +[Read more about the security of GitLab.com](https://about.gitlab.com/security/faq/). + +### Training data + +Code Suggestions uses open source pre-trained base models from the +[CodeGen family](https://openreview.net/forum?id=iaYcJKpY2B_) including CodeGen-MULTI and CodeGen-NL. +We then re-train and fine-tune these base models with a customized open source dataset to enable multi-language +support and additional use cases. This customized dataset contains non-preprocessed open source code in 13 +programming languages from [The Pile](https://pile.eleuther.ai/) and the +[Google BigQuery source code dataset](https://cloud.google.com/blog/topics/public-datasets/github-on-bigquery-analyze-all-the-open-source-code). +We then process this raw dataset against heuristics that aim to increase the quality of the dataset. + +The Code Suggestions model is not trained on GitLab customer data. + +### Off by default + +Code Suggestions are off by default and require a group owner to enable the feature with a group-level setting. + +After the group-level setting is enabled, developers using Visual Studio Code with the +[GitLab Workflow extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) can connect +to GitLab.com by using a GitLab +[personal access token](../../profile/personal_access_tokens.md#create-a-personal-access-token) with the `read_api` +and `read_user` scopes. + +## Progressive enhancement + +This feature is designed as a progressive enhancement to the existing VS Code GitLab Workflow plugin. +Code Suggestions offer a completion if the machine learning engine can generate a recommendation. +In the event of a connection issue or model inference failure, the feature gracefully degrades. +Code Suggestions do not prevent you from writing code in VS Code. + +### Internet connectivity + +Code Suggestions only work when you have internet connectivity and can access GitLab.com. +Code Suggestions are not available for self-managed customers, nor customers operating within an offline environment. + +### Stability and performance + +This feature is currently in [Beta](/ee/policy/alpha-beta-support.md#beta). +While the Code Suggestions inference API operates completely within the GitLab.com enterprise infrastructure, +we expect a high demand for this Beta feature, which may cause degraded performance or unexpected downtime +of the feature. We have built this feature to gracefully degrade and have controls in place to allow us to +mitigate abuse or misuse. GitLab may disable this feature for any or all customers at any time at our discretion. + +### Model accuracy and quality + +While in Beta, Code Suggestions can generate low-quality, incomplete, and possibly insecure code. +We strongly encourage all beta users to leverage GitLab native +[Code Quality Scanning](../../../ci/testing/code_quality.md) and +[Security Scanning](../../application_security/index.md) capabilities. + +GitLab uses a customized open source dataset to fine-tune the model to support multiple languages. +Based on the languages you code in, GitLab routes the request to a targeted inference and prompt engine +to get relevant suggestions. + +GitLab is actively refining these models to: + +- Improve the quality of recommendations. +- Add support for more languages. +- Add protections to limit personal data, insecure code, and other unwanted behavior + that the model may have learned from training data. + +## Known limitations + +While in Beta, we are working on improving the accuracy of overall generated content. +However, Code Suggestions may generate suggestions that are: + +- Low-quality +- Incomplete +- Produce failed pipelines +- Insecure code +- Offensive or insensitive + +We are also aware of specific situations that can produce unexpected or incoherent results including: + +- Suggestions based on natural language code comments. +- Suggestions that mixed programming languages in unexpected ways. + +## Feedback + +Report issues in the [feedback issue](https://gitlab.com/gitlab-org/gitlab/-/issues/405152). diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index f9a5d4e3aa7..e22dc549a4a 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -1,42 +1,28 @@ --- stage: Create -group: Editor +group: IDE info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/file_finder.html' --- # File finder **(FREE)** -The file finder feature allows you to search for a file in a repository using the -GitLab UI. To use it: +With file finder, you can search for a file in a repository directly from the GitLab UI. -1. Go to your project's **Repository > Files**. -1. In the upper right corner, select **Find File**. +File finder is powered by the [`fuzzaldrin-plus`](https://github.com/jeancroy/fuzz-aldrin-plus) library, which uses fuzzy search and highlights results as you type. -If you prefer to keep your fingers on the keyboard, use the -[shortcut button](../../shortcuts.md), which you can invoke from anywhere -in a project. +## Search for a file -Press `t` to launch the File search function when in **Issues**, -**Merge requests**, **Milestones**, even the project's settings. +To search for a file: -Start typing what you are searching for and watch the magic happen. With the -up/down arrows, you go up and down the results, with `Esc` you close the search -and go back to **Files** +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Files**. +1. In the upper right, select **Find file**. +1. In the search box, start typing the filename. +1. From the dropdown list, select the file. -## How it works +To go to file finder, you can also press <kbd>t</kbd> anywhere in your project. +To go back to **Files**, press <kbd>Esc</kbd>. -The File finder feature is powered by the [Fuzzy filter](https://github.com/jeancroy/fuzz-aldrin-plus) library. - -It implements a fuzzy search with the highlight and tries to provide intuitive -results by recognizing patterns that people use while searching. - -For example, consider the [GitLab FOSS repository](https://gitlab.com/gitlab-org/gitlab-foss/tree/master) and that we want to open -the `app/controllers/admin/deploy_keys_controller.rb` file. - -Using a fuzzy search, we start by typing letters that get us closer to the file. - -NOTE: -To narrow down your search, include `/` in your search terms. +To narrow down your results, include `/` in your search.  diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 929751b7247..74d765fa7fe 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -2,7 +2,6 @@ stage: Create group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/forking_workflow.html' --- # Project forking workflow **(FREE)** @@ -16,14 +15,14 @@ A fork is a personal copy of the repository and all its branches, which you crea in a namespace of your choice. Make changes in your own fork and submit them through a merge request to the repository you don't have access to. -## Creating a fork +## Create a fork > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15013) a new form in GitLab 13.11 [with a flag](../../../user/feature_flags.md) named `fork_project_form`. Disabled by default. > - [Enabled on GitLab.com and self-managed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/77181) in GitLab 14.8. Feature flag `fork_project_form` removed. To fork an existing project in GitLab: -1. On the project's home page, in the upper right, select **{fork}** **Fork**: +1. On the project's homepage, in the upper-right corner, select **Fork** (**{fork}**):  1. Optional. Edit the **Project name**. 1. For **Project URL**, select the [namespace](../../namespace/index.md) @@ -39,10 +38,51 @@ GitLab creates your fork, and redirects you to the new fork's page. ## Update your fork -To copy the latest changes from the upstream repository into your fork, update it -[from the command line](#from-the-command-line). GitLab Premium and higher tiers can also -[configure forks as pull mirrors](#with-repository-mirroring) -of the upstream repository. +A fork can fall out of sync with its upstream repository, and require an update: + +- **Ahead**: Your fork contains new commits not present in the upstream repository. + To sync your fork, create a merge request to push your changes to the upstream repository. +- **Behind**: The upstream repository contains new commits not present in your fork. + To sync your fork, pull the new commits into your fork. +- **Ahead and behind**: Both the upstream repository and your fork contain new commits + not present in the other. To fully sync your fork, create a merge request to push + your changes up, and pull the upstream repository's new changes into your fork. + +To sync your fork with its upstream repository, update it from the GitLab UI +or the command line. GitLab Premium and Ultimate tiers can also automate updates by +[configuring forks as pull mirrors](#with-repository-mirroring) of the upstream repository. + +### From the UI + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/330243) in GitLab 15.11 [with a flag](../../../administration/feature_flags.md) named `synchronize_fork`. Disabled by default, but enabled for projects in the `gitlab-org/gitlab` and `gitlab-com/www-gitlab-com` namespaces only. + +FLAG: +On self-managed GitLab, by default this feature is not available. To make it available, +ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `synchronize_fork`. +On GitLab.com, this feature is available for projects in the `gitlab-org/gitlab` and `gitlab-com/www-gitlab-com` namespaces. + +To update your fork from the GitLab UI: + +1. On the top bar, select **Main menu > Projects > View all projects**. +1. On the secondary menu, select **Personal**. +1. Select the fork you want to update. +1. Below the dropdown list for branch name, find the **Forked from** (**{fork}**) + information box to determine if your fork is ahead, behind, or both. In this example, + the fork is behind the upstream repository: + +  + +1. If your fork is **ahead** of the upstream repository, select + **Create merge request** to propose adding your fork's changes to the upstream repository. +1. If your fork is **behind** the upstream repository, select **Update fork** + to pull changes from the upstream repository. +1. If your fork is **ahead and behind** the upstream repository, you can update from the UI + available only if no merge conflicts are detected: + - If your fork contains no merge conflicts, you can select **Create merge request** + to propose pushing your changes to the upstream repository, **Update fork** + to pull changes down to your fork, or both. The type of changes in your fork + determine which actions are appropriate. + - If your fork contains merge conflicts, update your fork from the command line. ### From the command line @@ -102,7 +142,7 @@ an `upstream` remote repository for your fork: A fork can be configured as a mirror of the upstream if all these conditions are met: -1. Your subscription is **(PREMIUM)** or a higher tier. +1. Your subscription is **Premium** or **Ultimate**. 1. You create all changes in branches (not `main`). 1. You do not work on [merge requests for confidential issues](../merge_requests/confidential.md), which requires changes to `main`. @@ -114,7 +154,7 @@ For instructions, read [Configure pull mirroring](mirror/pull.md#configure-pull- WARNING: With mirroring, before approving a merge request, you are asked to sync. You should automate it. -## Merging upstream +## Merge changes back upstream When you are ready to send your code back to the upstream project, [create a merge request](../merge_requests/creating_merge_requests.md). For **Source branch**, @@ -129,11 +169,55 @@ Then you can add labels, a milestone, and assign the merge request to someone wh your changes. Then select **Submit merge request** to conclude the process. When successfully merged, your changes are added to the repository and branch you're merging into. -## Removing a fork relationship +## Unlink a fork -You can unlink your fork from its upstream project in the [advanced settings](../settings/index.md#remove-a-fork-relationship). +Removing a fork relationship unlinks your fork from its upstream project. +Your fork then becomes an independent project. + +Prerequisites: + +- You must be a project owner to unlink a fork. + +WARNING: +If you remove a fork relationship, you can't send merge requests to the source. +If anyone has forked your project, their fork also loses the relationship. +To restore the fork relationship, [use the API](../../../api/projects.md#create-a-forked-fromto-relation-between-existing-projects). + +To remove a fork relationship: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Advanced**. +1. In the **Remove fork relationship** section, select **Remove fork relationship**. +1. To confirm, enter the project path and select **Confirm**. + +When you unlink a fork that uses a [hashed storage pool](../../../administration/repository_storage_types.md#hashed-object-pools) +to share objects with another repository: + +- All objects are copied from the pool into your fork. +- After the copy process completes, no further updates from the storage pool are propagated to your fork. ## Related topics -- GitLab blog post: [How to keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/). -- GitLab community forum: [Refreshing a fork](https://forum.gitlab.com/t/refreshing-a-fork/). +- GitLab blog post: [Keep your fork up to date with its origin](https://about.gitlab.com/blog/2016/12/01/how-to-keep-your-fork-up-to-date-with-its-origin/) +- GitLab community forum: [Refreshing a fork](https://forum.gitlab.com/t/refreshing-a-fork/32469) + +## Troubleshooting + +### Error: `An error occurred while forking the project. Please try again` + +This error can be due to a mismatch in shared runner settings between the forked project +and the new namespace. See [Forks](../../../ci/runners/configure_runners.md#forks) +in the Runner documentation for more information. + +### Removing fork relationship fails + +If removing the fork through the UI or API is not working, you can attempt the +fork relationship removal in a +[Rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session): + +```ruby +p = Project.find_by_full_path('<project_path>') +u = User.find_by_username('<username>') +Projects::UnlinkForkService.new(p, u).execute +``` diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 78fcdec2a0b..fbf29bddd46 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -14,7 +14,7 @@ commit hash. To view it for a file: 1. Go to your project's **Repository > Files**. 1. Select the file you want to review. -1. In the upper right corner, select **Blame**. +1. In the upper-right corner, select **Blame**. When you select **Blame**, this information is displayed: diff --git a/doc/user/project/repository/git_history.md b/doc/user/project/repository/git_history.md index 321b9a5eb53..a9228b8cabd 100644 --- a/doc/user/project/repository/git_history.md +++ b/doc/user/project/repository/git_history.md @@ -12,7 +12,7 @@ Git file History provides information about the commit history associated with a file. To use it: 1. Go to your project's **Repository > Files**. -1. In the upper right corner, select **History**. +1. In the upper-right corner, select **History**. When you select **History**, this information is displayed: diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md index 64f19d1a92c..a2dd2488961 100644 --- a/doc/user/project/repository/gpg_signed_commits/index.md +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -43,7 +43,7 @@ To view a user's public GPG key, you can either: - Go to `https://gitlab.example.com/<USERNAME>.gpg`. GitLab displays the GPG key, if the user has configured one, or a blank page for users without a configured GPG key. -- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the upper right +- Go to the user's profile (such as `https://gitlab.example.com/<USERNAME>`). In the upper-right corner of the user's profile, select **View public GPG keys** (**{key}**). ## Configure commit signing diff --git a/doc/user/project/repository/img/update-fork_v15_11.png b/doc/user/project/repository/img/update-fork_v15_11.png Binary files differnew file mode 100644 index 00000000000..244868d80ae --- /dev/null +++ b/doc/user/project/repository/img/update-fork_v15_11.png diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 5b4e1b14489..9f0c46591b9 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -25,7 +25,7 @@ You can add files to a repository: - When you create a project. - After you create a project: - By using [the web editor](web_editor.md). - - [From the command line](../../../gitlab-basics/command-line-commands.md). + - From the command line. ## Commit changes to a repository @@ -235,9 +235,9 @@ The size can differ slightly from one instance to another due to compression, ho Administrators can set a [repository size limit](../../admin_area/settings/account_and_limit_settings.md). [GitLab sets the size limits for GitLab.com](../../gitlab_com/index.md#account-and-limit-settings). -## Repository contributor graph +## Repository contributor statistics -All code contributors are displayed under your project's **Repository > Contributors**. +All code contributors are displayed under your project's **Repository > Contributor statistics**. The graph shows the contributor with the most commits to the fewest. @@ -277,15 +277,15 @@ to fetch configuration from a project that is renamed or moved. ## Related topics -- [GitLab Workflow VS Code extension](vscode.md). -- To lock files and prevent change conflicts, use [file locking](../file_lock.md). -- [Repository API](../../../api/repositories.md). -- [Find files](file_finder.md) in a repository. -- [Branches](branches/index.md). -- [Create a directory](web_editor.md#create-a-directory). -- [Find file history](git_history.md). -- [Identify changes by line (Git blame)](git_blame.md). -- [Use Jupyter notebooks with GitLab](jupyter_notebooks/index.md). +- [GitLab Workflow VS Code extension](vscode.md) +- [Lock files and prevent change conflicts](../file_lock.md) +- [Repository API](../../../api/repositories.md) +- [Find files](file_finder.md) +- [Branches](branches/index.md) +- [Create a directory](web_editor.md#create-a-directory) +- [Find file history](git_history.md) +- [Identify changes by line (Git blame)](git_blame.md) +- [Use Jupyter notebooks with GitLab](jupyter_notebooks/index.md) ## Troubleshooting diff --git a/doc/user/project/repository/jupyter_notebooks/index.md b/doc/user/project/repository/jupyter_notebooks/index.md index 28f0ffb6fbd..1526c7b4dc2 100644 --- a/doc/user/project/repository/jupyter_notebooks/index.md +++ b/doc/user/project/repository/jupyter_notebooks/index.md @@ -25,7 +25,7 @@ GitLab. ## Cleaner diffs and raw diffs -> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6589) in GitLab 14.5 as an [Alpha](../../../../policy/alpha-beta-support.md#alpha-features) release [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. Enabled by default. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6589) in GitLab 14.5 as an [Experiment](../../../../policy/alpha-beta-support.md#experiment) release [with a flag](../../../../administration/feature_flags.md) named `jupyter_clean_diffs`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/75500) in GitLab 14.9. Feature flag `jupyter_clean_diffs` removed. > - [Reintroduced toggle](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/85079) in GitLab 15.0 [with a flag](../../../../administration/feature_flags.md) named `ipynb_semantic_diff`. Enabled by default. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/95373) in GitLab 15.6. Feature flag `ipynb_semantic_diff` removed. diff --git a/doc/user/project/repository/mirror/bidirectional.md b/doc/user/project/repository/mirror/bidirectional.md index 9942469dd5c..0563f747e8d 100644 --- a/doc/user/project/repository/mirror/bidirectional.md +++ b/doc/user/project/repository/mirror/bidirectional.md @@ -2,7 +2,6 @@ stage: Create group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- # Bidirectional mirroring **(PREMIUM)** @@ -168,4 +167,4 @@ Read about [Git Fusion settings on Perforce.com](https://www.perforce.com/manual ## Related topics -- [Configure server hooks](../../../../administration/server_hooks.md) on a GitLab server. +- [Configure server hooks](../../../../administration/server_hooks.md) diff --git a/doc/user/project/repository/mirror/index.md b/doc/user/project/repository/mirror/index.md index 7a50c294dfc..9f72b8f29b2 100644 --- a/doc/user/project/repository/mirror/index.md +++ b/doc/user/project/repository/mirror/index.md @@ -2,7 +2,6 @@ stage: Create group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- # Repository mirroring **(FREE)** @@ -107,13 +106,14 @@ To use this option, select **Only mirror protected branches** when you create a ## Mirror specific branches -> Mirroring branches matching a regex [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102608) in GitLab 15.8 [with a flag](../../../../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default. +> - Mirroring branches matching a regex [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/102608) in GitLab 15.8 [with a flag](../../../../administration/feature_flags.md) named `mirror_only_branches_match_regex`. Disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/381667) in GitLab 16.0. FLAG: -On self-managed GitLab, by default the field `mirror_branch_regex` is not available. -To make it available, ask an administrator to [enable the feature flag](../../../../administration/feature_flags.md) +On self-managed GitLab, by default the field `mirror_branch_regex` is available. +To hide the feature, ask an administrator to [disable the feature flag](../../../../administration/feature_flags.md) named `mirror_only_branches_match_regex`. -On GitLab.com, this feature is not available. +On GitLab.com, this feature is available. To mirror only branches with names matching an [re2 regular expression](https://github.com/google/re2/wiki/Syntax), enter a regular expression into the **Mirror specific branches** field. Branches with names that @@ -331,6 +331,29 @@ and requires the full version including the protocol (`ssh://git@gitlab.com/gitl Make sure that host and project path are separated using `/` instead of `:`. +### Host key verification failed + +This error is returned when the target host public SSH key changes. +Public SSH keys rarely, if ever, change. If host key verification fails, +but you suspect the key is still valid, you can refresh the key's information. + +Prerequisites: + +- You must have at least the Maintainer role for a project. + +To resolve the issue: + +1. [Verify the host key](#verify-a-host-key). +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Repository**. +1. Expand **Mirroring repositories**. +1. To refresh the keys, either: + + - Select **Detect host keys** for GitLab to fetch the host keys from the server, and display the fingerprints. + - Select **Input host keys manually**, and enter the host key into the **SSH host key** field. + +- Select **Mirror repository**. + ### Transfer mirror users and tokens to a single service account in Rails console This requires access to the [GitLab Rails console](../../../../administration/operations/rails_console.md#starting-a-rails-console-session). diff --git a/doc/user/project/repository/mirror/pull.md b/doc/user/project/repository/mirror/pull.md index 0eb51f40208..2b8470b9e3d 100644 --- a/doc/user/project/repository/mirror/pull.md +++ b/doc/user/project/repository/mirror/pull.md @@ -2,7 +2,6 @@ stage: Create group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- # Pull from a remote repository **(PREMIUM)** @@ -142,6 +141,5 @@ end ## Related topics -- Configure [pull mirroring intervals](../../../../administration/instance_limits.md#pull-mirroring-interval) - on self-managed instances. -- Configure [pull mirroring through the API](../../../../api/projects.md#configure-pull-mirroring-for-a-project). +- [Pull mirroring intervals](../../../../administration/instance_limits.md#pull-mirroring-interval) +- [Pull mirroring API](../../../../api/projects.md#configure-pull-mirroring-for-a-project) diff --git a/doc/user/project/repository/mirror/push.md b/doc/user/project/repository/mirror/push.md index f06dd747897..11093958650 100644 --- a/doc/user/project/repository/mirror/push.md +++ b/doc/user/project/repository/mirror/push.md @@ -2,7 +2,6 @@ stage: Create group: Source Code info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/workflow/repository_mirroring.html' --- # Push mirroring **(FREE)** @@ -26,8 +25,10 @@ When you push a change to the upstream repository, the push mirror receives it: - Within five minutes. - Within one minute, if you enabled **Only mirror protected branches**. -In the case of a diverged branch, an error displays in the **Mirroring repositories** -section. +When a branch is merged into the default branch and deleted in the source project, +it is deleted from the remote mirror on the next push. Branches with unmerged +changes are kept. If a branch diverges, the **Mirroring repositories** section +displays an error. ## Configure push mirroring @@ -194,4 +195,4 @@ If it isn't working correctly, a red `error` tag appears, and shows the error me ## Related topics -- [Remote mirrors API](../../../../api/remote_mirrors.md). +- [Remote mirrors API](../../../../api/remote_mirrors.md) diff --git a/doc/user/project/repository/push_rules.md b/doc/user/project/repository/push_rules.md index 7ae085812ae..28afba375fc 100644 --- a/doc/user/project/repository/push_rules.md +++ b/doc/user/project/repository/push_rules.md @@ -13,7 +13,7 @@ can and can't be pushed to your repository. While GitLab offers - Evaluating the contents of a commit. - Confirming commit messages match expected formats. -- Enforcing branch name rules. +- Enforcing [branch name rules](branches/index.md#name-your-branch). - Evaluating the details of files. - Preventing Git tag removal. diff --git a/doc/user/project/repository/reducing_the_repo_size_using_git.md b/doc/user/project/repository/reducing_the_repo_size_using_git.md index cf7d4f44aad..4bebe4c1a97 100644 --- a/doc/user/project/repository/reducing_the_repo_size_using_git.md +++ b/doc/user/project/repository/reducing_the_repo_size_using_git.md @@ -22,16 +22,27 @@ Rewriting repository history is a destructive operation. Make sure to back up yo you begin. The best way to back up a repository is to [export the project](../settings/import_export.md#export-a-project-and-its-data). +## Calculate repository size + +The size of a repository is determined by computing the accumulated size of all files in the repository. +It is similar to executing `du --summarize --bytes` on your repository's +[hashed storage path](../../../administration/repository_storage_types.md). + ## Purge files from repository history -To reduce the size of your repository in GitLab, you must first remove references to large files from branches, tags, *and* -other internal references (refs) that are automatically created by GitLab. These refs include: +GitLab [prunes unreachable objects](../../../administration/housekeeping.md#prune-unreachable-objects) +as part of housekeeping. In GitLab, to reduce the disk size of your repository manually, you must +first remove references to large files from branches, tags, *and* other internal references (refs) +created by GitLab. These refs include: -- `refs/merge-requests/*` for merge requests. -- `refs/pipelines/*` for - [pipelines](../../../ci/troubleshooting.md#fatal-reference-is-not-a-tree-error). -- `refs/environments/*` for environments. -- `refs/keep-around/*` are created as hidden refs to prevent commits referenced in the database from being removed +- `refs/merge-requests/*` +- `refs/pipelines/*` +- `refs/environments/*` +- `refs/keep-around/*` + +NOTE: +For details on each of these references, see +[GitLab-specific references](../../../development/gitaly.md#gitlab-specific-references). These refs are not automatically downloaded and hidden refs are not advertised, but we can remove these refs using a project export. diff --git a/doc/user/project/repository/tags/img/tag-display_v15_9.png b/doc/user/project/repository/tags/img/tag-display_v15_9.png Binary files differnew file mode 100644 index 00000000000..015df07d025 --- /dev/null +++ b/doc/user/project/repository/tags/img/tag-display_v15_9.png diff --git a/doc/user/project/repository/tags/img/tags_commits_view_v15_10.png b/doc/user/project/repository/tags/img/tags_commits_view_v15_10.png Binary files differnew file mode 100644 index 00000000000..247d2f368d5 --- /dev/null +++ b/doc/user/project/repository/tags/img/tags_commits_view_v15_10.png diff --git a/doc/user/project/repository/tags/index.md b/doc/user/project/repository/tags/index.md new file mode 100644 index 00000000000..e252a9a433b --- /dev/null +++ b/doc/user/project/repository/tags/index.md @@ -0,0 +1,120 @@ +--- +stage: Create +group: Source Code +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Tags **(FREE)** + +In Git, a tag marks an important point in a repository's history. +Git supports two types of tags: + +- **Lightweight tags** point to specific commits, and contain no other information. + Also known as soft tags. Create or remove them as needed. +- **Annotated tags** contain metadata, can be signed for verification purposes, + and can't be changed. + +The creation or deletion of a tag can be used as a trigger for automation, including: + +- Using a [webhook](../../integrations/webhook_events.md#tag-events) to automate actions + like Slack notifications. +- Signaling a [repository mirror](../mirror/index.md) to update. +- Running a CI/CD pipeline with [`if: $CI_COMMIT_TAG`](../../../../ci/jobs/job_control.md#common-if-clauses-for-rules). + +When you [create a release](../../releases/index.md), +GitLab also creates a tag to mark the release point. +Many projects combine an annotated release tag with a stable branch. Consider +setting deployment or release tags automatically. + +In the GitLab UI, each tag displays: + + + +- The tag name. (**{tag}**) +- Optional. If the tag is [protected](../../protected_tags.md), a **protected** badge. +- The commit SHA (**{commit}**), linked to the commit's contents. +- The commit's title and creation date. +- Optional. A link to the release (**{rocket}**). +- Optional. If a pipeline has been run, the current pipeline status. +- Download links to the source code and artifacts linked to the tag. +- A [**Create release**](../../releases/index.md#create-a-release) (**{pencil}**) link. +- A link to delete the tag. + +## View tags for a project + +To view all existing tags for a project: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Tags**. + +## View tagged commits in the commits list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18795) in GitLab 15.10. + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Commits**. +1. Commits with a tag are labeled with a tag icon (**{tag}**) and the name of the tag. + This example shows a commit tagged `v1.26.0`: + +  + +To view the list of commits in this tag, select the tag name. + +## Create a tag + +Tags can be created from the command line, or the GitLab UI. + +### From the command line + +To create either a lightweight or annotated tag from the command line, and push it upstream: + +1. To create a lightweight tag, run the command `git tag TAG_NAME`, changing + `TAG_NAME` to your desired tag name. +1. To create an annotated tag, run one of the versions of `git tag` from the command line: + + ```shell + # In this short version, the annotated tag's name is "v1.0", + # and the message is "Version 1.0". + git tag -a v1.0 -m "Version 1.0" + + # Use this version to write a longer tag message + # for annotated tag "v1.0" in your text editor. + git tag -a v1.0 + ``` + +1. Push your tags upstream with `git push origin --tags`. + +### From the UI + +To create a tag from the GitLab UI: + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Tags**. +1. Select **New tag**. +1. Provide a **Tag name**. +1. For **Create from**, select an existing branch name, tag, or commit SHA. +1. Optional. Add a **Message** to create an annotated tag, or leave blank to + create a lightweight tag. +1. Select **Create tag**. + +## Prevent tag deletion **(PREMIUM)** + +To prevent users from removing a tag with `git push`, create a [push rule](../push_rules.md). + +## Trigger pipelines from a tag + +GitLab CI/CD provides a [`CI_COMMIT_TAG` variable](../../../../ci/variables/predefined_variables.md) +to identify tags. Use this variable in job rules and workflow rules to test if the pipeline +was triggered by a tag. + +In your `.gitlab-ci.yml` file for the CI/CD pipeline configuration of your project, +you can trigger based on a new tag: + +- At the job level, with the [`only` keyword](../../../../ci/yaml/index.md#only--except). +- At the pipeline level, with the [workflow rules keywords](../../../../ci/yaml/workflow.md). + +## Related topics + +- [Tagging (Git reference page)](https://git-scm.com/book/en/v2/Git-Basics-Tagging) +- [Protected tags](../../protected_tags.md) +- [Tags API](../../../../api/tags.md) diff --git a/doc/user/project/repository/vscode.md b/doc/user/project/repository/vscode.md index 9260d59bc3a..2a33476b545 100644 --- a/doc/user/project/repository/vscode.md +++ b/doc/user/project/repository/vscode.md @@ -1,6 +1,6 @@ --- stage: Create -group: Editor +group: IDE info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -22,6 +22,7 @@ do more day-to-day tasks in Visual Studio Code, such as: and paste snippets to, and from, your editor. - [Browse repositories](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#browse-a-repository-without-cloning) without cloning them. +- [Receive Code Suggestions](code_suggestions.md) ## Download the extension @@ -34,6 +35,7 @@ you can [configure](https://marketplace.visualstudio.com/items?itemName=GitLab.g - [Features to display or hide](https://gitlab.com/gitlab-org/gitlab-vscode-extension#extension-settings). - [Self-signed certificate](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow#self-signed-certificates) information. +- [Code Suggestions](code_suggestions.md) ## Report issues with the extension @@ -44,5 +46,4 @@ Report any issues, bugs, or feature requests in the - [Download the extension](https://marketplace.visualstudio.com/items?itemName=GitLab.gitlab-workflow) - [Extension documentation](https://gitlab.com/gitlab-org/gitlab-vscode-extension/-/blob/main/README.md) -- The extension source code is available in the - [`gitlab-vscode-extension`](https://gitlab.com/gitlab-org/gitlab-vscode-extension/) project. +- [View source code](https://gitlab.com/gitlab-org/gitlab-vscode-extension/) diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index 80b0ada6f7b..dc988846676 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -1,6 +1,6 @@ --- stage: Create -group: Editor +group: IDE info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- @@ -26,11 +26,32 @@ for any change you commit through the Web Editor. To create a text file in the Web Editor: 1. On the top bar, select **Main menu > Projects** and find your project. -1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). +1. From the project dashboard or repository, next to the branch name, + select the plus icon (**{plus}**). 1. From the dropdown list, select **New file**. -1. Complete the fields. To create a merge request with the new file, ensure the **Start a new merge request with these changes** checkbox is selected. +1. Complete the fields. +1. To create a merge request with the new file, ensure the **Start a new merge request with these changes** checkbox is selected, if you had chosen a **Target branch** other than the [default branch (such as `main`)](../../../user/project/repository/branches/default.md). 1. Select **Commit changes**. +### Create a file from a template + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Repository > Files**. +1. Next to the project name, select the plus icon (**{plus}**) to display a + dropdown list, then select **New file** from the list. +1. For **Filename**, provide one of the filenames that GitLab provides a template for: + - `.gitignore` + - `.gitlab-ci.yml` + - `LICENSE` + - `Dockerfile` +1. Select **Apply a template**, then select the template you want to apply. +1. Make your changes to the file. +1. Provide a **Commit message**. +1. Enter a **Target branch** to merge into. To create a new merge request with + your changes, enter a branch name that is not your repository's + [default branch](../../../user/project/repository/branches/default.md), +1. Select **Commit changes** to add the commit to your branch. + ## Edit a file To edit a text file in the Web Editor: @@ -87,6 +108,9 @@ To link to a single line, you can also: To upload a binary file in the Web Editor: +<!-- This list is duplicated at doc/gitlab-basics/add-file.md#from-the-ui --> +<!-- For why we duplicated the info, see https://gitlab.com/gitlab-org/gitlab/-/merge_requests/111072#note_1267429478 --> + 1. On the top bar, select **Main menu > Projects** and find your project. 1. From the project dashboard or repository, next to the branch name, select the plus icon (**{plus}**). 1. From the dropdown list, select **Upload file**. @@ -115,7 +139,7 @@ To create a [branch](branches/index.md) in the Web Editor: ## Create a tag -You can create [tags](../../../topics/git/tags.md) to mark milestones such as +You can create [tags](tags/index.md) to mark milestones such as production releases and release candidates. To create a tag in the Web Editor: 1. On the top bar, select **Main menu > Projects** and find your project. diff --git a/doc/user/project/repository/x509_signed_commits/index.md b/doc/user/project/repository/x509_signed_commits/index.md index 42f7be30822..80538697100 100644 --- a/doc/user/project/repository/x509_signed_commits/index.md +++ b/doc/user/project/repository/x509_signed_commits/index.md @@ -32,7 +32,7 @@ For a commit or tag to be *verified* by GitLab: from the certificate in the signature to a trusted certificate in the GitLab certificate store. This chain may include intermediate certificates supplied in the signature. You may need to add certificates, such as Certificate Authority root certificates, - [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). + [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl/index.html#install-custom-public-certificates). - The signing time must be in the time range of the [certificate validity](https://www.rfc-editor.org/rfc/rfc5280.html#section-4.1.2.5), which is usually up to three years. @@ -101,7 +101,7 @@ To configure Windows or macOS: - Downloading the installer. - Running `brew install smimesign` on macOS. 1. Get the ID of your certificate by running `smimesign --list-keys`. -1. Set your signing key by running `git config --global user.signingkey ID`. +1. Set your signing key by running `git config --global user.signingkey <ID>`, replacing `<ID>` with the certificate ID. 1. Configure X.509 with this command: ```shell @@ -342,7 +342,7 @@ step of the previous [main verification checks](#main-verification-checks). ``` 1. If this fails, add the missing certificates required to establish trust - [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). + [to the GitLab certificate store](https://docs.gitlab.com/omnibus/settings/ssl/index.html#install-custom-public-certificates). 1. After adding more certificates, (if these troubleshooting steps then pass) run the Rake task to [re-verify commits](#re-verify-commits). |
