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.

In the first line of a git commit message I have a habit of mentioning the file that modified if a change doesn't span multiple files, for example:

Add [somefunc] to [somefile] 

Is this a good thing to do or is it unnecessary?

share|improve this question

migrated from stackoverflow.com Apr 26 '12 at 16:47

This question came from our site for professional and enthusiast programmers.

add comment

8 Answers

up vote 55 down vote accepted

Version control tools are powerful enough to let the person see what files were modified, and what methods were added. It means that in general, log messages which plainly duplicate what already exists are polluting the log.

You added somefunc method to fulfill a requirement, i.e.:

  • to add a feature,
  • to remove a bug or
  • to refactor the source code.

This means that your log messages must rather explain what features/bugs were affected or what was the purpose of the refactoring.

share|improve this answer
4  
It should also talk about why. What other options did you consider, and why did you choose this one? –  Jay Bazuzi Apr 27 '12 at 2:50
2  
I comment on commits the same way as I would comment code, just from a higher level perspective (ie, less info, more summarization). Personally, I break it down to a file/module level (in git) but only because commits are cheap up-front and I like being able to read the history like a book. YMMV. –  Evan Plaice Apr 27 '12 at 7:23
1  
If for some reason the person commits a bunch of files at once that aren't related to the same bug I prefer them to list the file names and bug id before the summery. I don't need to know file.cpp: added getMethod(), but I would like bug id #10 file.cpp: decent summery here. If they do commit a bunch of files that are spread over multiple bug reports we'll have a talk though, because I don't really like that. I'd much rather they make multiple commits. One for each issue they're resolving. –  William Apr 27 '12 at 18:03
    
@William: Also, in case there's a problem with one bug fix, it's possible to revert it with minimum fuss. Combine ten bug fixes in one commit, and that can be a serious problem. –  David Thornley Apr 27 '12 at 21:21
add comment

No. There are plenty of ways to examine the contents of a commit. The comment should describe the purpose of the commit.

share|improve this answer
add comment

I like the answer from Mainma.

I would like to add one more point: issue #

if you have any feature tracking or issue tracking system with a ticket# or issue #, be sure to put that ID# in the commit. That will help anyone who wants to know more about the feature or issue that you were working on.

In my last project, there was a macro which was developed which made sure that the first 7 digits of the comment is a valid issue number from clear quest (our issue/feature tracking system).

share|improve this answer
add comment

I do that type of thing when I'm committing e.g. the fix for a defect that required changes to multiple files. This makes it a bit easier to tell what actually changed without looking at individual files in the changeset.

For single file changesets, this is unnecessary.

The first line is always a high-level description of the changeset, like a link to the defect or user story.

share|improve this answer
add comment

If it's relevant information in the narrative of the commit message, then yes, include it. If the only bit of information is the filename itself, then no.

For example this make sense: "Moved the build_foo() function from fooutil.c to foobase.c, since most programs that want to use build_foo() are already including foobase.c"

This one doesn't: "Updated the build_foo() in fooutil.c to take a bar parameter."

share|improve this answer
add comment

The only time I could see this being useful for a single file checkin is if you've made changes to a function used in many places within the file with the result that the diff is cluttered. Even then I'd put the change tracker # and a plain text description of the change first.

share|improve this answer
add comment

I think the real question here is how limited in scope are your commits? If you wait to commit a variety of unrelated changes together in one commit, then you might feel the need to specify what files were changed for what purpose.

However, if you simply made more narrow commits more frequently, then a single commit would explain which files were modified and you could simply describe what the purpose was in the message.

More commits, more often. That's the way you can avoid being so verbose in your messages.

share|improve this answer
add comment

It shouldn't

Everybody who is interested can see changes in a history

It's also not feasible in larger systems as many files might be auto generated

share|improve this answer
add comment

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.