Skip to content

G
gitlab-ce
Commit 0abfd19e authored by Amy Qualls's avatar Amy Qualls
Browse files
Options

Merge branch '327754-aqualls-make-subdir' into 'master' 

Start cleanup of "threads" page

See merge request gitlab-org/gitlab!60870
parents 34099496 a5a40ede
Hide whitespace changes
Inline Side-by-side
Showing with 613 additions and 599 deletions
app/serializers/merge_request_widget_entity.rb
View file @ 0abfd19e
......@@ -52,7 +52,7 @@ class MergeRequestWidgetEntity < Grape::Entity
end
expose :reviewing_and_managing_merge_requests_docs_path do |merge_request|
help_page_path('user/project/merge_requests/reviewing_and_managing_merge_requests.md', anchor: "checkout-merge-requests-locally-through-the-head-ref")
help_page_path('user/project/merge_requests/reviews/index.md', anchor: "checkout-merge-requests-locally-through-the-head-ref")
end
expose :merge_request_pipelines_docs_path do |merge_request|
......
app/views/projects/_merge_request_merge_suggestions_settings.html.haml
View file @ 0abfd19e
......@@ -3,7 +3,7 @@
.form-group
%b= s_('ProjectSettings|Merge suggestions')
%p.text-secondary
- configure_the_commit_message_for_applied_suggestions_help_link_url = help_page_path('user/discussions/index.md', anchor: 'configure-the-commit-message-for-applied-suggestions')
- configure_the_commit_message_for_applied_suggestions_help_link_url = help_page_path('user/project/merge_requests/reviews/suggestions.md', anchor: 'configure-the-commit-message-for-applied-suggestions')
- configure_the_commit_message_for_applied_suggestions_help_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: configure_the_commit_message_for_applied_suggestions_help_link_url }
= s_('ProjectSettings|The commit message used when applying merge request suggestions. %{link_start}Learn more about suggestions.%{link_end}').html_safe % { link_start: configure_the_commit_message_for_applied_suggestions_help_link_start, link_end: '</a>'.html_safe }
.mb-2
......
app/views/projects/merge_requests/_widget.html.haml
View file @ 0abfd19e
......@@ -5,7 +5,7 @@
window.gl.mrWidgetData.squash_before_merge_help_path = '#{help_page_path("user/project/merge_requests/squash_and_merge")}';
window.gl.mrWidgetData.ci_troubleshooting_docs_path = '#{help_page_path('ci/troubleshooting.md')}';
window.gl.mrWidgetData.mr_troubleshooting_docs_path = '#{help_page_path('user/project/merge_requests/reviewing_and_managing_merge_requests.md', anchor: 'troubleshooting')}';
window.gl.mrWidgetData.mr_troubleshooting_docs_path = '#{help_page_path('user/project/merge_requests/reviews/index.md', anchor: 'troubleshooting')}';
window.gl.mrWidgetData.pipeline_must_succeed_docs_path = '#{help_page_path('user/project/merge_requests/merge_when_pipeline_succeeds.md', anchor: 'only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds')}';
window.gl.mrWidgetData.security_approvals_help_page_path = '#{help_page_path('user/application_security/index.md', anchor: 'security-approvals-in-merge-requests')}';
window.gl.mrWidgetData.license_compliance_docs_path = '#{help_page_path('user/compliance/license_compliance/index.md', anchor: 'policies')}';
......
app/views/projects/merge_requests/show.html.haml
View file @ 0abfd19e
......@@ -5,7 +5,7 @@
- page_title "#{@merge_request.title} (#{@merge_request.to_reference})", _("Merge requests")
- page_description @merge_request.description_html
- page_card_attributes @merge_request.card_attributes
- suggest_changes_help_path = help_page_path('user/discussions/index.md', anchor: 'suggest-changes')
- suggest_changes_help_path = help_page_path('user/project/merge_requests/reviews/suggestions.md')
- number_of_pipelines = @pipelines.size
- mr_action = j(params[:tab].presence || 'show')
- add_page_specific_style 'page_bundles/merge_requests'
......
doc/development/code_review.md
View file @ 0abfd19e
......@@ -387,7 +387,7 @@ If a merge request is fundamentally ready, but needs only trivial fixes (such as
typos), consider demonstrating a [bias for
action](https://about.gitlab.com/handbook/values/#bias-for-action) by making
those changes directly without going back to the author. You can do this by
using the [suggest changes](../user/discussions/index.md#suggest-changes) feature to apply
using the [suggest changes](../user/project/merge_requests/reviews/suggestions.md) feature to apply
your own suggestions to the merge request. Note that:
- If the changes are not straightforward, please prefer allowing the author to make the change.
......
doc/user/admin_area/diff_limits.md
View file @ 0abfd19e
......@@ -9,7 +9,7 @@ type: reference
You can set a maximum size for display of diff files (patches).
For details about diff files, [View changes between files](../project/merge_requests/reviewing_and_managing_merge_requests.md#view-changes-between-file-versions).
For details about diff files, [View changes between files](../project/merge_requests/reviews/index.md#view-changes-between-file-versions).
## Maximum diff patch size
......
doc/user/discussions/index.md
View file @ 0abfd19e
......@@ -382,142 +382,6 @@ After you select one of the filters in a given issue or merge request, GitLab sa
your preference, so that it persists when you visit the same page again
from any device you're logged into.
## Suggest Changes
> - [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 click
on the **Insert suggestion** icon in the toolbar:
![Add a new comment](img/suggestion_button_v13_9.png)
1. In the comment, add your suggestion to the pre-populated code block:
![Add a suggestion into a code block tagged properly](img/make_suggestion_v13_9.png)
1. Click either **Start a review** or **Add to review** to add your comment to a [review](#merge-request-reviews), 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](img/apply_suggestion_v13_9.png)
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).
![Custom commit](img/custom_commit_v13_9.png)
After the author applies a Suggestion, it is marked with the **Applied** label,
the thread is automatically resolved, and GitLab creates a new commit
and push 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.
![Multi-line suggestion syntax](img/multi-line-suggestion-syntax.png)
In the example above, 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](img/multi-line-suggestion-preview.png)
NOTE:
Suggestions covering multiple lines are limited to 100 lines _above_ and 100
lines _below_ the commented diff line, allowing 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.
![A comment editor with a suggestion with a fenced code block](img/suggestion_code_block_editor_v12_8.png)
![Output of a comment with a suggestion with a fenced code block](img/suggestion_code_block_output_v12_8.png)
### 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:
![Custom commit message for applied Suggestions](img/suggestions_custom_commit_messages_v13_1.jpg)
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, click **Add suggestion to batch**:
![A code change suggestion displayed, with the button to add the suggestion to a batch highlighted.](img/add_first_suggestion_to_batch_v13_1.jpg "Add a suggestion to a batch")
1. Add as many additional suggestions to the batch as you wish:
![A code change suggestion displayed, with the button to add an additional suggestion to a batch highlighted.](img/add_another_suggestion_to_batch_v13_1.jpg "Add another suggestion to a batch")
1. To remove suggestions, click **Remove from batch**:
![A code change suggestion displayed, with the button to remove that suggestion from its batch highlighted.](img/remove_suggestion_from_batch_v13_1.jpg "Remove a suggestion from a batch")
1. Having added all the suggestions to your liking, when ready, click **Apply suggestions**:
![A code change suggestion displayed, with the button to apply the batch of suggestions highlighted.](img/apply_batch_of_suggestions_v13_1.jpg "Apply a batch of suggestions")
WARNING:
Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions.
## Start a thread by replying to a standard comment
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30299) in GitLab 11.9
......
doc/user/project/merge_requests/creating_merge_requests.md
View file @ 0abfd19e
......@@ -249,4 +249,4 @@ branch already exists, the patches are applied on top of it.
## Reviewing and managing Merge Requests
Once you have submitted a merge request, it can be [reviewed and managed](reviewing_and_managing_merge_requests.md) through GitLab.
Once you have submitted a merge request, it can be [reviewed and managed](reviews/index.md) through GitLab.
doc/user/project/merge_requests/getting_started.md
View file @ 0abfd19e
......@@ -65,24 +65,24 @@ request's page at the top-right side:
After you have created the merge request, you can also:
- [Discuss](../../discussions/index.md) your implementation with your team in the merge request thread.
- [Perform inline code reviews](reviewing_and_managing_merge_requests.md#perform-inline-code-reviews).
- [Perform inline code reviews](reviews/index.md#perform-inline-code-reviews).
- Add [merge request dependencies](merge_request_dependencies.md) to restrict it to be merged only when other merge requests have been merged. **(PREMIUM)**
- Preview continuous integration [pipelines on the merge request widget](reviewing_and_managing_merge_requests.md#pipeline-status-in-merge-requests-widgets).
- Preview how your changes look directly on your deployed application with [Review Apps](reviewing_and_managing_merge_requests.md#live-preview-with-review-apps).
- Preview continuous integration [pipelines on the merge request widget](reviews/index.md#pipeline-status-in-merge-requests-widgets).
- Preview how your changes look directly on your deployed application with [Review Apps](reviews/index.md#live-preview-with-review-apps).
- [Allow collaboration on merge requests across forks](allow_collaboration.md).
- Perform a [Review](../../discussions/index.md#merge-request-reviews) to create multiple comments on a diff and publish them when you're ready.
- Add [code suggestions](../../discussions/index.md#suggest-changes) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI.
- Add [code suggestions](reviews/suggestions.md) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI.
- Add a time estimation and the time spent with that merge request with [Time Tracking](../time_tracking.md#time-tracking).
Many of these can be set when pushing changes from the command line,
with [Git push options](../push_options.md).
See also other [features associated to merge requests](reviewing_and_managing_merge_requests.md#associated-features).
See also other [features associated to merge requests](reviews/index.md#associated-features).
### Assignee
Choose an assignee to designate someone as the person responsible
for the first [review of the merge request](reviewing_and_managing_merge_requests.md).
for the first [review of the merge request](reviews/index.md).
Open the drop down box to search for the user you wish to assign,
and the merge request is added to their
[assigned merge request list](../../search/index.md#issues-and-merge-requests).
......
doc/user/project/merge_requests/index.md
View file @ 0abfd19e
......@@ -72,6 +72,6 @@ Feature.disable(:mr_tabs_position)
## Related topics
- [Create a merge request](creating_merge_requests.md)
- [Review and manage merge requests](reviewing_and_managing_merge_requests.md)
- [Review and manage merge requests](reviews/index.md)
- [Authorization for merge requests](authorization_for_merge_requests.md)
- [Testing and reports](testing_and_reports_in_merge_requests.md)
doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md
View file @ 0abfd19e
---
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
redirect_to: 'reviews/index.md'
---
# Reviewing and managing merge requests **(FREE)**
This document was moved to [another location](reviews/index.md).
Merge requests are the primary method of making changes to files in a GitLab project.
Changes are proposed by [creating and submitting a merge request](creating_merge_requests.md),
which is then reviewed, and accepted (or rejected).
## View project merge requests
View all the merge requests in a project by navigating to **Project > Merge Requests**.
When you access your project's merge requests, GitLab displays them in a list.
Use the tabs to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists).
![Project merge requests list view](img/project_merge_requests_list_view_v13_5.png)
## View merge requests for all projects in a group
View merge requests in all projects in the group, including all projects of all descendant subgroups of the group. Navigate to **Group > Merge Requests** to view these merge requests. This view also has the open and closed merge requests tabs.
You can [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists) from here.
![Group Issues list view](img/group_merge_requests_list_view.png)
## 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. Check the **version history** note above for details.
In a group, the sidebar displays the total count of open merge requests and this value is cached if higher
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)
```
## 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.
Navigate to a project's settings, select the **Merge commit with semi-linear history**
option under **Merge Requests: Merge method** and save your changes.
## View changes between file versions
The **Changes** tab, below the main merge request details and next to the discussion tab,
shows the changes to files between branches or commits. This view of changes to a
file is also known as a **diff**. By default, the diff view compares the file in the
merge request branch and the file in the target branch.
The diff view includes the following:
- The file's name and path.
- The number of lines added and deleted.
- Buttons for the following options:
- Toggle comments for this file; useful for inline reviews.
- Edit the file in the merge request's branch.
- Show full file, in case you want to look at the changes in context with the rest of the file.
- View file at the current commit.
- Preview the changes with [Review Apps](../../../ci/review_apps/index.md).
- The changed lines, with the specific changes highlighted.
![Example screenshot of a source code diff](img/merge_request_diff_v12_2.png)
### Merge request diff file navigation
When reviewing changes in the **Changes** tab the diff can be navigated using
the file tree or file list. As you scroll through large diffs with many
changes, you can quickly jump to any changed file using the file tree or file
list.
![Merge request diff file navigation](img/merge_request_diff_file_navigation.png)
### Collapsed files in the Changes view
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232820) in GitLab 13.4.
When you review changes in the **Changes** tab, files with a large number of changes are collapsed
to improve performance. When files are collapsed, a warning appears at the top of the changes.
Click **Expand file** on any file to view the changes for that file.
### File-by-file diff navigation
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229848) in GitLab 13.7.
For larger merge requests, consider reviewing one file at a time. To enable this feature:
1. In the top-right corner, select your avatar.
1. Select **Preferences**.
1. Scroll to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**.
1. Select **Save changes**.
After you enable this setting, GitLab displays only one file at a time in the **Changes** tab when you review merge requests. You can click **Prev** and **Next** to view other changed files.
![File-by-file diff navigation](img/file_by_file_v13_2.png)
In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) and later, if you want to change
this behavior, you can do so from your **User preferences** (as explained above) or directly in a
merge request:
1. Go to the merge request's **Changes** tab.
1. Select the cog icon (**{settings}**) to reveal the merge request's settings dropdown.
1. Select or deselect the checkbox **Show one file at a time** to change the setting accordingly.
This change overrides the choice you made in your user preferences and persists until you clear your
browser's cookies or change this behavior again.
### Merge requests commit navigation
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0.
To seamlessly navigate among commits in a merge request:
1. Select the **Commits** tab.
1. Select a commit to open it in the single-commit view.
1. Navigate through the commits by either:
- Selecting **Prev** and **Next** buttons below the tab buttons.
- Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts.
![Merge requests commit navigation](img/commit_nav_v13_11.png)
### Incrementally expand merge request diffs
By default, the diff shows only the parts of a file which are changed.
To view more unchanged lines above or below a change click on the
**Expand up** or **Expand down** icons. You can also click on **Show unchanged lines**
to expand the entire file.
![Incrementally expand merge request diffs](img/incrementally_expand_merge_request_diffs_v12_2.png)
In GitLab [versions 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/205401), when viewing a
merge request's **Changes** tab, if a certain file was only renamed, you can expand it to see the
entire content by clicking **Show file contents**.
### Ignore whitespace changes in Merge Request diff view
If you click the **Hide whitespace changes** button, you can see the diff
without whitespace changes (if there are any). This is also working when on a
specific commit page.
![MR diff](img/merge_request_diff.png)
NOTE:
You can append `?w=1` while on the diffs page of a merge request to ignore any
whitespace changes.
## Mark files as viewed
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9.
> - It's deployed behind a feature flag, 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-file-views). **(FREE SELF)**
When reviewing a merge request with many files multiple times, it may be useful to the reviewer
to focus on new changes and ignore the files that they have already reviewed and don't want to
see anymore unless they are changed again.
To mark a file as viewed:
1. Go to the merge request's **Diffs** tab.
1. On the right-top of the file, locate the **Viewed** checkbox.
1. Check it to mark the file as viewed.
Once checked, the file remains marked for that reviewer unless there are newly introduced
changes to its content or the checkbox is unchecked.
### Enable or disable file views **(FREE SELF)**
The file view feature 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 opt to enable it for your instance.
To enable it:
```ruby
Feature.enable(:local_file_reviews)
```
To disable it:
```ruby
Feature.disable(:local_file_reviews)
```
## 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**: Click the **{comment}** **comment** icon in the
gutter to expand the diff lines and display a comment box.
- [**Comment on multiple lines**](#commenting-on-multiple-lines).
### Commenting 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:
![Comment on any diff file line](img/comment-on-any-diff-line_v13_10.png)
- Clicking and 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 clicking 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:
![Multiline comment selection displayed above comment](img/multiline-comment-saved.png)
## 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.
![Merge request pipeline](img/merge_request_pipeline.png)
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 clicking 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, click the **Copy branch name** button
(**{copy-to-clipboard}**) in the right sidebar. Use it to checkout the branch locally
via 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 checkout a merge request locally.
You can checkout 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 via 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 is not available
for local checkout via 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.
<!-- This redirect file can be deleted after <2021-08-03>. -->
<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page -->
doc/user/project/merge_requests/reviews/index.md 0 → 100644
View file @ 0abfd19e
---
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
---
# Reviewing and managing merge requests **(FREE)**
Merge requests are the primary method of making changes to files in a GitLab project.
Changes are proposed by [creating and submitting a merge request](../creating_merge_requests.md),
which is then reviewed, and accepted (or rejected).
## View project merge requests
View all the merge requests in a project by navigating to **Project > Merge Requests**.
When you access your project's merge requests, GitLab displays them in a list.
Use the tabs to quickly filter by open and closed. You can also [search and filter the results](../../../search/index.md#filtering-issue-and-merge-request-lists).
![Project merge requests list view](img/project_merge_requests_list_view_v13_5.png)
## View merge requests for all projects in a group
View merge requests in all projects in the group, including all projects of all descendant subgroups of the group. Navigate to **Group > Merge Requests** to view these merge requests. This view also has the open and closed merge requests tabs.
You can [search and filter the results](../../../search/index.md#filtering-issue-and-merge-request-lists) from here.
![Group Issues list view](img/group_merge_requests_list_view.png)
## 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. Check the **version history** note above for details.
In a group, the sidebar displays the total count of open merge requests and this value is cached if higher
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)
```
## 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.
Navigate to a project's settings, select the **Merge commit with semi-linear history**
option under **Merge Requests: Merge method** and save your changes.
## View changes between file versions
The **Changes** tab, below the main merge request details and next to the discussion tab,
shows the changes to files between branches or commits. This view of changes to a
file is also known as a **diff**. By default, the diff view compares the file in the
merge request branch and the file in the target branch.
The diff view includes the following:
- The file's name and path.
- The number of lines added and deleted.
- Buttons for the following options:
- Toggle comments for this file; useful for inline reviews.
- Edit the file in the merge request's branch.
- Show full file, in case you want to look at the changes in context with the rest of the file.
- View file at the current commit.
- Preview the changes with [Review Apps](../../../../ci/review_apps/index.md).
- The changed lines, with the specific changes highlighted.
![Example screenshot of a source code diff](img/merge_request_diff_v12_2.png)
### Merge request diff file navigation
When reviewing changes in the **Changes** tab the diff can be navigated using
the file tree or file list. As you scroll through large diffs with many
changes, you can quickly jump to any changed file using the file tree or file
list.
![Merge request diff file navigation](img/merge_request_diff_file_navigation.png)
### Collapsed files in the Changes view
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/232820) in GitLab 13.4.
When you review changes in the **Changes** tab, files with a large number of changes are collapsed
to improve performance. When files are collapsed, a warning appears at the top of the changes.
Click **Expand file** on any file to view the changes for that file.
### File-by-file diff navigation
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/222790) in GitLab 13.2.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229848) in GitLab 13.7.
For larger merge requests, consider reviewing one file at a time. To enable this feature:
1. In the top-right corner, select your avatar.
1. Select **Preferences**.
1. Scroll to the **Behavior** section and select **Show one file at a time on merge request's Changes tab**.
1. Select **Save changes**.
After you enable this setting, GitLab displays only one file at a time in the **Changes** tab when you review merge requests. You can click **Prev** and **Next** to view other changed files.
![File-by-file diff navigation](img/file_by_file_v13_2.png)
In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/233898) and later, if you want to change
this behavior, you can do so from your **User preferences** (as explained above) or directly in a
merge request:
1. Go to the merge request's **Changes** tab.
1. Select the cog icon (**{settings}**) to reveal the merge request's settings dropdown.
1. Select or deselect the checkbox **Show one file at a time** to change the setting accordingly.
This change overrides the choice you made in your user preferences and persists until you clear your
browser's cookies or change this behavior again.
### Merge requests commit navigation
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/18140) in GitLab 13.0.
To seamlessly navigate among commits in a merge request:
1. Select the **Commits** tab.
1. Select a commit to open it in the single-commit view.
1. Navigate through the commits by either:
- Selecting **Prev** and **Next** buttons below the tab buttons.
- Using the <kbd>X</kbd> and <kbd>C</kbd> keyboard shortcuts.
![Merge requests commit navigation](img/commit_nav_v13_11.png)
### Incrementally expand merge request diffs
By default, the diff shows only the parts of a file which are changed.
To view more unchanged lines above or below a change click on the
**Expand up** or **Expand down** icons. You can also click on **Show unchanged lines**
to expand the entire file.
![Incrementally expand merge request diffs](img/incrementally_expand_merge_request_diffs_v12_2.png)
In GitLab [versions 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/205401), when viewing a
merge request's **Changes** tab, if a certain file was only renamed, you can expand it to see the
entire content by clicking **Show file contents**.
### Ignore whitespace changes in Merge Request diff view
If you click the **Hide whitespace changes** button, you can see the diff
without whitespace changes (if there are any). This is also working when on a
specific commit page.
![MR diff](img/merge_request_diff.png)
NOTE:
You can append `?w=1` while on the diffs page of a merge request to ignore any
whitespace changes.
## Mark files as viewed
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/51513) in GitLab 13.9.
> - It's deployed behind a feature flag, 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-file-views). **(FREE SELF)**
When reviewing a merge request with many files multiple times, it may be useful to the reviewer
to focus on new changes and ignore the files that they have already reviewed and don't want to
see anymore unless they are changed again.
To mark a file as viewed:
1. Go to the merge request's **Diffs** tab.
1. On the right-top of the file, locate the **Viewed** checkbox.
1. Check it to mark the file as viewed.
Once checked, the file remains marked for that reviewer unless there are newly introduced
changes to its content or the checkbox is unchecked.
### Enable or disable file views **(FREE SELF)**
The file view feature 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 opt to enable it for your instance.
To enable it:
```ruby
Feature.enable(:local_file_reviews)
```
To disable it:
```ruby
Feature.disable(:local_file_reviews)
```
## 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**: Click the **{comment}** **comment** icon in the
gutter to expand the diff lines and display a comment box.
- [**Comment on multiple lines**](#commenting-on-multiple-lines).
### Commenting 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:
![Comment on any diff file line](img/comment-on-any-diff-line_v13_10.png)
- Clicking and 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 clicking 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:
![Multiline comment selection displayed above comment](img/multiline-comment-saved.png)
## 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.
![Merge request pipeline](img/merge_request_pipeline.png)
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 clicking 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, click the **Copy branch name** button
(**{copy-to-clipboard}**) in the right sidebar. Use it to checkout the branch locally
via 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 checkout a merge request locally.
You can checkout 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 via 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 is not available
for local checkout via 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.
doc/user/project/merge_requests/reviews/suggestions.md 0 → 100644
View file @ 0abfd19e
---
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
> - [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 click
on the **Insert suggestion** icon in the toolbar:
![Add a new comment](img/suggestion_button_v13_9.png)
1. In the comment, add your suggestion to the pre-populated code block:
![Add a suggestion into a code block tagged properly](img/make_suggestion_v13_9.png)
1. Click 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:
![Apply suggestions](img/apply_suggestion_v13_9.png)
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).
![Custom commit](img/custom_commit_v13_9.png)
After the author applies a Suggestion, it is marked with the **Applied** label,
the thread is automatically resolved, and GitLab creates a new commit
and push 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.
![Multi-line suggestion syntax](img/multi-line-suggestion-syntax.png)
In the example above, 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](img/multi-line-suggestion-preview.png)
NOTE:
Suggestions covering multiple lines are limited to 100 lines _above_ and 100
lines _below_ the commented diff line, allowing 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.
![A comment editor with a suggestion with a fenced code block](img/suggestion_code_block_editor_v12_8.png)
![Output of a comment with a suggestion with a fenced code block](img/suggestion_code_block_output_v12_8.png)
## 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:
![Custom commit message for applied Suggestions](img/suggestions_custom_commit_messages_v13_1.jpg)
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, click **Add suggestion to batch**:
![A code change suggestion displayed, with the button to add the suggestion to a batch highlighted.](img/add_first_suggestion_to_batch_v13_1.jpg "Add a suggestion to a batch")
1. Add as many additional suggestions to the batch as you wish:
![A code change suggestion displayed, with the button to add an additional suggestion to a batch highlighted.](img/add_another_suggestion_to_batch_v13_1.jpg "Add another suggestion to a batch")
1. To remove suggestions, click **Remove from batch**:
![A code change suggestion displayed, with the button to remove that suggestion from its batch highlighted.](img/remove_suggestion_from_batch_v13_1.jpg "Remove a suggestion from a batch")
1. Having added all the suggestions to your liking, when ready, click **Apply suggestions**:
![A code change suggestion displayed, with the button to apply the batch of suggestions highlighted.](img/apply_batch_of_suggestions_v13_1.jpg "Apply a batch of suggestions")
WARNING:
Suggestions applied from multiple authors creates a commit authored by the user applying the suggestions.
doc/user/project/settings/index.md
View file @ 0abfd19e
......@@ -194,7 +194,7 @@ Set up your project's merge request settings:
- Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md).
- Enable [merge only when all threads are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved).
- Enable [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch)
- Configure [suggested changes commit messages](../../discussions/index.md#configure-the-commit-message-for-applied-suggestions)
- Configure [suggested changes commit messages](../merge_requests/reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions)
- Configure [the default target project](../merge_requests/creating_merge_requests.md#set-the-default-target-project) for merge requests coming from forks.
### Service Desk
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7