Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

Why should i write a commit message? I dont 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 everytime even if they are using the VCS on the command line.

If i commit several times a day and havent finish a feature what am i writing about? I ONLY ever write a message after many commits and i feel its 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

share|improve this question
50  
I wanted to fix spelling and style in your question, but instead I'll just leave it as is: a bad writer asks why he should write more... –  Pavel Shved Feb 26 '11 at 9:59
3  
@Pavel: Brilliant +1 –  acidzombie24 Feb 26 '11 at 10:20
2  
-1 for loaded question and the accepted answer. If I could I would give you -10 for accepting the answer you wanted to hear. –  Boris Yankov Nov 2 '11 at 17:48
1  
@Boris: Hey... it convinced me to write commit messages which is exactly what i asked. Also it didnt tell me to do something completely stupid like backup the file outside of source control or to commit less frequently (which in IMO is horrible advice to tell someone not to commit when he wants to. Even half a day of work is valuable). Also you have not a single reason to disagree with the accepting answer. –  acidzombie24 Nov 2 '11 at 19:24

17 Answers 17

up vote 16 down vote accepted

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.

share|improve this answer
4  
my workflow, git rocks –  Nazgob Feb 27 '11 at 12:50
1  
@Boris: Because he is clearly talking about git which is clearly NOT subversion –  acidzombie24 Nov 2 '11 at 19:25
3  
It really shouldn't be any significant work to write a sentence stating what you just did, and destroying history with rebase seems obnoxious. Suppose you introduced a bug in the 5th of those ten commits that isn't caught until a week later. Being able to pin it down to a single small commit will help you a lot. –  Steven Burnap May 14 '12 at 19:45

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.

share|improve this answer
32  
Well then he can read the 5,000 lines of spaghetti I just checked in, JEESH!!! Some people are just lazy! –  Crazy Eddie Feb 26 '11 at 8:18
7  
BEcause when the poor sucker comes after you (in 3 years time) and looks at the history and goes... WTF .. WTF .. WTF, he will at least have some idea of what was going on. You can easily add a comment like "routine checkin, feature X, incomplete". –  quickly_now Feb 26 '11 at 10:01
3  
@acidzombie24: Because every commit should say what it was for - even if it's "corrected typo in ....", there's no point in a revision history, unless you know what the revisions are for. –  Orbling Feb 26 '11 at 14:13
8  
@quickly_now, the poor sucker might even be yourself. Unfortunately this is one of the things you must experience yourself to appreciate it fully. –  user1249 Feb 26 '11 at 14:55
2  
@Crazy Eddie, because DVCS affords you this flexibility. –  Alex Budovski Feb 26 '11 at 23:19

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

gitk --all sample

(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.

share|improve this answer
2  
@acidzombie, I can only speak for git, but you can commit in very small steps locally and then group them all together in a single commit when pushing upstream. That commit message can then be descriptive. –  user1249 Feb 26 '11 at 10:20
2  
@acidzombie, why do you commit if you have not done enough changes to warrant a comment? Please explain. –  user1249 Feb 26 '11 at 14:56
2  
@Thor: Because version control protects your code against loss, and even half-done code should be protected. –  Ben Voigt Feb 26 '11 at 22:24
1  
@Ben, commits are for long term storage and should accurately reflect work "chunks". Protection against loss is in my opinion orthogonal to version control, and should be handled by a suitable backup system. I have found Time Machine for the Mac extremely well suited for this purpose - I hope a similar system is available for Windows. –  user1249 Feb 26 '11 at 23:10
2  
+1 I'm a fan of not polluting my source control with meaningless commits. It makes searching for a particular commit easier (through useful comments), and I know that when I check out code, it's always in a working state. Traditional backup software is a better option for protecting my local repository in-between commits. This works well with a DVCS, but you have to remember that a local check-in is not really a backup of your code. –  Anna Lear Feb 27 '11 at 15:28

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.

share|improve this answer
1  
@Karl: IIRC linus in his git google talk said on average 6 commits are done per day. Now, i dont know how much is considered to much, but on this project right now i commited when i got some reflection working (i loop the right data, i dont do anything with it), after i generated interface but before serialization works. and i am now working on getting serialization working even though i had the interface 2hours ago. I'll commit and say 'reflection basics' once that works but on the first three why would i ever leave a comment when i can easily see when a features is 'working' every x commits. –  acidzombie24 Feb 26 '11 at 10:02

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.

share|improve this answer
2  
+1 for the idea of keeping it short. Short and simple and good enough is perfectly fine. –  quickly_now Feb 26 '11 at 10:03
1  
IMHO an even better guidance would be the common "as short as possible, as long as necessary" recipe; since sometimes it simply isn't possible to keep it short without sacrificing essential information –  hvr Jan 14 '12 at 11:42

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

share|improve this answer
6  
I add commit messages for my projects, when I'm the ONLY DEVELOPER! Because when I come back in 2 years to look at this stuff, I want to know WTF I was doing at the time. I know perfectly well that 99% of the time this won't be looked at. The 1% of the time it will save me 2 weeks of agony, and I think the price of entering a 10 second commit message is worth the long term benefit I will get. –  quickly_now Feb 26 '11 at 10:07
1  
@quickly_now: Amen to that. In the space of a year or two, a lot of code comes out of me, what every last bit was supposed to do months later, god only knows. God, and my revision history. –  Orbling Feb 26 '11 at 14:16

It reduces the number of WTF/minute ;)

enter image description here

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

share|improve this answer
3  
I would up vote this if you elaborated on why this is true. –  TokenMacGuy Feb 26 '11 at 16:46
1  
How do expressive commit messages Reduce WTFs/Minute (they do, certainly) –  TokenMacGuy Feb 26 '11 at 17:21

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.

share|improve this answer
1  
sounds like a perfect candidate for peer review before commit, if I ever heard one. –  user1249 Feb 26 '11 at 14:58
2  
oh man, I've worked with these sort of people. Drives me nuts. –  sevenseacat Feb 27 '11 at 12:59

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.

share|improve this answer

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.

share|improve this answer
1  
why do you commit that often, if it doesn't have a "natural" reason? –  user1249 Feb 26 '11 at 12:37

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.

share|improve this answer

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.

share|improve this answer

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?

share|improve this answer

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

share|improve this answer

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.

share|improve this answer

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

share|improve this answer

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.

share|improve this answer
2  
i'm not tempted to do that –  acidzombie24 Feb 26 '11 at 10:57

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.