Commit a1173d41 authored by Russell Dickenson's avatar Russell Dickenson

Merge branch 'docs-push-options' into 'master'

Centralize push option documentation

Closes #31147

See merge request gitlab-org/gitlab!18176
parents 4e59f1b0 3859b63b
......@@ -3309,13 +3309,8 @@ all updated Merge Requests will have a pipeline created when using
If your commit message contains `[ci skip]` or `[skip ci]`, using any
capitalization, the commit will be created but the pipeline will be skipped.
Alternatively, one can pass the `ci.skip` [Git push option][push-option] if
using Git 2.10 or newer:
```sh
git push --push-option=ci.skip # using git 2.10+
git push -o ci.skip # using git 2.18+
```
Alternatively, one can pass the `ci.skip` [Git push option](../../user/project/push_options.md#push-options-for-gitlab-cicd)
if using Git 2.10 or newer.
<!-- ## Troubleshooting
......
......@@ -290,140 +290,10 @@ 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 will be applied on top of it.
## Git push options
## Use Git push options with merge requests
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/26752) in GitLab 11.10.
NOTE: **Note:**
Git push options are only available with Git 2.10 or newer. With Git older than 2.18
`git push --push-option=...` should be used instead of `git push -o ...`.
GitLab supports using
[Git push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt)
to perform the following actions against merge requests at the same time
as pushing changes:
- Create a new merge request for the pushed branch.
- Set the target of the merge request to a particular branch.
- Set the merge request to merge when its pipeline succeeds.
- Set the merge request to remove the source branch when it's merged.
- Set the title of the merge request to a particular title.
- Set the description of the merge request to a particular description.
- Add or remove labels from the merge request.
### Create a new merge request using Git push options
To create a new merge request for a branch, use the
`merge_request.create` push option:
```sh
git push -o merge_request.create
```
### Set the target branch of a merge request using Git push options
To update an existing merge request's target branch, use the
`merge_request.target=<branch_name>` push option:
```sh
git push -o merge_request.target=branch_name
```
You can also create a merge request and set its target branch at the
same time using a `-o` flag per push option:
```sh
git push -o merge_request.create -o merge_request.target=branch_name
```
### Set merge when pipeline succeeds using Git push options
To set an existing merge request to
[merge when its pipeline succeeds](merge_when_pipeline_succeeds.md), use
the `merge_request.merge_when_pipeline_succeeds` push option:
```sh
git push -o merge_request.merge_when_pipeline_succeeds
```
You can also create a merge request and set it to merge when its
pipeline succeeds at the same time using a `-o` flag per push option:
```sh
git push -o merge_request.create -o merge_request.merge_when_pipeline_succeeds
```
### Set removing the source branch using Git push options
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/64320) in GitLab 12.2.
To set an existing merge request to remove the source branch when the
merge request is merged, the
`merge_request.remove_source_branch` push option can be used:
```sh
git push -o merge_request.remove_source_branch
```
You can also use this push option in addition to the
`merge_request.create` push option.
### Set merge request title using Git push options
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/64320) in GitLab 12.2.
To set the title of an existing merge request, use
the `merge_request.title` push option:
```sh
git push -o merge_request.title="The title I want"
```
You can also use this push option in addition to the
`merge_request.create` push option.
### Set merge request description using Git push options
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/64320) in GitLab 12.2.
To set the description of an existing merge request, use
the `merge_request.description` push option:
```sh
git push -o merge_request.description="The description I want"
```
You can also use this push option in addition to the
`merge_request.create` push option.
### Add or remove labels using Git push options
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/31831) in GitLab 12.3.
You can add or remove labels from merge requests using push options.
For example, to add two labels to an existing merge request, use the
`merge_request.label` push option:
```sh
git push -o merge_request.label="label1" -o merge_request.label="label2"
```
To remove two labels from an existing merge request, use
the `merge_request.unlabel` push option:
```sh
git push -o merge_request.unlabel="label1" -o merge_request.unlabel="label2"
```
You can also use these push options in addition to the
`merge_request.create` push option.
To create a merge request and add two labels to it, use:
```sh
git push -o merge_request.create -o merge_request.label="label1" -o merge_request.label="label2"
```
Use [Git push options](../push_options.md) to create or update merge requests when
pushing changes to GitLab with Git, without needing to use the GitLab interface.
## Find the merge request that introduced a change
......
---
type: reference
---
# Push Options
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/15643) in GitLab 11.7.
GitLab supports using [Git push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt)
to perform various actions at the same time as pushing changes.
Currently, there are push options available for:
- [Skipping CI jobs](#push-options-for-gitlab-cicd)
- [Merge requests](#push-options-for-merge-requests)
NOTE: **Note:**
Git push options are only available with Git 2.10 or newer.
For Git versions 2.10 to 2.17 use `--push-option`:
```shell
git push --push-option=<push_option>
```
For version 2.18 and later, you can use the above format, or the shorter `-o`:
```shell
git push -o <push_option>
```
## Push options for GitLab CI/CD
If the `ci.skip` push option is used, the commit will be pushed, but no [CI pipeline](../../ci/pipelines.md)
will be created.
| Push option | Description |
| ----------- | ----------- |
| `ci.skip` | Do not create a CI pipeline for the latest push. |
For example:
```shell
git push -o ci.skip
```
## Push options for merge requests
You can use Git push options to perform certain actions for merge requests at the same
time as pushing changes:
| Push option | Description | Introduced in version |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------- |
| `merge_request.create` | Create a new merge request for the pushed branch. | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/26752) |
| `merge_request.target=<branch_name>` | Set the target of the merge request to a particular branch. | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/26752) |
| `merge_request.merge_when_pipeline_succeeds` | Set the merge request to [merge when its pipeline succeeds](merge_requests/merge_when_pipeline_succeeds.md). | [11.10](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/26752) |
| `merge_request.remove_source_branch` | Set the merge request to remove the source branch when it's merged. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/issues/64320) |
| `merge_request.title="<title>"` | Set the title of the merge request. Ex: `git push -o merge_request.title="The title I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/issues/64320) |
| `merge_request.description="<description>"` | Set the description of the merge request. Ex: `git push -o merge_request.description="The description I want"`. | [12.2](https://gitlab.com/gitlab-org/gitlab-foss/issues/64320) |
| `merge_request.label="<label>"` | Add labels to the merge request. If the label does not exist, it will be created. For example, for two labels: `git push -o merge_request.label="label1" -o merge_request.label="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/31831) |
| `merge_request.unlabel="<label>"` | Remove labels from the merge request. For example, for two labels: `git push -o merge_request.unlabel="label1" -o merge_request.unlabel="label2"`. | [12.3](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/31831) |
If you use a push option that requires text with spaces in it, you need to enclose it
in quotes (`"`). You can omit the quotes if there are no spaces. Some examples:
```shell
git push -o merge_request.label="Label with spaces"
git push -o merge_request.label=Label-with-no-spaces
```
You can combine push options to accomplish multiple tasks at once, by using
multiple `-o` (or `--push-option`) flags. For example, if you want to create a new
merge request, and target a branch named `my-target-branch`:
```shell
git push -o merge_request.create -o merge_request.target=my-target-branch
```
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