What is the use of commit messages?

Question

Hi folks,

I struggled asking that question but here it is. I am using source control since several years for multiple projects using different systems (svn, hg, git) and I learned how to improve my messages by following guidelines etc. But as far as I can remember I never ever had a look at them afterwards.

So ... how do you profit from your own commit messages? When I need to go back because I smashed something and need a fresh start, I usually just go back to the latest "node" (where I started or merged a branch). Do I write those messages just for people monitoring the project who are curious what is going on?

Regards

Answer 1

"Send me a list of the things you did in the past two weeks" - Boss

Answer 2

One thing I've found is that the commit messages are a good way to keep myself from not committing often enough. If I can't put the changes into a short commit message I probably should have committed the changes earlier.

Answer 3

Your messages are more for other users than yourself. Although I make sure to place good commit messages even on personal repos as well. Helps when you get sidetracked on a project and visit it months down the line to get a handle of the recent work done on a project.

Answer 4

You write them as an aid to your future self, and others on the team. To give you some background of when I have found them useful:

I used to work on a project where commit messages were invaluable - on more than one occasion I used them to track down code that was years old. On that project our bug tracking system was also integrated with our VCS (ClearCase). So when you checked in a change, it would record the bug number in the commit comments. This was very helpful to allow you to trace back exactly what was changed and why.

So to sum it up, although commit messages may seem pointless if you are just starting out (especially if you are the only one working on the project), they become invaluable once you have a successful product that is supported in production by multiple developers.

Update

Another useful feature of commit messages is that they require you to review and summarize the changes you just made. Even if I remember what I have changed, I will often do a quick diff of a file before checking it in. I will briefly read it all over again to make sure there are no typo's, that I changed everything I meant to, etc. This is a simple way to review your code for those small little bugs that would otherwise find their way into your code. Anyway, after doing this I have a clear picture of what changed, so I use this to write a concise summary of the change when checking in the file. This is a simple habit that helps increase code quality with little effort on your part.

Answer 5

In the best case, a commit is bound to a work item in a feature/bug tracker. That way you will be able to easily see which feature/bug has been implemented/fixed. This is not only useful to know if a certain revision contains a feature or bug fix but also to easily create a release note.

Answer 6

What would be the point of a commit without a note to tell you what it is? It's like asking 'Why do books have titles on the sides?', or perhaps 'Why do books have indexes and page numbers?'. It seems to me that a source control log that didn't have a description for each change wouldn't be very useful.

Reasons you may need to refer to the commit message include

• A bug has surfaced and you want to find when that part of the code was changed last
• You decide to undo some changes and need to decide which revision to revert to

For either of these possibilities, without good commit messages, you would be left looking through the diffs for every single commit until you found what you were looking for in the code.