diff options
Diffstat (limited to 'doc/user/project/merge_requests/reviews')
25 files changed, 559 insertions, 0 deletions
diff --git a/doc/user/project/merge_requests/reviews/img/add_another_suggestion_to_batch_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/add_another_suggestion_to_batch_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..e8aa4b7c730 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/add_another_suggestion_to_batch_v13_1.jpg diff --git a/doc/user/project/merge_requests/reviews/img/add_first_suggestion_to_batch_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/add_first_suggestion_to_batch_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..d15f5d53e55 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/add_first_suggestion_to_batch_v13_1.jpg diff --git a/doc/user/project/merge_requests/reviews/img/apply_batch_of_suggestions_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/apply_batch_of_suggestions_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..3e1e9c20af9 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/apply_batch_of_suggestions_v13_1.jpg diff --git a/doc/user/project/merge_requests/reviews/img/apply_suggestion_v13_9.png b/doc/user/project/merge_requests/reviews/img/apply_suggestion_v13_9.png Binary files differnew file mode 100644 index 00000000000..e27fa629672 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/apply_suggestion_v13_9.png diff --git a/doc/user/project/merge_requests/reviews/img/comment-on-any-diff-line_v13_10.png b/doc/user/project/merge_requests/reviews/img/comment-on-any-diff-line_v13_10.png Binary files differnew file mode 100644 index 00000000000..a31fea85be9 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/comment-on-any-diff-line_v13_10.png diff --git a/doc/user/project/merge_requests/reviews/img/custom_commit_v13_9.png b/doc/user/project/merge_requests/reviews/img/custom_commit_v13_9.png Binary files differnew file mode 100644 index 00000000000..170c04542dd --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/custom_commit_v13_9.png diff --git a/doc/user/project/merge_requests/reviews/img/make_suggestion_v13_9.png b/doc/user/project/merge_requests/reviews/img/make_suggestion_v13_9.png Binary files differnew file mode 100644 index 00000000000..92d5ba5ddda --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/make_suggestion_v13_9.png diff --git a/doc/user/project/merge_requests/reviews/img/merge_request_pipeline.png b/doc/user/project/merge_requests/reviews/img/merge_request_pipeline.png Binary files differnew file mode 100644 index 00000000000..ce1d6bab536 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/merge_request_pipeline.png diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_new_comment_v13_11.png b/doc/user/project/merge_requests/reviews/img/mr_review_new_comment_v13_11.png Binary files differnew file mode 100644 index 00000000000..6b4899bf67f --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/mr_review_new_comment_v13_11.png diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_resolve.png b/doc/user/project/merge_requests/reviews/img/mr_review_resolve.png Binary files differnew file mode 100644 index 00000000000..ced33682459 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/mr_review_resolve.png diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_resolve2.png b/doc/user/project/merge_requests/reviews/img/mr_review_resolve2.png Binary files differnew file mode 100644 index 00000000000..2f0be3b6d06 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/mr_review_resolve2.png diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_start.png b/doc/user/project/merge_requests/reviews/img/mr_review_start.png Binary files differnew file mode 100644 index 00000000000..08b4c6bb82b --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/mr_review_start.png diff --git a/doc/user/project/merge_requests/reviews/img/mr_review_unresolve.png b/doc/user/project/merge_requests/reviews/img/mr_review_unresolve.png Binary files differnew file mode 100644 index 00000000000..4bef38f7808 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/mr_review_unresolve.png diff --git a/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview.png b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview.png Binary files differnew file mode 100644 index 00000000000..476c50b9098 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-preview.png diff --git a/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-syntax.png b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-syntax.png Binary files differnew file mode 100644 index 00000000000..80424d1f056 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/multi-line-suggestion-syntax.png diff --git a/doc/user/project/merge_requests/reviews/img/multiline-comment-saved.png b/doc/user/project/merge_requests/reviews/img/multiline-comment-saved.png Binary files differnew file mode 100644 index 00000000000..cceab36e62b --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/multiline-comment-saved.png diff --git a/doc/user/project/merge_requests/reviews/img/pending_review_comment.png b/doc/user/project/merge_requests/reviews/img/pending_review_comment.png Binary files differnew file mode 100644 index 00000000000..70a66b3f4f0 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/pending_review_comment.png diff --git a/doc/user/project/merge_requests/reviews/img/project_merge_requests_list_view_v13_5.png b/doc/user/project/merge_requests/reviews/img/project_merge_requests_list_view_v13_5.png Binary files differnew file mode 100644 index 00000000000..625d47b1142 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/project_merge_requests_list_view_v13_5.png diff --git a/doc/user/project/merge_requests/reviews/img/remove_suggestion_from_batch_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/remove_suggestion_from_batch_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..fa8331effdb --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/remove_suggestion_from_batch_v13_1.jpg diff --git a/doc/user/project/merge_requests/reviews/img/suggestion_button_v13_9.png b/doc/user/project/merge_requests/reviews/img/suggestion_button_v13_9.png Binary files differnew file mode 100644 index 00000000000..58e0508d8cf --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggestion_button_v13_9.png diff --git a/doc/user/project/merge_requests/reviews/img/suggestion_code_block_editor_v12_8.png b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_editor_v12_8.png Binary files differnew file mode 100644 index 00000000000..927b4f812a5 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_editor_v12_8.png diff --git a/doc/user/project/merge_requests/reviews/img/suggestion_code_block_output_v12_8.png b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_output_v12_8.png Binary files differnew file mode 100644 index 00000000000..6f29107146d --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggestion_code_block_output_v12_8.png diff --git a/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v13_1.jpg b/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v13_1.jpg Binary files differnew file mode 100644 index 00000000000..a4c9df0ebb9 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/img/suggestions_custom_commit_messages_v13_1.jpg diff --git a/doc/user/project/merge_requests/reviews/index.md b/doc/user/project/merge_requests/reviews/index.md new file mode 100644 index 00000000000..e98a230c0de --- /dev/null +++ b/doc/user/project/merge_requests/reviews/index.md @@ -0,0 +1,417 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: index, reference +--- + +# Review and manage merge requests **(FREE)** + +[Merge requests](../index.md) are the primary method of making changes to files in a +GitLab project. [Create and submit a merge request](../creating_merge_requests.md) +to propose changes. Your team makes [suggestions](suggestions.md) and leaves +[comments](../../../discussions/index.md). When your work is reviewed, your team +members can choose to accept or reject it. + +## View merge requests + +You can view merge requests for a specific project, or for all projects in a group: + +- **Specific project**: Go to your project and select **Merge requests**. +- **All projects in a group**: Go to your group and select **Merge requests**. + If your group contains subgroups, this view also displays merge requests from the subgroup projects. + GitLab displays a count of open merge requests in the left sidebar, but + [caches the value](#cached-merge-request-count) for groups with a large number of + open merge requests. + +GitLab displays open merge requests, with tabs to filter the list by open and closed status: + + + +You can [search and filter](../../../search/index.md#filtering-issue-and-merge-request-lists), +the results, or select a merge request to begin a review. + +## Bulk edit merge requests at the project level + +Users with permission level of [Developer or higher](../../../permissions.md) can manage merge requests. + +When bulk editing merge requests in a project, you can edit the following attributes: + +- Status (open/closed) +- Assignee +- Milestone +- Labels +- Subscriptions + +To update multiple project merge requests at the same time: + +1. In a project, go to **Merge requests**. +1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with + editable fields. +1. Select the checkboxes next to each merge request you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. + +## Bulk edit merge requests at the group level + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/12719) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2. + +Users with permission level of [Developer or higher](../../../permissions.md) can manage merge requests. + +When bulk editing merge requests in a group, you can edit the following attributes: + +- Milestone +- Labels + +To update multiple group merge requests at the same time: + +1. In a group, go to **Merge requests**. +1. Click **Edit merge requests**. A sidebar on the right-hand side of your screen appears with + editable fields. +1. Select the checkboxes next to each merge request you want to edit. +1. Select the appropriate fields and their values from the sidebar. +1. Click **Update all**. + +## Review a merge request + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4213) in GitLab Premium 11.4. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/28154) to GitLab Free in 13.1. + +When you review a merge request, you can create comments that are visible only +to you. When you're ready, you can publish them together in a single action. +To start your review: + +1. Go to the merge request you want to review, and select the **Changes** tab. + To learn more about navigating the diffs displayed in this tab, read + [Changes tab in merge requests](../changes.md). +1. Select a line of code. In GitLab version 13.2 and later, you can [highlight a set of lines](#comment-on-multiple-lines). +1. Write your first comment, and select **Start a review** below your comment: +  +1. Continue adding comments to lines of code, and select the appropriate button after + you write a comment: + - **Add to review**: Keep this comment private and add to the current review. + These review comments are marked **Pending** and are visible only to you. + - **Add comment now**: Submits the specific comment as a regular comment instead of as part of the review. +1. (Optional) You can use [quick actions](../../quick_actions.md) inside review comments. + The comment shows the actions to perform after publication, but does not perform them + until you submit your review. +1. When your review is complete, you can [submit the review](#submit-a-review). Your comments + are now visible, and any quick actions included your comments are performed. + +### Submit a review + +You can submit your completed review in multiple ways: + +- Use the `/submit_review` [quick action](../../quick_actions.md) in the text of a non-review comment. +- When creating a review comment, select **Submit review**. +- Scroll to the bottom of the screen and select **Submit review**. + +When you submit your review, GitLab: + +- Publishes the comments in your review. +- Sends a single email to every notifiable user of the merge request, with your + review comments attached. Replying to this email creates a new comment on the merge request. +- Perform any quick actions you added to your review comments. + +### Resolving/Unresolving threads + +Review comments can also resolve or unresolve [resolvable threads](../../../discussions/index.md#resolvable-comments-and-threads). +When replying to a comment, a checkbox is displayed to resolve or unresolve +the thread after publication. + + + +If a particular pending comment resolves or unresolves the thread, this is shown on the pending +comment itself. + + + + + +### Adding a new comment + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/8225) in GitLab 13.10. + +If you have a review in progress, you will be presented with the option to **Add to review**: + + + +## Semi-linear history merge requests + +A merge commit is created for every merge, but the branch is only merged if +a fast-forward merge is possible. This ensures that if the merge request build +succeeded, the target branch build also succeeds after the merge. + +1. Go to your project and select **Settings > General**. +1. Expand **Merge requests**. +1. In the **Merge method** section, select **Merge commit with semi-linear history**. +1. Select **Save changes**. + +## Perform inline code reviews + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/13950) in GitLab 11.5. + +In a merge request, you can leave comments in any part of the file being changed. +In the merge request Diff UI, you can: + +- **Comment on a single line**: Select the **{comment}** **comment** icon in the + gutter to expand the diff lines and display a comment box. +- [**Comment on multiple lines**](#comment-on-multiple-lines). + +### Comment on multiple lines + +> - [Introduced](https://gitlab.com/gitlab-org/ux-research/-/issues/870) in GitLab 13.2. +> - [Added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/49875) click-and-drag features in GitLab 13.8. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/299121) in GitLab 13.9. + +When commenting on a diff, you can select which lines of code your comment refers +to by either: + + + +- Dragging the **{comment}** **comment** icon in the gutter to highlight + lines in the diff. GitLab expands the diff lines and displays a comment box. +- After starting a comment by selecting the **{comment}** **comment** icon in the + gutter, select the first line number your comment refers to in the **Commenting on lines** + select box. New comments default to single-line comments, unless you select + a different starting line. + +Multiline comments display the comment's line numbers above the body of the comment: + + + +## Pipeline status in merge requests widgets + +If you've set up [GitLab CI/CD](../../../../ci/README.md) in your project, +you can see: + +- Both pre-merge and post-merge pipelines and the environment information if any. +- Which deployments are in progress. + +If an application is successfully deployed to an +[environment](../../../../ci/environments/index.md), the deployed environment and the link to the +Review App are both shown. + +NOTE: +When the pipeline fails in a merge request but it can still be merged, +the **Merge** button is colored red. + +### Post-merge pipeline status + +When a merge request is merged, you can see the post-merge pipeline status of +the branch the merge request was merged into. For example, when a merge request +is merged into the [default branch](../../repository/branches/default.md) and then triggers a deployment to the staging +environment. + +Ongoing deployments are shown, and the state (deploying or deployed) +for environments. If it's the first time the branch is deployed, the link +returns a `404` error until done. During the deployment, the stop button is +disabled. If the pipeline fails to deploy, the deployment information is hidden. + + + +For more information, [read about pipelines](../../../../ci/pipelines/index.md). + +### Merge when pipeline succeeds (MWPS) + +Set a merge request that looks ready to merge to +[merge automatically when CI pipeline succeeds](../merge_when_pipeline_succeeds.md). + +### Live preview with Review Apps + +If you configured [Review Apps](https://about.gitlab.com/stages-devops-lifecycle/review-apps/) for your project, +you can preview the changes submitted to a feature branch through a merge request +on a per-branch basis. You don't need to checkout the branch, install, and preview locally. +All your changes are available to preview by anyone with the Review Apps link. + +With GitLab [Route Maps](../../../../ci/review_apps/index.md#route-maps) set, the +merge request widget takes you directly to the pages changed, making it easier and +faster to preview proposed modifications. + +[Read more about Review Apps](../../../../ci/review_apps/index.md). + +## Associated features + +These features are associated with merge requests: + +- [Bulk editing merge requests](../../../project/bulk_editing.md): + Update the attributes of multiple merge requests simultaneously. +- [Cherry-pick changes](../cherry_pick_changes.md): + Cherry-pick any commit in the UI by selecting the **Cherry-pick** button in a merged merge requests or a commit. +- [Fast-forward merge requests](../fast_forward_merge.md): + For a linear Git history and a way to accept merge requests without creating merge commits +- [Find the merge request that introduced a change](../versions.md): + When viewing the commit details page, GitLab links to the merge request(s) containing that commit. +- [Merge requests versions](../versions.md): + Select and compare the different versions of merge request diffs +- [Resolve conflicts](../resolve_conflicts.md): + GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. +- [Revert changes](../revert_changes.md): + Revert changes from any commit from a merge request. + +## Troubleshooting + +Sometimes things don't go as expected in a merge request. Here are some +troubleshooting steps. + +### Merge request cannot retrieve the pipeline status + +This can occur if Sidekiq doesn't pick up the changes fast enough. + +#### Sidekiq + +Sidekiq didn't process the CI state change fast enough. Please wait a few +seconds and the status should update automatically. + +#### Bug + +Merge request pipeline statuses can't be retrieved when the following occurs: + +1. A merge request is created +1. The merge request is closed +1. Changes are made in the project +1. The merge request is reopened + +To enable the pipeline status to be properly retrieved, close and reopen the +merge request again. + +## Tips + +Here are some tips to help you be more efficient with merge requests in +the command line. + +### Copy the branch name for local checkout + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/23767) in GitLab 13.4. + +The merge request sidebar contains the branch reference for the source branch +used to contribute changes for this merge request. + +To copy the branch reference into your clipboard, select the **Copy branch name** button +(**{copy-to-clipboard}**) in the right sidebar. Use it to checkout the branch locally +from the command line by running `git checkout <branch-name>`. + +### Checkout merge requests locally through the `head` ref + +A merge request contains all the history from a repository, plus the additional +commits added to the branch associated with the merge request. Here's a few +ways to check out a merge request locally. + +You can check out a merge request locally even if the source +project is a fork (even a private fork) of the target project. + +This relies on the merge request `head` ref (`refs/merge-requests/:iid/head`) +that is available for each merge request. It allows checking out a merge +request by using its ID instead of its branch. + +[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/223156) in GitLab +13.4, 14 days after a merge request gets closed or merged, the merge request +`head` ref is deleted. This means that the merge request isn't available +for local checkout from the merge request `head` ref anymore. The merge request +can still be re-opened. If the merge request's branch +exists, you can still check out the branch, as it isn't affected. + +#### Checkout locally by adding a Git alias + +Add the following alias to your `~/.gitconfig`: + +```plaintext +[alias] + mr = !sh -c 'git fetch $1 merge-requests/$2/head:mr-$1-$2 && git checkout mr-$1-$2' - +``` + +Now you can check out a particular merge request from any repository and any +remote. For example, to check out the merge request with ID 5 as shown in GitLab +from the `origin` remote, do: + +```shell +git mr origin 5 +``` + +This fetches the merge request into a local `mr-origin-5` branch and check +it out. + +#### Checkout locally by modifying `.git/config` for a given repository + +Locate the section for your GitLab remote in the `.git/config` file. It looks +like this: + +```plaintext +[remote "origin"] + url = https://gitlab.com/gitlab-org/gitlab-foss.git + fetch = +refs/heads/*:refs/remotes/origin/* +``` + +You can open the file with: + +```shell +git config -e +``` + +Now add the following line to the above section: + +```plaintext +fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* +``` + +In the end, it should look like this: + +```plaintext +[remote "origin"] + url = https://gitlab.com/gitlab-org/gitlab-foss.git + fetch = +refs/heads/*:refs/remotes/origin/* + fetch = +refs/merge-requests/*/head:refs/remotes/origin/merge-requests/* +``` + +Now you can fetch all the merge requests: + +```shell +git fetch origin + +... +From https://gitlab.com/gitlab-org/gitlab-foss.git + * [new ref] refs/merge-requests/1/head -> origin/merge-requests/1 + * [new ref] refs/merge-requests/2/head -> origin/merge-requests/2 +... +``` + +And to check out a particular merge request: + +```shell +git checkout origin/merge-requests/1 +``` + +All the above can be done with the [`git-mr`](https://gitlab.com/glensc/git-mr) script. + +## Cached merge request count + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299542) in GitLab 13.11. +> - It's [deployed behind a feature flag](../../../feature_flags.md), enabled by default. +> - It's enabled on GitLab.com. +> - It's recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-cached-merge-request-count). + +WARNING: +This feature might not be available to you. Refer to the previous **version history** note for details. + +In a group, the sidebar displays the total count of open merge requests. This value is cached if it's greater than +than 1000. The cached value is rounded to thousands (or millions) and updated every 24 hours. + +### Enable or disable cached merge request count **(FREE SELF)** + +Cached merge request count in the left sidebar is under development but ready for production use. It is +deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../../../administration/feature_flags.md) +can disable it. + +To disable it: + +```ruby +Feature.disable(:cached_sidebar_merge_requests_count) +``` + +To enable it: + +```ruby +Feature.enable(:cached_sidebar_merge_requests_count) +``` diff --git a/doc/user/project/merge_requests/reviews/suggestions.md b/doc/user/project/merge_requests/reviews/suggestions.md new file mode 100644 index 00000000000..0c8dd384b88 --- /dev/null +++ b/doc/user/project/merge_requests/reviews/suggestions.md @@ -0,0 +1,142 @@ +--- +stage: Create +group: Code Review +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +type: index, reference +--- + +# Suggest changes **(FREE)** + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/18008) in GitLab 11.6. +> - Custom commit messages for suggestions was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9 behind a [feature flag](../../../feature_flags.md), 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)) is able to apply these suggestions with a click, +which generates a commit in the merge request authored by the user that applied them. + +1. Choose a line of code to be changed, add a new comment, then select + the **Insert suggestion** icon in the toolbar: + +  + +1. In the comment, add your suggestion to the pre-populated code block: + +  + +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 suggestion in the comment can be applied by the merge request author + directly from the merge request: + +  + +1. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25381) in GitLab 13.9, + you can opt to add a custom commit message to describe your change. If you don't + specify it, the default commit message is used. It is not supported for [batch suggestions](#batch-suggestions). + +  + +After the author applies a suggestion, it's marked with the **Applied** label, +the thread is automatically resolved, and GitLab creates a new commit +and pushes the suggested change directly into the codebase in the merge request's +branch. [Developer permission](../../../permissions.md) is required to do so. + +## Multi-line suggestions + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/53310) in GitLab 11.10. + +Reviewers can also suggest changes to multiple lines with a single suggestion +within merge request diff threads 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. + + + +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. + + + +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 + +If you need to make a suggestion that involves a +[fenced code block](../../../markdown.md#code-spans-and-blocks), wrap your suggestion in four backticks +instead of the usual three. + + + + + +## 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: `Apply %{suggestions_count} suggestion(s) to %{files_count} 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)** + +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: + + + +You can also use following variables besides static text: + +| Variable | Description | Output example | +|------------------------|-------------|----------------| +| `%{branch_name}` | The name of the branch the suggestion(s) was(were) applied to. | `my-feature-branch` | +| `%{files_count}` | The number of file(s) to which suggestion(s) was(were) applied.| **2** | +| `%{file_paths}` | The path(s) of the file(s) suggestion(s) was(were) applied to. 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** | +| `%{username}` | The username of the user applying suggestion(s). | `user_1` | +| `%{user_full_name}` | The full name of the user applying suggestion(s). | **User 1** | + +For example, to customize the commit message to output +**Addresses user_1's review**, set the custom text to +`Addresses %{username}'s review`. + +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](https://about.gitlab.com/handbook/product/gitlab-the-product/#alpha) behind a feature flag, disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/227799) in GitLab 13.2. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320755) in GitLab 13.11. + +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**: + +  + +1. Having added all the suggestions to your liking, when ready, select **Apply suggestions**: + +  + +WARNING: +Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions. |
