When making a commit, Git prompts you to enter a message to store with the commit. Commit messages are messages for someone looking at the change in the future. They can help them in making sense of the changes, but Git can't enforce that you write a useful one - how can it? Instead, it is up to you to write something useful for them. So, what can you write to in a commit message to make it useful?
No matter who is looking at the commit message, it helps to describe what is in the commit. This is most likely the first thing anyone will want to know about a commit - what is this commit about? The git commit documentation recommends this being the first thing in commit message:
Though not required, it’s a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git.
Visually, the format looks something like this:
commit title (less than 50 characters recommended)
more thorough description
Log viewers like gitk display their title in the list of commits.
A descriptive title describing what is in the commit will make the logs much more easier to work with.
If you're finding it difficult to write a descriptive title for the commit, perhaps have a look what is in the change and see whether the commit is trying to do more than one thing. Ideally, the commit should be doing just one thing.
When looking back to a previous change, a very common question that is asked is why did we make that change? When trying to build changes on top of previous changes or trying to fix an issue in code, knowing why the changes were made in the first place can help avoiding introducing more problems later. For contributions to other projects, it helps to convince maintainers that they should be included. For your future self, it can help to serve as a reminder of why you did what you did at the time. An explanation of the why indicates that the changes were thought out and wasn't just done on a whim.
Sometimes, the why is implied in the title. For example, "fix spelling errors" would likely be self explanatory. When its not, this is something that should be written in the commit description. Describing the why could also include answering:
- If the change fixes something, what was wrong in the first place? Were there any lessons learnt?
- If it is an new feature, what does it do?
- If it is an optimisation or improvement, how does it improve things? Are you also able to quantify the improvement?
When Git prompts your for a commit message it may be tempting to just fill this in with something to fulfil this step, but to do so would be squandering an opportunity to capture valuable information about it. Writing one is about spending the time and effort now to help someone in the future - it can be immensely helpful in understanding your change and its purpose. Someone may thank you for it one day!
Top comments (0)