Git Best Practice

Commit Contents

  • Don’t do multiple things in one commit, use multiple commits for that.
  • Do commits as atomically as possible (or: as atomically as it still makes sense/is reasonable; giant commits as well as micro-commiting doesn’t make any sense).
  • Rule of thumb: each commit should be revertable as-is and by itself. Means: if you commit something and someone else needs to revert that commit, s/he should need to only revert that commit and not split it or edit anything else in order to do that.

Generally, the documentation about SubmittingPatches is reasonable too.

Commit Messages

Commit messages should consist of two parts:

  • always use signed-off lines in commits and sign them with your PGP key git commit -a -s -S.
  • one sentence on the first line (doesn’t matter how long/as many words as you want):
    • give a broad idea about what got changed and why it was changed (not a detailed of the what since that is visible in the diff).
  • any additional/technical/in-depth details go into one or more paragraphs after the first sentence:
    • broader explenation(s) why something was done the way it was done (especially if it’s not obvious or has a back history).
    • optionally some information who was involved/helped/debugged, links to further information etc.
  • since git commits should be revertable by its own, you should have commit messages that are unique:
    • e.g. if you’re updating copyright notices, don’t use “Updating copyright notices.” since this is a reoccuring task, use “Updating copyright notices for 2014.” instead.