Commit Hygiene

One logical change per commit

• Each commit does one thing and leaves the project in a working state.
• Do not mix refactoring, formatting and behaviour changes in the same commit.
• Use git add -p to stage only some of the changes in a file.

A good message

Add retry to payment client

The payment API sometimes returns 503 during deployments. Retry
idempotent requests up to three times with backoff instead of
failing the customer's checkout.

• Subject line: imperative mood (“Add”, “Fix”, “Remove”), about 50 characters, no trailing period.
• Blank line, then an optional body wrapped at about 72 characters.
• The body explains why the change was made and anything non-obvious. The diff already shows what changed.
• Follow your team’s conventions, such as ticket numbers or Conventional Commits prefixes like feat: and fix:.

What to avoid

• Vague messages such as “fix”, “changes” or “wip” on shared branches.
• Committing secrets, generated files or commented-out code.
• Huge commits that nobody can review.

Tidying before you share

Until you push, your commits are private and can be improved:

git commit --amend       # fix the last commit's message or add a forgotten file
git rebase -i HEAD~3     # reorder, reword or squash your last three commits

Do not rewrite commits that others have already pulled.

Try it

Look at git log --oneline in a project you work on. Could a stranger tell what happened and why? Rewrite the message of your last unpushed commit with git commit --amend.