Writing Good Git Commits

Let's talk about git commit messages & why they're important.

If you're like me, when you've been adding a feature or fixing a bug, you've come across some code that the you from 3 months ago wrote and you're scratching your head. "What the hell was I thinking?" you ask yourself.

You take a look at the git blame only to find the last time you touched that block of code, you left yourself the note "add invites". You don't know why you added them and the commit spanned across your entire stack so the diff is huge. "If only I would have taken the time then, to make this easier to understand now", you say before diving right into the code and start tearing it out.

Writing good commit messages can turn your codebase from the Rohonc Codex 🧐 into an Indiana Jones-level treasure map 🤩. Here are a few suggestions to write a better git commit history and to help your future self:

1. Add structure

Make it easy to scan to get the scope of the change in one line. The angular commit format is great for capturing a lot of detail in a compact format:

✅ “feat(invites): Add invites to athletes page”

2. Lead with Why

Why defines the problem being solved by the commit.

✅ “We need to give race organizers a way to quickly invite more athletes to their event and athletes a way to easily join events they've been invited to.”

3. Follow with What

What describes, in terms the codebase uses, how the problem was solved by the commit

✅ “Added a migration to add the invite_code field to a race. Added a inviteCode field to the Race GraphQL type. Added some behavior to generate an invite code for a race when it is created. Added a button & popover to the race athletes page that allows an athlete to copy the invite link and send it to their friends.”

4. What dos & donts

Don't write about what the commit’s diff clearly shows (files changed, code changes, etc)

🚫 “We updated race-schema.js & RaceAthletesPage.ts and updated the build-router function…”

Do write in terms of the domain

✅ “We added a inviteCode field to Race & to the query on the race page"

5. Changes are causal graphs

Writing a good “what” is like writing a story. Changes to your code are causal graphs and so are stories. Instead of our previous "What" example, let's try describing the change as it unfolded:

🏆 "In order to support creating a unique link as an invite link for a race, we need to add the notion of an invite code. To associate an invite code with a race, we added a field to the races table in the database. After that, we were able to begin generating one upon creation of a race. Then..."

📝 The final product:

feat(invites): Add invites to athletes page

Why:
We need to give race organizers a way to quickly invite more athletes to their event and athletes a way to easily join events they've been invited to.

What:
In order to support creating a unique link as an invite link for a race, we need to add the notion of an invite code. To associate an invite code with a race, we added a field to the races table in the database. After that, we were able to begin generating one upon creation of a race. Then...

There you have it. You can quickly understand the scope of the change, why you made it and the story behind what was changed to support the invites feature.

I hope you found some of this advice helpful. Happy git committing!