49

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?

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

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

84

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.

  • 5
    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
59

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

30

Don't forget to add TICKET/ISSUE NUMBER .

If you have any feature 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 to make sure that the first 7 digits of the comment was a valid issue number from clear quest (our issue/feature tracking system).

  • How do you commit a refactoring change, then? – Jules Jun 9 '16 at 19:42
  • @Jules refactoring has a ticket # that is never finished – Caleth Jun 10 '16 at 8:47
  • @Jules one methodology is that refactoring is tracked as a "chore" kind of issue and so it has an issue number too. – Scott McIntyre Nov 11 '16 at 3:25
  • @ScottMcIntyre While this may be true, I'm not convinced it's a good idea. Refactoring is frequently best performed opportunistically, or as part of the process of developing code that relies on the code to be refactored. As Fowler puts it, "Planned refactoring is [...] a sign that the team hasn't done enough refactoring using the other workflows". Or more bluntly by Ron Jeffries: Refactoring -- Not on the backlog!. – Jules Nov 11 '16 at 21:32
3

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.

3

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

0

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.

0

I want to add a different perspective here.

My Answer is Yes Or No. But Generally I would say Yes.

Version control is indeed powerful enough to know which file is being updated. But, when we do

$ git log

We only see the commit message. That what most people do.

By looking into the log itself. It adds additional context to it. For example:

readme.md: Fix typo detected by language tool

Is better than

Fix typo detected by language tool

However, if the changes spawn multiple files, then at least mention the component that is being edited.

API: Fix reset password not sent email to user

By reading it, we know that the error being fixed is at the API component, and it probably under API directory at the code base.

We could however do

$ git show COMMIT_ID --name-only 

but it adds more step just to get the files.

-1

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.

-2

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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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