62

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?

Improve this question
0

11 Answers 11

Reset to default
89

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.

Improve this answer
4
  • 5
    It should also talk about why. What other options did you consider, and why did you choose this one?
    – Jay Bazuzi
    Apr 27, 2012 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, 2012 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, 2012 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, 2012 at 21:21
66

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

Improve this answer
1
  • OP said: if a change *doesn't* span multiple files. So you suggest to not include the filename, ever? Not even if the commit is specific to the file only – say, a syntax error bugfix? I feel this answer is too narrowly considered, as that would make e.g. git log pretty much illegible
    – phil294
    May 17, 2020 at 12:38
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).

Improve this answer
4
  • How do you commit a refactoring change, then?
    – Jules
    Jun 9, 2016 at 19:42
  • @Jules refactoring has a ticket # that is never finished
    – Caleth
    Jun 10, 2016 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, 2016 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, 2016 at 21:32
5

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.

Improve this answer
4

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.

Improve this answer
4

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

Improve this answer
1

If you can include the verb that the file is representative of for e.g slideDesigner: fixed funcX(), returns obj instead of the actual fileName (e.g slide-designer.vue or main-slide-designer) its much better.

In the end there is no hard/fast rule you should follow, it's boils down to what you are comfortable and confident with. IMHO, if I include the term slideDesigner rather than just fixed funcX(), returns obj it makes the commit history more usable to me and I am more likely to further research the actual files in that commit for I know beforeHand of a context (slideDesigner) for my mind to constructively relate to the problem I am currently dealing with.

Thanks.

Improve this answer
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.

Improve this answer
0

Look at how easy or difficult it is to figure out which files a commit modified and/or how easy it is to figure out the list of commits modifying a file. Then base your decision on your findings. Your setup may be different from mine.

(For example, the Xcode editor has a “history” button which shows two versions side by side with a diff, and you can pick commits for either side. Pointless to have the file mentioned in the commit message. Unless the change is something like “fix outdated comments xyz.cpp”. )

Improve this answer
-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.

Improve this answer
-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

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

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