Suggest changes

Version history

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) can apply these suggestions. This action generates a commit in the merge request, authored by the user that suggested the changes.

  1. Choose a line of code to be changed, add a new comment, then select the Insert suggestion icon in the toolbar:

    Add a new comment

  2. In the comment, add your suggestion to the pre-populated code block:

    Add a suggestion into a code block tagged properly

  3. Select either Start a review or Add to review to add your comment to a review, 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:

    Apply suggestions

  4. 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.

    Custom commit

After the author applies a suggestion:

  1. The suggestion is marked as Applied.
  2. The thread is resolved.
  3. GitLab creates a new commit with the changes.
  4. If the user has the Developer role, GitLab pushes the suggested change directly into the codebase in the merge request’s branch.

Multi-line suggestions

Changed in GitLab 13.11: suggestions in multi-line comments also become multi-line.

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.

Multi-line suggestion syntax

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.

Multi-line suggestion preview

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

To add a suggestion that includes a fenced code block, wrap your suggestion in four backticks instead of three:

git config --global receive.advertisepushoptions true

Output of a comment with a suggestion with a fenced code block

Configure the commit message for applied suggestions

Introduced 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:

Custom commit message for applied suggestions

You can also use following variables besides static text:

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
%{file_paths} The paths of the file to which suggestions were applied. Paths are separated by commas. docs/, docs/
%{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 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 %{username}'s review.

For merge requests created from forks, GitLab uses the template defined in target project.

Custom commit messages for each applied suggestion is introduced by #25381.

Batch suggestions

Version history

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:

    A code change suggestion displayed, with the add-suggestion option highlighted.

  2. Add as many additional suggestions to the batch as you wish:

    A code change suggestion displayed, with the add-more suggestion option highlighted.

  3. To remove suggestions, select Remove from batch:

    A code change suggestion displayed, with the option to remove that suggestion from its batch highlighted.

  4. Having added all the suggestions to your liking, when ready, select Apply suggestions. You can optionally specify a custom commit message for batch suggestions (GitLab 14.4 and later) to describe your change. If you don’t specify it, the default commit message is used.

    A code change suggestion displayed, with the option to apply the batch of suggestions highlighted.

Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions.