Commitment Needs a Reason

25 August 2013

Modern version control systems automatically record useful information every time we make a commit:

What?

The difference (diff) of every file is automatically recorded, so we can see the additions and deletions in each commit.

Where?

Every commit tracks the location (files) of each change, so we know where the bodies are buried.

When?

Every commit is timestamped, so it’s easy to find things that were changed yesterday, last week or ten years ago.

Who?

Every commit is associated with a person, so we know who to ask about that confusing conditional.

Why?

The reason for making this change is the only thing a version control system can’t infer, so it’s the only piece of information that should ever go into a commit message.

Version control systems automatically record the ‘who’, ‘when’, ‘where’ and ‘what’ of every commit. Please, use the commit message to tell us why this change was made.

(Thanks to Antony and Andy for helping me understand these ideas and write useful commit messages.)