19

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

gnat
  • 21,442
  • 29
  • 112
  • 288
  • 3
    Don't bother, just say "blah" in the comment line. As long as you never share the code with anyone else and as long as no-one else will ever work on it and as long as you never need to rollback the code and as long as you never make a single code mistake and... wait a minute, why are you using version control again? – Michael Durrant Mar 12 '12 at 05:11

17 Answers17

57

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.

Peter Taylor
  • 4,012
  • 1
  • 24
  • 29
  • 38
    Well then he can read the 5,000 lines of spaghetti I just checked in, JEESH!!! Some people are just lazy! – Edward Strange Feb 26 '11 at 08:18
  • But rev. xyz isnt suppose to do anything. Its just the first part of rev.xyy which is the second part of rev. xyx which finally makes feature 649 complete however thats not active until glue 996 is committed. So why am i committing on a checkend that only has part of a feature rather then the 10th checkin that completes it? –  Feb 26 '11 at 08:55
  • 9
    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
  • @quickly_now: Alright, but, why should i comment every commit instead of writing "routine checkin, feature X, incomplete" on my 9th commit? (which is a day and a half apart from my last descriptive commit). –  Feb 26 '11 at 10:30
  • 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
  • 11
    @quickly_now, the poor sucker might even be yourself. Unfortunately this is one of the things you _must_ experience yourself to appreciate it fully. –  Feb 26 '11 at 14:55
  • 2
    @acidzombie - why are you checking in incomplete changes?? – Edward Strange Feb 26 '11 at 20:05
  • 2
    @Crazy Eddie, because DVCS affords you this flexibility. – Alex Budovski Feb 26 '11 at 23:19
  • 1
    @Crazy Eddie: What @Alex said ;). why wouldnt i commit a change i dont want to lose –  Feb 27 '11 at 00:42
  • 2
    @acidzombie - because you really should only be checking into a trunk if you've accomplished something. If you're committing just because you want a backup, use a branch. If it's your own personal branch then gibberish for a comment is your own problem. I wouldn't advise it, but nobody should care. Any commit to a trunk should be complete and have a descriptive comment. – Edward Strange Feb 27 '11 at 04:01
  • Not to forget that even you yourself can be that `poor maintainer` just few weeks/months down the line. – IsmailS Aug 01 '14 at 06:50
  • @iSid, user1249 beat you to that comment by 3.5 years. – Peter Taylor Aug 01 '14 at 08:34
  • @PeterTaylor Oh sorry! I should have read comments first before adding one. – IsmailS Aug 04 '14 at 10:37
35

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.

  • +1 for giving the answer I was going to give. Which is obviously the right answer. ;) – Jon Purdy Feb 26 '11 at 08:56
  • +1, the only answer i liked so far. I still think its a bit excessive, and why are there so many commits in one hour and a day or two with NO commits. I think it would look much uglier if commit rate was as consistent/frequent. Or at least it would be more ugly if it was as frequent as i commit –  Feb 26 '11 at 10:16
  • 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. –  Feb 26 '11 at 10:20
  • Thorbjørn: Actually, thats what i am saying. I only push every 4-12 commits which is a day or two of work and i write a fair message. But why should i write a message everytime! I think i agree with you. Also, from what i remember the team can see your commits msgs in commits before the push. –  Feb 26 '11 at 10:24
  • 2
    @acidzombie, why do you commit if you have not done enough changes to warrant a comment? Please explain. –  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. –  Feb 26 '11 at 23:10
  • @Thor, DVCS grants you this feature for free. You can use it to backup (and version) your code without inflicting it on others (until it's ready). – Alex Budovski Feb 26 '11 at 23:23
  • @Alex, if you don't "inflict" it on others what good is the backup? –  Feb 26 '11 at 23:30
  • 1
    @Thor, uhh, because it's backed up? Yet it doesn't break the build. Maybe you're thinking of only keeping it on your local harddisk. That's not what I mean. I mean pushing to your private mirror on some server somewhere. – Alex Budovski Feb 26 '11 at 23:39
  • @Thor - Agreed! I actually sell a backup system for windows machines which can do backup with past history versions of files. And for s/w the combination of this + version control has saved my life on a few occasions (frequently human error: Doh! Deleted a file I should not have.) – quickly_now Feb 27 '11 at 00:15
  • @Thor: Exactly what Alex said. It doesnt break the build and i like to SAVE the changes and not lose it. Isnt this the point of version control? not losing changes and going back when you did something silly like delete the wrong file. I push my repo for others when i do something significant but really, i'll commit every 2nd hour if i want to. –  Feb 27 '11 at 00:47
  • @Alex, now a private repository to backup your work on a regular basis? I sincerely believe you are doing manual labor making the VCS do things your operating system should do for you. I encourage you to investigate how Time Machine works under OS X. –  Feb 27 '11 at 07:29
  • @quickly_now. I am not doubting that version control is smart and you can retreive accidentially lost code. I am doubting you should use it as a backup system. –  Feb 27 '11 at 07:30
  • @Thor - I'm agreeing furiously with you. Using VCS for backup is a wrong use of the technology. It fill it with useless crap. – quickly_now Feb 27 '11 at 08:22
  • @quickly, @thor, I never intended to suggest you should use VCS as a general purpose backup system. I meant specifically for the use-case you mentioned, that is, code. – Alex Budovski Feb 27 '11 at 08:26
  • @Alex, did I say that? Using a VCS to keep backups of sub-commit changes, is band-aiding the inadequacy of the underlying operating system. –  Feb 27 '11 at 08:46
  • @acidzombie, if your VCS support aggregating commits (like git) it is fine. If it doesn't, you should work another way. –  Feb 27 '11 at 08:47
  • 1
    @Thor, that depends on your definition of a sub-commit change. I would argue that work-in-progress commits are just as valid, and a DVCS affords you this luxury. – Alex Budovski Feb 27 '11 at 10:29
  • @quickly: unless crap? Its text... even if 100% of the lines i change are modified again and again until i finish the feature my repo size wont grow. If it somehow gains 100mb of extra data... well even if a large team does it, a gb or a few gb can easily solve it. But that could only happen on a LARGE many man team –  Feb 27 '11 at 11:33
  • @Thor: About time machine... why should i use time machine instead of my DVSC? Why shouldnt i use time machine up until i finish a feature that may require 60 or more hours (say a complex state machine). –  Feb 27 '11 at 12:03
  • @acidzombie, use it because it works automatically as opposed to your manual checkin. Of course you could commit automatically with an empty message every time you save and get even better protection, but I am unaware of an IDE yet to allow doing this. –  Feb 27 '11 at 12:31
  • 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. – Adam Lear Feb 27 '11 at 15:28
  • VCS is not a backup system. Yes if you have a local server you can backup and push to that is separate from the central server that might be able to act as a backup. This would be like having a forked workflow as used in git hub. This is not a common version control workflow though and suggests your behaviour might be quite different for many. If there is a practise of bundling your code into a single set of diffs with annotations at the end of a feature you will work different to those who always push to a central server. – TafT Sep 03 '15 at 07:54
27

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.

Alex Budovski
  • 333
  • 2
  • 7
  • Good answer, i like it. I am a bit scared to use rebase. Here is an article about it going wrong and how to recover it http://www.bluemangolearning.com/blog/2009/03/recovering-from-a-disastrous-git-rebase-mistake/ –  Feb 27 '11 at 01:02
  • @acid, if you're rebasing your own private changes, there shouldn't be any conflicts. Besides, you have to try *hard* to lose anything in git. – Alex Budovski Feb 27 '11 at 02:35
  • Thats good to know and makes me feel a little better. –  Feb 27 '11 at 03:21
  • I cant believe some of the comments are telling me NOT to use source control... –  Feb 27 '11 at 12:03
  • 4
    my workflow, git rocks – Nazgob Feb 27 '11 at 12:50
  • So what is wrong with having a SVN mindset if you are actually using Subversion? – Boris Yankov Nov 02 '11 at 17:49
  • 1
    @Boris: Because he is clearly talking about git which is clearly NOT subversion –  Nov 02 '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. – Gort the Robot May 14 '12 at 19:45
  • OP asked about a generic version control reason for making commit messages. A specific workflow for a specific tool is ignoring people using any of the other VCS. There are also git workflows/workshops that suggest rebase should not be used to re-write history as it is remembered at the end because you loose the views of what was going on when it happened. – TafT Sep 03 '15 at 07:47
18

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.

Nicole
  • 28,111
  • 12
  • 95
  • 143
  • 1
    +1, sounds like he is committing too frequently or at bad stopping points. If he just wants a good back-up point for some experimental changes, he can use the index, a temporary branch, amend previous commits instead of creating new ones, or even use the undo buffer in his editor. – Karl Bielefeldt Feb 26 '11 at 09:29
  • 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. –  Feb 26 '11 at 10:02
  • Actually i may hold off until i get some basic test in because otherwise, if i comment every commit how would i know which of these has a stable reflection? 'reflection basics', 'reflection serializing' 'reflection serialize test' Assuming serializing is a must it could be the 2nd or the 3rd. Test could mean unit test or test can mean testing if its working on the basic classes i require. I just think commenting makes sense when i can say 'reflection working basics' rather then guess which of these actually mean the basics are working. Also its easier to skim/find when theres less to read. –  Feb 26 '11 at 10:11
  • @acid, the entire purpose of a commit is to be able to revert back to it or compare changes with it. If you ever need to do that with your earlier commits, how do you know which one to choose? You don't have to write novels, here. "interface working," "serialization working," and "reflection working" are just fine in my opinion. There isn't a fixed maximum number of commits per day, but if your messages would read like "some work on interface" "some more work on interface" "interface almost done", then you're committing too often and should just use the index. – Karl Bielefeldt Feb 26 '11 at 10:18
  • @Karl: Whats the index btw? i know git has a stash but i dont think your talking about that. What does it do? –  Feb 26 '11 at 10:20
  • @acid, the index is where files are after a `git add` but before a `git commit`. It's useful to add files if you want to be able to see what you changed since a certain point, but don't feel that point is good for a full commit yet. – Karl Bielefeldt Feb 26 '11 at 10:23
  • Karl: hmm, sounds good but, if i need to revert i cant because it isnt committed? What i do is commit locally then push after every 4-12commits when something noteworthy happens (a day - a day and a half of work usually). –  Feb 26 '11 at 10:27
12

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.

Scant Roger
  • 9,038
  • 2
  • 29
  • 47
  • 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
  • 2
    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
11

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

Tim Abell
  • 205
  • 1
  • 7
Rook
  • 19,861
  • 9
  • 53
  • 96
9

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

Edward Strange
  • 9,172
  • 2
  • 36
  • 48
  • 7
    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
  • @quickly_now, _agony_ even? Is your code *that* bad? –  Feb 26 '11 at 12:36
  • 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
  • Oh yes. I agree too. I think of it as experience == humility. – Michael Durrant Mar 12 '12 at 05:16
9

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.

stijn
  • 4,108
  • 1
  • 25
  • 31
5

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.

EricSchaefer
  • 2,091
  • 1
  • 17
  • 30
4

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.

Inca
  • 1,534
  • 10
  • 11
4

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

Richard Harrison
  • 283
  • 1
  • 3
  • 1
    exactly. Even if (as mentioned earlier) it's just code you 'dont want to redo' well obviously it means something therefore it shouldn't be hard to write a super-quick summary of it. – sevenseacat Feb 27 '11 at 13:01
3

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.

GG01
  • 201
  • 1
  • 5
  • Why should i do this during every commit instead of at the end of the day, every other day or when i finish a feature? –  Feb 26 '11 at 08:52
  • 1
    why do you commit that often, if it doesn't have a "natural" reason? –  Feb 26 '11 at 12:37
  • I commit whenever I make some significant changes, so it can be reflected in repository and other developers can checking those changes. But the answer you gave it helps to have an bird eye on what is done by whom and when. – GG01 Feb 26 '11 at 17:05
  • @acidzombie24 Well, don't commit half finished stuff unless you really have to. And so the other people can see what you're doing/working on when you call in sick one day and nothing works. Or so you can remember where you left off when you have to sit in meetings for 2 days. Or so you more easily pinpoint which revision broke a build and look at the diff. – nos Feb 26 '11 at 22:54
  • @Thorbjørn: Why wouldnt i commit a change i dont want to redo? –  Feb 27 '11 at 00:44
2

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.

Sparky
  • 3,055
  • 18
  • 18
2

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?

  • One glance at my incredibly obvious code and they will know instantly everything that it does and all the amazing tests it passes 100%. Sorry, I'm in a humor mood tonight [so I'm KIDDING] ;) – Michael Durrant Mar 12 '12 at 05:20
1

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.

Joris Geer
  • 109
  • 1
1

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.

Mahesh Velaga
  • 151
  • 4
1

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

talonx
  • 2,762
  • 2
  • 23
  • 32