Chapter 3: Version control

A history is only a paper trail if someone can read it. The diff says what changed. Nothing else can say why.

Commit message

Also called Conventional Commits

The note attached to a commit. Its first line says what changed, short enough to read in a list, and the body says why. Conventional Commits is a common format for that first line: fix(cart): stop charging VAT twice.

The next session's agent starts knowing nothing and reads git log to catch up, so this is the memory you leave it. It also matters for you: a message giving a real reason shows you understood the change, and "fix stuff" shows nothing. An agent will write vague ones unless told otherwise.

Say it to your agent

“Write the message as type(scope): subject. In the body, say why this change was needed and what you ruled out, not what the diff already shows. Never write "fix bug" or "update code".”

The workshop

Name a word, or describe what you mean in everyday language.