Blog Post #006
Duncan Faulkner – February 2020
This post is slightly off my usual topics of Angular and Angular Material though its loosely linked to Angular I felt it was worthy of a post as this is something we as developers do all the time.
I’ve been using Git for about five years or so now, and writing Git Commit messages can be hard (I would say this is just as hard as coming up with meaningful function and variable names in code), especially when trying to be consistent with the formatting of the message.
I’m sure we’ve all written commit messages like this, the way I have written them have all started like:
git commit -m "name-ticket-number - bug fix" git commit -m "name-ticket-number - more work" git commit -m "name-ticket-number - minor changes" git commit -m "name-ticket-number - work on feature X" git commit -m "name-ticket-number - updated Y on..."
At first these don’t appear to look that bad, you get a rough idea of the change. But when faced with hundreds of commit messages (and from different developers), finding a specific Commit in the Git History becomes that much harder.
Up until quite recently I hadn’t realised that you can provide multiple -m flags with a commit to add multiple commit messages.
Why would you want to add multiple messages to a commit?
Surely we can just cram everything into one message?
By adding multiple messages you can provide much more detail and be more specific about the commit, it doesn’t need to be an abbreviated or cryptic message that only you can remember what the commit was for.
Now, when reading a commit message in say GitLab, the first message becomes the Subject, the second message is the Body, the third message is the Footer (I’ll come to this in a bit), their values are concatenated as separate paragraphs.
git commit -m "name-ticket-number - fixed..." -m "body/description..." -m "footer..."
So this is a little better, adds more detail to the commit message, but we could improve this further by following a convention.
Conventional Commit Standard (I didn’t know that was a thing either!). This is a set of guide lines for creating Git Commit messages that follow a particular format.
The format is:
Each commit message consists of a header, body and footer. The header is mandatory, scope is optional, subject is mandatory. When writing a commit message try and limit each line of the commit to a max of a 100 hundred characters, so it can be read easily on GitLab etc…
It is also acceptable to add the project name or a ticket number in square brackets, for example: [foo-1234] fix(user-service): changed user….
If using something like Jira this [foo-1234] becomes a hyperlink to the ticket from Gitlab / Github.
The type must be one of the following:
- build: Changes that affect the build
- ci: Changes to our CI configuration files and scripts
- docs: Documentation only changes
- feat: A new feature
- fix: A bug fix
- perf: A code change that improves performance
- refactor: A code change that neither fixes a bug nor adds a feature
- style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
- test: Adding missing tests or correcting existing tests
If a commit reverts a previous change then the type should begin with revert: and the body should explain what this change is reverting.
The scope refers to the section that this commit belongs to Components, Services, Directives, Pipes for example user-component, user-service, user-directive etc.. Other scopes include changelog, styles, test and refactor.
The subject should contain a short description of the change, and written in present tense, for example “change” and not “changed” or “changes”.
The body should contain a longer description of the change, try not to repeat the subject and keep it in the present tense as above.
The footer is used to highlight where issues have created a breaking change in your commit. The footer should start with BREAKING CHANGE: the body should contain a description of the breaking change.
The footer can also be used to reference other issues, for example: “Fixes ticket #123”.
A few examples of Git Commit messages using this new format:
feat(order): add a save button
add the save button to the sales order form
docs(manual): document the order process
create new document explaining the sales order process
fix(user): update the user menu
update to the user menu to fix the broken menu item
fix(user-service): change save method in API
BREAKING CHANGE: change to the save method to include additional parameters
Let me know in the comments what you think to this format.