For a long time I didn't know that even writing commit message can have its own "best practices". When I got in touch with git for the first time, this part was described with words like "...and here you can write something short about what's going on in the commit".
Look at the commit messages below. If you want to merge them, you realy don't know, what you are adding / changing, what they do or why you need them. The same applies if you want to search something in the history. You scroll down the log, but it is a mess and a waste of time.
cd3e27a contact page aee9d0d comments eac95e5 list of online users, some other changes because of server fae5636 little edit
And now take a look at these messages. Better? I think so.
43ec6aa Fix error when the URL is not reachable 4fe84ab Add error message if something went wrong 753aa05 Add server fingerprint check df3a662 Fix shadow box closing problem
The whole message should have its format - subject, body and optionally conclusion consisting of resolved / closed issues.
The git commit help page described it very good as a single short (less than 50 character) line summarizing the change, followed by a blank line. The subject should start with a capital letter and should not end with dot. And the important thing here is, it has to be in imperative form. Chris Beams wrote a simple rule to get it right every time :
A properly formed Git commit subject line should always be able to complete the following sentence: if applied, this commit will your subject line here. For example :
It will not work for bad commit messages :
The git itself is using this approach. When you merge something it generates a commit message like "Merge branch...", or when reverting "Revert...".
Here you write what and why is changed. The body should not exceed 72 characters for a line. Of course not every commit has to have body.
On the end, you can add which issue does the commit fix or is related to. This can be a link, number or if you use GitHub you can write it as Resolves #N / Closes #N, where N is the issue ID.
This is an example commit from one of my repositories :
Fix error when protocol is missing First, it checks if the protocol is set. If not, it changes the url and add the basic http protocol on the beginning. Second, it does a "preflight" request and follows all redirects and returns the last URL. The process then continues with this URL. Resolves #17
Thank you for reading, I hope you learned something new. If you have another tip(s) how to write better commit messages, or how to better use this tool, please leave a comment.
Another advantage of such commits is it is really easy to generate changelog.
# show whole commit history $ git log --oneline --decorate --color # show history from one tag to another $ git log 0.0.9..0.0.10 --oneline --decorate --color # show history form tag to head git log 0.0.9..HEAD --oneline --decorate --color
The result of such command is the list of commits.
21629ee Fix getResources bug aa13384 Update docs 44de44c Add HSTS check
There is a command line tool available on GitHub named Commitizen which makes it a little bit easier. When you want to commit, you just type git cz and it asks you couple of questions and then creates the commit with proper message for you.
Git commit manpage
Closing issues using keywords on GitHub
How to Write a Git Commit Message post from Chris Beams
You know, I actually disagree. I love having good standards, and I absolutely hate being confused about what is in our code base, who did it, when did they do it, and why, but commit messages are not the solution to this problem.
If you are using a tool like Github or BitBucket, you should always use pull requests. Pull Requests should contain an explanation of the problem being solved, the decided-upon solution, and the actual implementation of the solution. This should also include videos and links to external resources, when appropriate.
You can't get that from a commit message. If you are using pull requests and committing regularly and often, your commit messages will rarely be that helpful.
If you need detailed commit messages to find something you did wrong, then you are likely not committing often enough, leaving your commits too large to manage effectively.
If you need detailed commit messages to roll back to a certain version, then you should be squashing your merges into your production branch and mentioning the release name. Your individual commit messages should only live for the lifetime of development; once merged, your commits should live in the pull request for historical purposes.
To round all of my rambling up, commit messages are not that useful if you are committing many, many times a day, which I think we all should be doing. Spending time creating detailed messages is not very valuable. Use tooling and processes to make you work smarter.
Just one person's opinion!
I disagree with Sager. If you're making a deliberate change to your code-base, you should know why. If it takes you more than a 30 seconds to describe the change you're making, perhaps your commit is too big, or you should take some time to better understand the change your making. Perhaps that's an idealistic world and I get that it's not always going to work out that way, but I feel like that should be a goal.
In any case, ideally if a single pull request contains a single commit, sure, the commit message might be less important. But as features grow, a single PR may contain multiple commits that touch different parts of a project, and having good messages could make it easier to know which commit is a front-end change and which is a back-end, which could lead to reduced debugging times.
I will always advocate for thorough commit messages. If it takes you too long, you don't understand your code well enough, or the commit is too big.
PRs with well thought-out commits and commit messages are WAY easier to review.