I have noticed that I recently wrote the following commit message:

Since HTML changed, getting the index would always result in zero, since the element is now enclosed in a parent block.

For someone who starts by viewing the diff of the commit commit first (for instance after doing a blame on a file) and doesn't get the purpose of the change, this message is helpful:

  • It tells why the change within the commit was done, not what was the change (a diff would tell what the change actually is).

  • It explains the larger picture, the context in which the commit was done.

However, for someone who is simply browsing the log, the message is absolutely cryptic. What HTML? What index? What parent block? What the heck is happening here? In order to figure this out, the person should need to diff the changes, and only then she will understand the message. It doesn't even matter if the person knows the project; I'm pretty sure I won't be able to explain the message myself in a week without consulting the diff results.


Should a log message of a commit be explicit by itself, without requiring a developer to explore the diff in order to understand it?


IMHO, no. Sometimes, a commit is just too large to be explained in enough detail in the message, for it not to require exploring the 'diff'.

However, I would change the why to a what (described in broad strokes). This way, a developer can get a good idea of what was affected by that commit, and only have to explore the diff if they really want to go into detail.

As for the why, if you're using some sort of bug tracking system, I would reference the issue number in the commit message. If not (unlikely), it's best to mention the why in broad strokes as well.

  • "Sometimes, a commit is just too large": doesn't it defeat the purpose of a commit (and a version control system in general)? – Arseni Mourzenko Jul 23 '16 at 23:23
  • 1
    @MainMa Merge commits can be very large even if its parts are small. – Doval Jul 23 '16 at 23:57
  • 1
    @Doval: valid point. – Arseni Mourzenko Jul 23 '16 at 23:58
  • +1 for changing from "why" to "what", and then add some reference to a bug tracking system, which explains the why. – Niklas H Aug 23 '16 at 7:29

The git mantra states

commit often

Commits shouldn't be done after a complete module have been coded. Commits should be done after changes that work and add something organic no the goal of the project.

If you abide to that mantra and commit often and write a clear commit message, then such message should be a clear enough indicator of what was affected by the commit.

Nonetheless you will often have to issue a diff command to see the changes in context.

Bottom line:

Both commit messages and diffs complement each other and each one has its purpose.

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.