The most important thing about commit messages, is that it should describe what this change is about. So the message should be about the fix, not about the bug/feature.
Bad example of commit message:
Images have wrong aspect ratio ❌
Better example of commit message:
Force images aspect ratio ✅
Typically a commit message is consisted from a subject and a body. The examples above are subject lines and usually is all we need. But in some cases we may want to add more information to a commit, by leaving an empty line after the subject and keep writing some more text. Here is a good example of how Gihub renders such a commit.
If the commit is connected to a specific ticket, it’s a good practice to add the ticket number to the commit. If the ticket is on Github it should have a similar prefix you can use.
PLANET-1234 Force images aspect ratio
Some syntax and styling rules to make git log history more consistent.
Separate subject from body with a blank line
Capitalize the subject line
Do not end the subject line with a period
Use the imperative mood in the subject line (see https://chris.beams.io/posts/git-commit/)
You can use the ticket number in branch names. Additionally you could add a prefix, depending on the kind of the PR. If the ticket is on Github it should have a similar prefix you can use.
These are all good branch names:
planet-1234 feature/planet-1234 bug/planet-1234
If a Pull Request has just one commit, it automatically inherits its name from that. Otherwise make sure to add the ticket number there too, to make reviewers life easier.
Always add a link to the ticket pointing to all relevant PRs.
Sometimes a reviewer asks us to make some changes to our PR. If these changes are part of the existing work it should also be part of the existing commits, not a new one.
Fixing syntax, linting, typo errors we introduced on our commits should never be a new commit.
Assuming we have one commit already and we did some additional changes to a file. We can amend the commit and update the PR.
git add templates/footer.twiggit commit --amend --no-editgit push -f origin planet-1234
What the above does, is that it stages the changes on footer template and amend our last commit by just adding our staged changes. If we wish to make changes to the commit message we can omit the
-f option on the push command overrides the branch already on the remote (Github) with what we now have locally.
To read more about rewriting git history, you can check the relevant chapter of the git Book.
Sometimes we run into conflicts, because other people code is merged in the meantime.
To solve the conflict we need to update locally the target branch and rebase, not merge.
Assuming we have a PR with conflicts against the main branch. We update main branch first and then we rebase our own branch:
git checkout maingit pullgit checkout planet-1234git rebase main
Git will stop when it finds the conflicts and will ask us to resolve them. Once we do that in our editor we stage the changes and continue the rebase:
git add templates/footer.twiggit rebase --continue
When done we update the remote branch:
git push -f origin planet-1234
You can read more about rebase on the relevant chapter of the git book.
The important thing of this process is that your branch should never have merge commits or commits about resolve conflicts. It should only contain commits that are relevant to your work.
Remember that the
-f option means force, and it essentially rewrites history. So, it’s ok to use it for your own branches, but you should never use it for the project branches (eg. main).