1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
---
stage: Create
group: Source Code
info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments"
---
# Tutorial: Update Git commit messages **(FREE ALL)**
Occasionally, after you've made a few commits to your branch, you realize you need
to update one or more commit messages. Perhaps you found a typo, or some automation warned you
that your commit message didn't completely align with a project's
[commit message guidelines](../../development/contributing/merge_request_workflow.md#commit-messages-guidelines).
Updating the message can be tricky if you don't have much practice using Git
from the command-line interface (CLI). But don't worry, even if you have only ever worked in
the GitLab UI, you can follow these steps to use the CLI.
This tutorial explains how to rewrite commit messages in both cases:
- If you work in the GitLab UI only, start at step 1.
- If you already have your repository cloned locally, you can skip to step 2.
To rewrite any number of commit messages:
1. [Clone your project's repository to your local machine](#clone-your-repository-to-your-local-machine).
1. [Fetch and check out your branch locally](#fetch-and-check-out-your-branch).
1. [Update the commit messages](#update-the-commit-messages).
1. [Push the changes up to GitLab](#push-the-changes-up-to-gitlab).
## Before you begin
You must have:
- A GitLab project with a Git branch containing commits that you want to update.
- Git [installed on your local machine](../../topics/git/how_to_install_git/index.md).
- The ability to get to your local machine's command-line interface (CLI). In macOS,
you can use Terminal. In Windows, you can use PowerShell. Linux users are probably
already familiar with their system's CLI.
- Familiarity with your system's default editor. This tutorial assumes your editor is Vim,
but any text editor should work. If you are unfamiliar with Vim, step 1 to 2 of
[Getting started with Vim](https://opensource.com/article/19/3/getting-started-vim)
explains all the commands used later in this tutorial.
- Permission to overwrite the commit messages. If you are working with multiple people in the same branch,
you should first verify with them that it's OK to update the commits. Some organizations might
have rules against rewriting commits, as it is considered a destructive change.
You must authenticate with GitLab to overwrite the commit messages in the final step.
If your GitLab account uses basic username and password authentication, you must have
[two factor authentication (2FA)](../../user/profile/account/two_factor_authentication.md)
disabled to authenticate from the CLI. Alternatively, you can [use an SSH key to authenticate with GitLab](../../user/ssh.md).
## Clone your repository to your local machine
The first step is to get a clone of the repository on your local machine:
1. In GitLab, on your project's overview page, on the top right, select **Clone**.
1. In the dropdown list, copy the URL for your repository by selecting **{copy-to-clipboard}** next to:
- **Clone with HTTPS** if your GitLab account uses basic username and password authentication.
- **Clone with SSH** if you use SSH to authenticate with GitLab.
1. Now switch to the CLI (Terminal, PowerShell, or similar) on your local machine, and go to
the directory where you want to clone the repository. For example, `/users/my-username/my-projects/`.
1. Run `git clone` and paste the URL you copied earlier, for example:
```shell
git clone https://gitlab.com/my-username/my-awesome-project.git
```
This clones the repository into a new directory called `my-awesome-project/`.
Now your repository is on your computer, ready for your Git CLI commands!
## Fetch and check out your branch
Next, you need to check out the branch that contains the commits to update.
1. Assuming you are still at the same place in the CLI as the previous step,
change to your project directory with `cd`:
```shell
cd my-awesome-project
```
1. Optional. If you've just cloned the repository, your branch should already be
on your computer too. But if you've previously cloned the repository and skipped
to this step, you might need to fetch your branch with:
```shell
git fetch origin my-branch-name
```
1. Now that you know for sure that the branch is on your local system, switch to it:
```shell
git checkout my-branch-name
```
1. Verify that it's the correct branch with `git log` and check that the most recent commits
match the commits in your branch on GitLab. To exit the log, use `q`.
## Update the commit messages
Now you are ready to update the commit messages:
1. In GitLab, check how far back in the commit history you need to go:
- If you already have a merge request open for your branch, you can check the
**Commits** tab and use the total number of commits.
- If you are working from a branch only:
1. Go to **Code > Commits**.
1. Select the dropdown list in the top left and find your branch.
1. Find the oldest commit you want to update, and count how far back that commit is.
For example, if you want to update the second and fourth commit, the count would be 4.
1. From the CLI, start an interactive rebase, which is the Git process to update commits.
Add the count of commits from the previous step to the end of `HEAD~`, for example:
```shell
git rebase -i HEAD~4
```
In this example, Git selects the four most recent commits in the branch to update.
1. Git launches a text editor and lists the selected commits.
For example, it should look similar to:
```shell
pick a0cea50 Fix broken link
pick bb84712 Update milestone-plan.md
pick ce11fad Add list of maintainers
pick d211d03 update template.md
# Rebase 1f5ec88..d211d03 onto 1f5ec88 (4 commands)
#
# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup [-C | -c] <commit> = like "squash" but keep only the previous
# commit's log message, unless -C is used, in which case
# [and so on...]
```
1. The `pick` command tells Git to use the commits without change. You must change
the command from `pick` to `reword` for the commits you want to update.
Type `i` to enter `INSERT` mode, and then start editing the text.
For example, to update the text of the second and fourth commits in the sample above,
edit it to look like:
```shell
pick a0cea50 Fix broken link
reword bb84712 Update milestone-plan.md
pick ce11fad Add list of maintainers
reword d211d03 update template.md
```
1. Save the edited text. Press <kbd>Escape</kbd> to exit `INSERT` mode,
then type `:wq` and <kbd>Enter</kbd> to save and exit.
1. Git now goes through each commit one at a time and applies the commands you selected.
Any commits with `pick` are added back to the branch unchanged. When Git reaches a commit
with `reword`, it stops and again opens up the text editor. Now it's time to finally update
the text of the commit message!
- If you only need a one line commit message, update the text as needed. For example:
```plaintext
Update the monthly milestone plan
```
- If the commit message needs a title and a body, separate these with a blank line. For example:
```plaintext
Update the monthly milestone plan
Make the milestone plan clearer by listing the responsibilities
of each maintainer.
```
After you save and exit, Git updates the commit message, and processes the next
commits in order. You should see the message `Successfully rebased and update refs/heads/my-branch-name`
when finished.
1. Optional. To verify that the commit messages were updated, you can run `git log`
and scroll down to see the commit messages.
## Push the changes up to GitLab
Now all that's left is to push these changes up to GitLab:
1. From the CLI, push the changes back to GitLab. You must use the `-f` "force push" option,
because the commits were updated and a force push overwrites the old commits in GitLab.
```shell
git push -f origin
```
Your terminal might prompt you for your username and password before overwriting
the commit messages in GitLab.
1. In your project in GitLab, verify that the commits have been updated:
- If you already have a merge request open for your branch, check the **Commits** tab.
- If you are working from a branch only:
1. Go to **Code > Commits**.
1. Select the dropdown list in the top left and find your branch.
1. Verify that the relevant commits in the list are now updated.
Congratulations, you have successfully updated your commit messages and pushed them to GitLab!
|
