Commit b1b930a9 authored by Phil Hughes's avatar Phil Hughes

Merge branch '346527-aqualls-refine-squash-merge' into 'master'

Revise commit templates page for tone and style

See merge request gitlab-org/gitlab!75579
parents d057bc1f 3c4e9bc3
......@@ -3,7 +3,7 @@
.form-group
%b= s_('ProjectSettings|Merge commit message template')
%p.text-secondary
- configure_the_merge_commit_message_help_link_url = help_page_path('user/project/merge_requests/commit_templates.md', anchor: 'merge-commit-message-template')
- configure_the_merge_commit_message_help_link_url = help_page_path('user/project/merge_requests/commit_templates.md')
- configure_the_merge_commit_message_help_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: configure_the_merge_commit_message_help_link_url }
= s_('ProjectSettings|The commit message used when merging, if the merge method creates a merge commit. %{link_start}Learn more about syntax and variables.%{link_end}').html_safe % { link_start: configure_the_merge_commit_message_help_link_start, link_end: '</a>'.html_safe }
.mb-2
......
......@@ -3,7 +3,7 @@
.form-group
%b= s_('ProjectSettings|Squash commit message template')
%p.text-secondary
- configure_the_squash_commit_message_help_link_url = help_page_path('user/project/merge_requests/commit_templates.md', anchor: 'squash-commit-message-template')
- configure_the_squash_commit_message_help_link_url = help_page_path('user/project/merge_requests/commit_templates.md')
- configure_the_squash_commit_message_help_link_start = '<a href="%{url}" target="_blank" rel="noopener noreferrer">'.html_safe % { url: configure_the_squash_commit_message_help_link_url }
= s_('ProjectSettings|The commit message used when squashing commits. %{link_start}Learn more about syntax and variables.%{link_end}').html_safe % { link_start: configure_the_squash_commit_message_help_link_start, link_end: '</a>'.html_safe }
.mb-2
......
......@@ -1314,7 +1314,7 @@ POST /projects/user/:user_id
| `jobs_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable jobs for this project. Use `builds_access_level` instead. |
| `lfs_enabled` | boolean | **{dotted-circle}** No | Enable LFS. |
| `merge_commit_template` | string | **{dotted-circle}** No | [Template](../user/project/merge_requests/commit_templates.md) used to create merge commit message in merge requests. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5.)_ |
| `squash_commit_template` | string | **{dotted-circle}** No | [Template](../user/project/merge_requests/commit_templates.md#squash-commit-message-template) used to create squash commit message in merge requests. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) in GitLab 14.6.)_ |
| `squash_commit_template` | string | **{dotted-circle}** No | [Template](../user/project/merge_requests/commit_templates.md) used to create squash commit message in merge requests. _([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) in GitLab 14.6.)_ |
| `merge_method` | string | **{dotted-circle}** No | Set the [merge method](#project-merge-method) used. |
| `merge_requests_access_level` | string | **{dotted-circle}** No | One of `disabled`, `private`, or `enabled`. |
| `merge_requests_enabled` | boolean | **{dotted-circle}** No | _(Deprecated)_ Enable merge requests for this project. Use `merge_requests_access_level` instead. |
......
......@@ -7,15 +7,42 @@ type: reference, howto
# Commit message templates **(FREE)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/20263) in GitLab 14.5.
> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) squash commit templates in GitLab 14.6.
## Merge commit message template
GitLab uses commit templates to create default messages for specific types of
commits. These templates encourage commit messages to follow a particular format,
or contain specific information. Users can override these templates when merging
a merge request.
As a project maintainer, you're able to configure merge commit message template. It will be used during merge to
create commit message. Template uses similar syntax to
Commit templates use syntax similar to the syntax for
[review suggestions](reviews/suggestions.md#configure-the-commit-message-for-applied-suggestions).
Default merge commit message can be recreated using following template:
## Configure commit templates
Change the commit templates for your project if the default templates don't
contain the information you need.
Prerequisite:
- You must have at least the Maintainer role for a project.
To do this:
1. On the top bar, select **Menu > Projects** and find your project.
1. On the left sidebar, select **Settings > General** and expand **Merge requests**.
1. Depending on the type of template you want to create, scroll to either
[**Merge commit message template**](#default-template-for-merge-commits) or
[**Squash commit message template**](#default-template-for-squash-commits).
1. For your desired commit type, enter your default message. You can use both static
text and [variables](#supported-variables-in-commit-templates). Each template
is limited to a maximum of 500 characters, though after replacing the templates
with data, the final message may be longer.
1. Select **Save changes**.
## Default template for merge commits
The default template for merge commit messages is:
```plaintext
Merge branch '%{source_branch}' into '%{target_branch}'
......@@ -27,40 +54,30 @@ Merge branch '%{source_branch}' into '%{target_branch}'
See merge request %{reference}
```
This commit message 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 commit message template** text:
![Custom commit message for merge commit](img/merge_commit_message_template_v14_5.png)
## Default template for squash commits
You can use static text and following variables:
If you have configured your project to [squash commits on merge](squash_and_merge.md),
GitLab creates a squash commit message with this template:
| Variable | Description | Output example |
|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|
| `%{source_branch}` | The name of the branch that is being merged. | `my-feature-branch` |
| `%{target_branch}` | The name of the branch that the changes are applied to. | `master` |
| `%{title}` | Title of the merge request. | Fix stuff |
| `%{issues}` | String with phrase "Closes <issue numbers>" with all issues mentioned in the MR description matching [issue closing patterns](../issues/managing_issues.md#closing-issues-automatically). It will be empty when no issues were mentioned. | `Closes #465, #190 and #400` |
| `%{description}` | Description of the merge request. | Merge request description.<br>Can be multiline. |
| `%{reference}` | Reference to the merge request. | group-name/project-name!72359 |
NOTE:
Empty variables that are the only word in a line will be removed along with all newline characters preceding it.
Merge commit template field has a limit of 500 characters. This limit only applies to the template
itself.
```plaintext
%{title}
```
## Squash commit message template
## Supported variables in commit templates
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345275) in GitLab 14.6.
Commit message templates support these variables:
As a project maintainer, you're able to configure squash commit message template. It will be used during merge with
squash to create squash commit message. It uses the same syntax and variables as merge commit message template.
| Variable | Description | Output example |
|----------|-------------|----------------|
| `%{source_branch}` | The name of the branch being merged. | `my-feature-branch` |
| `%{target_branch}` | The name of the branch that the changes are applied to. | `main` |
| `%{title}` | Title of the merge request. | `Fix tests and translations` |
| `%{issues}` | String with phrase `Closes <issue numbers>`. Contains all issues mentioned in the merge request description that match [issue closing patterns](../issues/managing_issues.md#closing-issues-automatically). Empty if no issues are mentioned. | `Closes #465, #190 and #400` |
| `%{description}` | Description of the merge request. | `Merge request description.<br>Can be multiline.` |
| `%{reference}` | Reference to the merge request. | `group-name/project-name!72359` |
![Custom commit message for squash commit](img/squash_commit_message_template_v14_6.png)
Empty variables that are the only word in a line are removed, along with all newline characters preceding it.
Default squash commit message can be recreated using following template:
## Related topics
```plaintext
%{title}
```
- [Squash and merge](squash_and_merge.md).
......@@ -28,7 +28,8 @@ NOTE:
The squashed commit in this example is followed by a merge commit, because the merge method for this repository uses a merge commit. You can disable merge commits in
**Project Settings > General > Merge requests > Merge method > Fast-forward merge**.
The squashed commit's default commit message is taken from the merge request title. It can be changed using [squash commit message template](commit_templates.md#squash-commit-message-template).
The squashed commit's default commit message is taken from the merge request title.
You can [edit the default message for squash commits](commit_templates.md).
It can also be customized before merging a merge request.
......@@ -123,6 +124,10 @@ NOTE:
If your project is set to **Do not allow** Squash and Merge, the users still have the option to
squash commits locally through the command line and force-push to their remote branch before merging.
## Related topics
- [Commit message templates](commit_templates.md).
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
......
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