diff options
Diffstat (limited to 'doc/user/project/merge_requests/reviews/suggestions.md')
| -rw-r--r-- | doc/user/project/merge_requests/reviews/suggestions.md | 204 |
1 files changed, 112 insertions, 92 deletions
diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md index 668dece9fda..9187c5fad44 100644 --- a/doc/user/project/merge_requests/reviews/suggestions.md +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -8,156 +8,176 @@ type: index, reference # Suggest changes **(FREE)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) custom commit messages for suggestions in GitLab 13.9 [with a flag](../../../../administration/feature_flags.md) named `suggestions_custom_commit`. Disabled by default. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/297404) in GitLab 13.10. - -As a reviewer, you're able to suggest code changes with a Markdown syntax in merge request -diff threads. Then, the merge request author (or other users with appropriate -[permission](../../../permissions.md)) can apply these suggestions. -This action generates a commit in the merge request, authored by the user that suggested the changes. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/297404) in GitLab 13.10. Feature flag `suggestions_custom_commit` removed. + +Reviewers can suggest code changes with a Markdown syntax in merge request diff threads. +The merge request author (or other users with the appropriate role) can apply any or +all of the suggestions from the GitLab UI. Applying suggestions adds a commit to the +merge request, authored by the user who suggested the changes. + +## Create suggestions + +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and find your merge request. +1. On the secondary menu, select **Changes**. +1. Find the lines of code you want to change. + - To select a single line: + - Hover over the line number, and + select **Add a comment to this line** (**{comment}**). + - To select multiple lines: + 1. Hover over the line number, and select **Add a comment to this line** (**{comment}**). + 1. Select and drag your selection until all desired lines are included. To + learn more, see [Multi-line suggestions](#multi-line-suggestions). +1. In the comment toolbar, select **Insert suggestion** (**{doc-code}**). GitLab + inserts a pre-populated code block into your comment, like this: + + ````markdown + ```suggestion:-0+0 + The content of the line you selected is shown here. + ``` + ```` + +1. Edit the pre-populated code block to add your suggestion. +1. Select either **Start a review** or **Add to review** to add your comment to a + [review](index.md), or **Add comment now** to add the comment to the thread immediately. -1. Choose a line of code to be changed, add a new comment, then select - the **Insert suggestion** icon in the toolbar: +### Multi-line suggestions -  +> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/232339) in GitLab 13.11: suggestions in multi-line comments also become multi-line. -1. In the comment, add your suggestion to the pre-populated code block: +When you review a merge request diff, you can propose changes to multiple lines (up to 200) +in a single suggestion, by either: -  +- Selecting and dragging, as described in [Create suggestions](#create-suggestions). + GitLab creates a suggestion block for you. +- Selecting a single line, then manually adjusting the range offsets. -1. Select either **Start a review** or **Add to review** to add your comment to a - [review](index.md), or **Add comment now** to add the comment to the thread immediately. +The range offsets in the first line of the suggestion describe line numbers relative +to the line you selected. The offsets specify the lines your suggestion intends to replace. +For example, this suggestion covers 3 lines above and 4 lines below the +commented line: - The suggestion in the comment can be applied by the merge request author - directly from the merge request: +````markdown +```suggestion:-3+4 + "--talk-name=ca.desrt.dconf", + "--socket=wayland", +``` +```` -  +When applied, the suggestion replaces from 3 lines above to 4 lines below the commented line: -1. Optionally specify a custom commit message for individual suggestions (GitLab 13.9 and later) to - describe your change. If you don't specify it, the default commit message is used. + -  +Suggestions for multiple lines are limited to 100 lines _above_ and 100 +lines _below_ the commented diff line. This allows for up to 200 changed lines per +suggestion. -After the author applies a suggestion: +## Apply suggestions -1. The suggestion is marked as **Applied**. -1. The thread is resolved. -1. GitLab creates a new commit with the changes. -1. If the user has the Developer role, GitLab pushes - the suggested change directly into the codebase in the merge request's branch. +Prerequisites: -## Multi-line suggestions +- You must be the author of the merge request, or have at least the Developer role in the project. -> [Changed](https://gitlab.com/gitlab-org/gitlab/-/issues/232339) in GitLab 13.11: suggestions in multi-line comments also become multi-line. +To apply suggested changes directly from the merge request: -Reviewers can also suggest changes to multiple lines with a single suggestion -within merge request diff threads by selecting and dragging selection to all -relevant line numbers or by adjusting the range offsets. The -offsets are relative to the position of the diff thread, and specify the -range to be replaced by the suggestion when it is applied. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and find your merge request. +1. Find the comment containing the suggestion you want to apply. + - To apply suggestions individually, select **Apply suggestion**. + - To apply multiple suggestions in a single commit, select **Add suggestion to batch**. +1. Optional. Provide a custom commit message to describe your change. If you don't provide a custom message, the default commit message is used. +1. Select **Apply**. - +After a suggestion is applied: -In the previous example, the suggestion covers three lines above and four lines -below the commented line. When applied, it would replace from 3 lines _above_ -to 4 lines _below_ the commented line, with the suggested change. +- The suggestion is marked as **Applied**. +- The comment thread is resolved. +- GitLab creates a new commit with the changes. +- If the user has the Developer role, GitLab pushes + the suggested change directly into the codebase in the merge request's branch. - - -NOTE: -Suggestions for multiple lines are limited to 100 lines _above_ and 100 -lines _below_ the commented diff line. This allows for up to 200 changed lines per -suggestion. - -## Code block nested in suggestions +## Nest code blocks in suggestions To add a suggestion that includes a [fenced code block](../../../markdown.md#code-spans-and-blocks), wrap your suggestion in four backticks instead of three: -~~~markdown +`````markdown ````suggestion:-0+2 ```shell git config --global receive.advertisepushoptions true ``` ```` -~~~ +`````  ## Configure the commit message for applied suggestions -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13086) in GitLab 12.7. +GitLab uses a default commit message when applying suggestions. This message +supports placeholders, and can be changed. For example, the default message +`Apply %{suggestions_count} suggestion(s) to %{files_count} file(s)` renders +like this if you apply three suggestions to two different files: -GitLab uses a default commit message -when applying suggestions: `Apply %{suggestions_count} suggestion(s) to %{files_count} file(s)` - -<!-- vale gitlab.BadPlurals = NO --> +```plaintext +Apply 3 suggestion(s) to 2 file(s) +``` -For example, consider that a user applied 3 suggestions to 2 different files, the -default commit message is: **Apply 3 suggestion(s) to 2 file(s)** +Merge requests created from forks use the template defined in the target project. -<!-- vale gitlab.BadPlurals = YES --> +To meet your project's needs, you can customize these messages and include other +placeholder variables: -These commit messages can be customized to follow any guidelines you might have. -To do so, expand the **Merge requests** tab within your project's **General** -settings and change the **Merge suggestions** text: +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Settings > Merge requests**. +1. Scroll to **Merge suggestions**, and alter the text to meet your needs. + See [Supported variables](#supported-variables) for a list of placeholders + you can use in this message. - +### Supported variables -You can also use following variables besides static text: +The template for commit messages for applied suggestions supports these variables: | Variable | Description | Output example | |------------------------|-------------|----------------| | `%{branch_name}` | The name of the branch to which suggestions were applied. | `my-feature-branch` | -| `%{files_count}` | The number of files to which suggestions were applied.| **2** | +| `%{files_count}` | The number of files to which suggestions were applied.| `2` | | `%{file_paths}` | The paths of the file to which suggestions were applied. Paths are separated by commas.| `docs/index.md, docs/about.md` | | `%{project_path}` | The project path. | `my-group/my-project` | -| `%{project_name}` | The human-readable name of the project. | **My Project** | -| `%{suggestions_count}` | The number of suggestions applied.| **3** | +| `%{project_name}` | The human-readable name of the project. | `My Project` | +| `%{suggestions_count}` | The number of suggestions applied.| `3` | | `%{username}` | The username of the user applying suggestions. | `user_1` | -| `%{user_full_name}` | The full name of the user applying suggestions. | **User 1** | +| `%{user_full_name}` | The full name of the user applying suggestions. | `User 1` | For example, to customize the commit message to output -**Addresses user_1's review**, set the custom text to +`Addresses user_1's review`, set the custom text to `Addresses %{username}'s review`. -For merge requests created from forks, GitLab uses the template defined in target project. - -NOTE: -Custom commit messages for each applied suggestion is -introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/-/issues/25381). - ## Batch suggestions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [alpha feature](../../../../policy/alpha-beta-support.md#alpha-features) with a flag named `batch_suggestions`, disabled by default. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25486) in GitLab 13.1 as an [Experiment](../../../../policy/alpha-beta-support.md#experiment) with a flag named `batch_suggestions`, disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. [Feature flag `batch_suggestions`](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) removed. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/326168) custom commit messages for batch suggestions in GitLab 14.4. -You can apply multiple suggestions at once to reduce the number of commits added -to your branch to address your reviewers' requests. - -1. To start a batch of suggestions to apply with a single commit, select **Add suggestion to batch**: - -  - -1. Add as many additional suggestions to the batch as you wish: - -  - -1. To remove suggestions, select **Remove from batch**: - -  +To reduce the number of commits added to your branch, you can apply multiple +suggestions in a single commit. -1. Having added all the suggestions to your liking, when ready, select **Apply suggestions**. You - can optionally specify a custom commit message for [batch suggestions](#batch-suggestions) - (GitLab 14.4 and later) to describe your change. If you don't specify it, the default commit - message is used. +1. On the top bar, select **Main menu > Projects** and find your project. +1. On the left sidebar, select **Merge requests** and find your merge request. +1. For each suggestion you want to apply, and select **Add suggestion to batch**. +1. Optional. To remove a suggestion, select **Remove from batch**. +1. After you add your desired suggestions, select **Apply suggestions**. -  + WARNING: + If you apply a batch of suggestions containing changes from multiple authors, + you are credited as the resulting commit's author. If your project is configured + to [prevent approvals from users who add commits](../approvals/settings.md#prevent-approvals-by-users-who-add-commits), you are no longer an eligible + approver for this merge request. -WARNING: -Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions. +1. Optional. Provide a custom commit message for [batch suggestions](#batch-suggestions) + (GitLab 14.4 and later) to describe your change. If you don't specify one, + the default commit message is used. ## Related topics |