Why should I write a commit message?

Question

Why should I write a commit message? I don't want to and i think its stupid every single time.

A GUI frontend I use which will go unnamed forces you to do it. I hear other doing it every time even if they are using the VCS on the command line.

If I commit several times a day and haven't finished a feature what am I writing about? I ONLY ever write a message after many commits and I feel it's time for a mini tag or when I do an actual tag.

Am I right or am I missing something? also I am using a distributed system

Answer 1

To all the people saying "commit only when you have a useful, well thought out message to write, and when your feature is 100% complete, and you have unit tests for it", I say: You're still in the SVN mindset.

If you're using git, this is what I would call a smart workflow:

1. Commit as often as you like. Write any old quick message there. No one will see it anyways.
2. After say, 10 commits, you've finished that feature you were working on. Now write tests and commit those tests. Or whatever else you want. If you like TDD, write tests first, I don't care, neither does git.
3. git rebase -i from the first 'messy' commit you added and fix your local history by squashing, editing, omitting and otherwise cleaning up your recent history into logical, clean commits with nice messages.
4. After cleanup, ask someone to pull from you.
5. Rinse and repeat.

Notice that step 3 is when you end up with those nice commits you were after, and that using SVN you'd have to abstain from committing until you've done the first two steps, which is what most of the other answers are suggesting. IOW, you don't want to inflict your half-written, untested code on others, so you don't commit for a week, until your feature is done. You're not using version control to its full potential.

Also note that anywhere between steps 1 and 3, you can git push your changes to your own private repo mirror on the server to get free backups if your laptop HDD dies.

Answer 2

Because when some poor maintainer is hunting a bug and finds that it was added in rev. xyz, he will want to know what rev. xyz was supposed to do.

Answer 3

You comment your source code, right?

You write the very best comments, those that say why as the code only say how?

The commit message is such a comment, and therefore it is very important and the more thought you put into getting it right, the more useful it is to a future maintainer of the software.

For any active piece of software, this particular comment will end up being showed in something like

(found at http://longair.net/blog/2009/04/25/a-few-git-tips/). This allows a birds eye view of who has worked on the software when, and what they did.

Note that this is the ultimate goal for the commit comment, namely showing up in such a list saying "what" to your future self or your colleague, and THAT is the reason why you should take care in writing good commit messages.

Answer 4

If the commit message seems stupid to you then it sounds like you are using commits wrong.

Commits should be made for good reason — they should be related to tasks you've broken down for the feature you are working on. Whether those tasks are formal or just in your mind, each change you commit should more or less complete a task and therefore be functional in some way.

Then your commit messages serve a much better purpose. Describe the task youn finished and if its not tracked somewhere else, why that task was needed or what purpose it serves:

• Refactored the user class for better encapsulation
• Created API stubs so interfaces could be used in the controller class
• Converted the database class to an abstract class so that a mock database can be used in test cases

Then you or other developers can browse the repository or file history and fairly easily see where certain evolutions happened and why. Or, if a particular revision is found to be guilty of a bug, the commit message will give a clue as to why that line was put in, so that you don't just rip it out and possible rebreak something that was thought to be fixed, and you can instead fix it the right way.

Answer 5

Commit comments don't solve everything. There's always a chance they may mislead as much as they help - especially when developers are angry about having to enter them. Try this: consider them like a bread crumb trail in the woods or a mountaineering waypoint or tracer bullets. Done right, they can outline an otherwise confusing path.

Don't make a big deal out of them. Be honest:

• "Edited spacial index entities, Daos, and UIs to handle feature X"
• "Incremental check-in for feature request #1234 and bug #5678"
• "I broke the last build. These are the files I missed."

Keep it short and "big picture". If possible, refer to an issue number in your feature/bug system. Some version control UIs include a field for this sort of thing.

Answer 6

It reduces the number of WTF/minute ;)

which translates into a happier team (who doesn't hate you), and better team output potentially at lower cost

Answer 7

So the rest of your team knows WTF you're doing checking in changes to the project tree.

Answer 8

because if you don't practice entering decent commit messages, you'll end up like my collegue who enters messages like

no changes

or

testing

for commits with over a hundred changed files (no kidding here!!).

If you become such developer, you'll look stupid in the eyes of the rest of the world, no matter how stupid you think it is to just enter a message.

Answer 9

Why do you commit if the changes are not meaningful?

Just commit changes that have a meaning. E.g. I did a rather large refactoring the other week which took me about 3 days. I would have tons of commits during that time. Some were rather small changes ('renamed class X to Y to reflect new responsibility' or 'moved method Z() to class Q') and others were really large. When I am done with a feature/refactoring I check if some commits could be squashed (at least git supports that, don't know about other tools), but usually I leave them as is because it helps later.

I guess you would not commit in the middle of editing a line, so it should have a meaning. Just describe what you did since the last commit.

Answer 10

If you are working with others, then commit messages are very important to actually see what others have done: looking up the diffs for each of them is much more work and you might fail to get why someone has done it. If you work with others and someone (perhaps not you) has to actually look back, for example to track how behavior changed since the previous version in unexpected ways... you are really making life difficult by not using a helpful hint in the commit message.

If you are working alone... on a project that is mostly coded 'as is' (for example a single simple website or script) I can more or less see where you are coming from. If I work on something like that, I only care about the date/time or the most recent changes when continuing work on something (you have a point to restore to, but that only matters during development, not after you implemented it). Version control is just a way of making backups with a few plusses - I fully agree that is not making complete use of the system - but on some small scale projects, that might not be needed.

The thought has occured to me before that Version Control is being used in two split ways, one of documenting changes in the project, and other as a helping hand to developers in place... and those two are totally different from each other. Commit messages are very important in the one way, and might be mostly useless in the other.

Answer 11

You're missing something. There must be a reason for performing a commit otherwise you wouldn't be doing it.

All you need to do in the comment is to put the reason into words, even if it is only wip: adding new state objects

Answer 12

imagine a condition when you broke your system by making some change and realize this after several commits by team. You don't remember what the change was but you remember something could go wrong when you was enhancing feature X or removing a file from module Y.

But unfortunately revision number doesn't tell you when you changed X or Y. So its your choice either read all codes committed during last N days or just read detailed commit messages you wrote( much more readable than code ).

So if you write same, boring, useless, non-related text in commit message, because you have to, is more harmful than having commit message. Because instead of finding root of bug wrong message will misguide you.

So try to write meaningful commit messages every time you commit which can help you and maintainer as well.

Answer 13

Like many others, I do a little coding in my spare time and use a revision control system to track both my development and changes. The amount of spare time I have available varies greatly from week to week and month to month. Many have been the occasions when I would not have any time to code on a project for weeks or even months on end, and such time as I had would typically range from 10 minutes (typical day) to 40 minutes (good day). Those certainly not great conditions--especially for debugging problems.

It was essential to keep notes that would both not get lost, and were easily retrievable. At the end of each session, the session's work would be committed with a detailed message. I could then go through the commit history and track my progress and thought process. This allowed me to pick up where I was last week, or last month with the least amount of precious time lost.

The point that I am trying to illustrate is that good commit messages help you (and anyone else who comes after you) to figure out what has happenned, what has been going on, where things are going and above all else why.

Answer 14

Think about it logically for a minute. When you are committing that means something was done. If you leave no message how will other people know what was done?

Answer 15

If you don't comment your commits, you may be tempted to comment the change in the source. In time, that can clutter the source.

Answer 16

Commit messages are a quick way to know what is going into that check-in and will help other devs on your team when they want to know which aspect of the code changed in which revisions (for may reasons).

On a related note, I would suggest specifying the bug tracker case number (I hope you are using one) in the commit message, so that it would be helpful for future to easily track things.

Answer 17

So that the maintainer of that code 1 year later knows whom to hunt down for that atrocious code. :)