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

Centralize push option documentation

Closes #31147

See merge request gitlab-org/gitlab!18176

doc/ci/yaml/README.md

@@ -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
 

doc/user/project/merge_requests/index.md

@@ -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
 

doc/user/project/push_options.md

+---
+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
+```