diff options
Diffstat (limited to 'doc/user/project/merge_requests/creating_merge_requests.md')
| -rw-r--r-- | doc/user/project/merge_requests/creating_merge_requests.md | 292 |
1 files changed, 106 insertions, 186 deletions
diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 430c6488b26..0d56fbc89b8 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -7,189 +7,155 @@ description: "How to create merge requests in GitLab." disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html' --- -# How to create a merge request **(FREE)** +# Creating merge requests **(FREE)** -Before creating a merge request, read through an -[introduction to merge requests](getting_started.md) -to familiarize yourself with the concept, the terminology, -and to learn what you can do with them. +There are many different ways to create a merge request. -Every merge request starts by creating a branch. You can either -do it locally through the [command line](#new-merge-request-from-your-local-environment), via a Git CLI application, -or through the [GitLab UI](#new-merge-request-from-a-new-branch-created-through-the-ui). +## From the merge request list -This document describes the several ways to create a merge request. +You can create a merge request from the list of merge requests. -When you start a new merge request, regardless of the method, -you are taken to the [**New merge request** page](#new-merge-request-page) -to fill it with information about the merge request. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left menu, select **Merge requests**. +1. In the top right, select **New merge request**. +1. Select a source and target branch and then **Compare branches and continue**. +1. Fill out the fields and select **Create merge request**. -If you push a new branch to GitLab, also regardless of the method, -you can click the [**Create merge request**](#create-merge-request-button) -button and start a merge request from there. +## From an issue -## New merge request page +You can [create a merge request from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue). -On the **New merge request** page, start by filling in the title and description -for the merge request. If commits already exist on the branch, GitLab suggests a -merge request title for you: +## When you add, edit, or upload a file -- **If a multi-line commit message exists**: GitLab adds the first line of the - first multi-line commit message as the title. Any additional lines in that - commit message become the description. -- **If no multi-line commit message exists**: GitLab adds the branch name as the - title, and leaves the description blank. +You can create a merge request when you add, edit, or upload a file to a repository. -The title is the only field that is mandatory in all cases. +1. Add, edit, or upload a file to the repository. +1. In the **Commit message**, enter a reason for the commit. +1. Select the **Target branch** or create a new branch by typing the name (without spaces, capital letters, or special chars). +1. Select the **Start a new merge request with these changes** checkbox or toggle. This checkbox or toggle is visible only + if the target is not the same as the source branch, or if the source branch is protected. +1. Select **Commit changes**. -From there, you can fill it with information (title, description, -assignee(s), milestone, labels, approvers) and click **Create merge request**. +## When you create a branch -From that initial screen, you can also see all the commits, -pipelines, and file changes pushed to your branch before submitting -the merge request. +You can create a merge request when you create a branch. - +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left menu, select **Repository > Branches**. +1. Type a branch name and select **New branch**. +1. Above the file list, on the right side, select **Create merge request**. + A merge request is created. The default branch is the target. +1. Fill out the fields and select **Create merge request**. -NOTE: -You can push one or more times to your branch in GitLab before -creating the merge request. +## When you use Git commands locally -## Create merge request button +You can create a merge request by running Git commands on your local machine. -Once you have pushed a new branch to GitLab, visit your repository -in GitLab and to see a call-to-action at the top of your screen -from which you can click the button **Create merge request**. +1. Create a branch: - + ```shell + git checkout -b my-new-branch + ``` -You can also see the **Create merge request** button in the top-right of the: +1. Create, edit, or delete files. The stage and commit them: -- **Project** page. -- **Repository > Files** page. -- **Merge requests** page. + ```shell + git add . + git commit -m "My commit message" + ``` -In this case, GitLab uses the most recent branch you pushed -changes to as the source branch, and the default branch in the current -project as the target. +1. [Push your branch to GitLab](../../../gitlab-basics/start-using-git.md#send-changes-to-gitlabcom): -## New merge request by adding, editing, and uploading a file + ```shell + git push origin my-new-branch + ``` -When you choose to edit, add, or upload a file through the GitLab UI, -at the end of the file you see the option to add the **Commit message**, -to select the **Target branch** of that commit, and the checkbox to -**Start new a merge request with these changes**. + GitLab prompts you with a direct link for creating a merge request: -Similarly, if you change files through the Web IDE, when you navigate to **Commit** on the left-hand sidebar, you see these same options. + ```plaintext + ... + remote: To create a merge request for docs-new-merge-request, visit: + remote: https://gitlab.example.com/my-group/my-project/merge_requests/new?merge_request%5Bsource_branch%5D=my-new-branch + ``` -Once you have added, edited, or uploaded the file: +1. Copy the link and paste it in your browser. -1. Describe your changes in the commit message. -1. Select an existing branch to add your commit into, or, if you'd like to create a new branch, type the new branch name (without spaces, capital letters, or special chars). -1. Keep the checkbox checked to start a new merge request straightaway, or, uncheck it to add more changes to that branch before starting the merge request. -1. Click **Commit changes**. +You can add other [flags to commands when pushing through the command line](../push_options.md) +to reduce the need for editing merge requests manually through the UI. -If you chose to start a merge request, you are taken to the -[**New merge request** page](#new-merge-request-page), from -which you can fill it in with information and submit the merge request. +## When you work in a fork -The merge request targets the default branch of the repository. -If you want to change it, you can do it later by editing the merge request. +You can create a merge request from your fork to contribute back to the main project. -## New merge request from a new branch created through the UI - -To quickly start working on files through the GitLab UI, -navigate to your project's **Repository > Branches** and click -**New branch**. A new branch is created and you can start -editing files. - -Once committed and pushed, you can click on the [**Create merge request**](#create-merge-request-button) -button to open the [**New merge request** page](#new-merge-request-page). -A new merge request is started using the current branch as the source, -and the default branch in the current project as the target. - -## New merge request from your local environment - -Assuming you have your repository cloned into your computer and you'd -like to start working on changes to files, start by creating and -checking out a new branch: - -```shell -git checkout -b my-new-branch -``` - -Work on your file changes, stage, and commit them: +1. On the top bar, select **Menu > Project**. +1. Select your fork of the repository. +1. On the left menu, go to **Merge requests**, and select **New merge request**. +1. In the **Source branch** drop-down list box, select the branch in your forked repository as the source branch. +1. In the **Target branch** drop-down list box, select the branch from the upstream repository as the target branch. + You can set a [default target project](#set-the-default-target-project) to + change the default target branch (which can be useful if you are working in a + forked project). +1. Select **Compare branches and continue**. +1. Select **Submit merge request**. -```shell -git add . -git commit -m "My commit message" -``` +After your work is merged, if you don't intend to +make any other contributions to the upstream project, you can unlink your +fork from its upstream project. Go to **Settings > Advanced Settings** and +[remove the forking relationship](../settings/index.md#removing-a-fork-relationship). -Once you're done, [push your branch to GitLab](../../../gitlab-basics/start-using-git.md#send-changes-to-gitlabcom): +For more information, [see the forking workflow documentation](../repository/forking_workflow.md). -```shell -git push origin my-new-branch -``` +## By sending an email **(FREE SELF)** -In the output, GitLab prompts you with a direct link for creating -a merge request: +> The format of the generated email address changed in GitLab 11.7. + The earlier format is still supported so existing aliases + or contacts still work. -```shell -... -remote: To create a merge request for docs-new-merge-request, visit: -remote: https://gitlab-instance.com/my-group/my-project/merge_requests/new?merge_request%5Bsource_branch%5D=my-new-branch -``` +You can create a merge request by sending an email message to GitLab. +The merge request target branch is the project's default branch. -Copy that link and paste it in your browser, and the [**New merge request page**](#new-merge-request-page) -is displayed. +Prerequisites: -There is also a number of [flags you can add to commands when pushing through the command line](../push_options.md) to reduce the need for editing merge requests manually through the UI. +- A GitLab administrator must configure [incoming email](../../../administration/incoming_email.md). +- A GitLab administrator must configure [Reply by email](../../../administration/reply_by_email.md). -If you didn't push your branch to GitLab through the command line -(for example, you used a Git CLI application to push your changes), -you can create a merge request through the GitLab UI by clicking -the [**Create merge request**](#create-merge-request-button) button. +To create a merge request by sending an email: -## New merge request from an issue +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left menu, select **Merge requests**. +1. In the top right, select **Email a new merge request to this project**. + An email address is displayed. Copy this address. + Ensure you keep this address private. +1. Open an email and compose a message with the following information: -You can also [create a new merge request directly from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue). + - The **To** line is the email address you copied. + - The subject line is the source branch name. + - The message body is the merge request description. -## New merge request from the merge requests page +1. Send the email message. -You can start creating a new merge request by clicking the -**New merge request** button on the **merge requests** page in a project. -Then choose the source project and branch that contain your changes, -and the target project and branch where you want to merge the changes into. -Click on **Compare branches and continue** to go to the -[**New merge request** page](#new-merge-request-page) and fill in the details. +A merge request is created. -## New merge request from a fork +### Add attachments when creating a merge request by email -After forking a project and applying your local changes, complete the following steps to -create a merge request from your fork to contribute back to the main project: +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22723) in GitLab 11.5. -1. On the top bar, select **Menu > Project**. -1. Select **Your Projects**, then select your fork of the repository. -1. In the left menu, go to **Merge requests**, and click **New merge request**. -1. In the **Source branch** drop-down list box, select your branch in your forked repository as the source branch. -1. In the **Target branch** drop-down list box, select the branch from the upstream repository as the target branch. - You can set a [default target project](#set-the-default-target-project) to - change the default target branch (which can be useful when working with a - forked project). -1. After entering the credentials, click **Compare branches and continue** to compare your local changes to the upstream repository. -1. Assign a user to review your changes, and click **Submit merge request**. +You can add commits to a merge request by adding +patches as attachments to the email. All attachments with a filename +ending in `.patch` are considered patches and are processed +ordered by name. -When the changes are merged, your changes are added to the upstream repository and -the branch as per specification. After your work is merged, if you don't intend to -make any other contributions to the upstream project, you can unlink your -fork from its upstream project in the **Settings > Advanced Settings** section by -[removing the forking relationship](../settings/index.md#removing-a-fork-relationship). +The combined size of the patches can be 2 MB. -For further details, [see the forking workflow documentation](../repository/forking_workflow.md). +If the source branch from the subject does not exist, it is +created from the repository's HEAD or the specified target branch. +You can specify the target branch by using the +[`/target_branch` quick action](../quick_actions.md). If the source +branch already exists, the patches are applied on top of it. ## Set the default target project -Merge requests have a source and a target project which are the same, unless +Merge requests have a source and a target project that are the same, unless forking is involved. Creating a fork of the project can cause either of these scenarios when you create a new merge request: @@ -197,57 +163,11 @@ scenarios when you create a new merge request: option). - You target your own fork. -If you want to have merge requests from a fork by default target your own fork -(instead of the upstream project), you can change the default by: +To have merge requests from a fork by default target your own fork +(instead of the upstream project), you can change the default. -1. In your project, go to **Settings > General > Merge requests**. +1. On the top bar, select **Menu > Project**. +1. On the left menu, select **Settings > General > Merge requests**. 1. In the **Target project** section, select the option you want to use for your default target project. 1. Select **Save changes**. - -## New merge request by email **(FREE SELF)** - -_This feature needs [incoming email](../../../administration/incoming_email.md) -to be configured by a GitLab administrator to be available._ It isn't -available in GitLab.com. - -You can create a new merge request by sending an email to a user-specific email -address. The address can be obtained on the merge requests page by clicking on -a **Email a new merge request to this project** button. The subject is -used as the source branch name for the new merge request and the target branch -is the default branch for the project. The message body (if not empty) -is used as the merge request description. You need -["Reply by email"](../../../administration/reply_by_email.md) enabled to use -this feature. If it's not enabled to your instance, you may ask your GitLab -administrator to do so. - -This is a private email address, generated just for you. **Keep it to yourself** -as anyone who has it can create issues or merge requests as if they were you. -You can add this address to your contact list for easy access. - - - -_In GitLab 11.7, we updated the format of the generated email address. -However the older format is still supported, allowing existing aliases -or contacts to continue working._ - -### Adding patches when creating a merge request via e-mail - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/22723) in GitLab 11.5. - -You can add commits to the merge request being created by adding -patches as attachments to the email. All attachments with a filename -ending in `.patch` are considered patches and they are processed -ordered by name. - -The combined size of the patches can be 2MB. - -If the source branch from the subject does not exist, it is -created from the repository's HEAD or the specified target branch to -apply the patches. The target branch can be specified using the -[`/target_branch` quick action](../quick_actions.md). If the source -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](reviews/index.md) through GitLab. |