Stop Wrecking Your Git History


Git is a beautiful tool - and you’re probably using it like a blindfolded intern with sudo on prod.

We’ve all scrolled through a repo and found commits like:

fix
final_fix
pls_work
oops
update

Congrats, you just caused a future postmortem. Let’s fix that, before I rm -rf your repository.


Make Atomic Commits

Each commit should do one thing. Not three unrelated things, not “misc infra fixes lol”.

Do:

  • Update one Puppet module
  • Fix one broken Ansible role
  • Rotate one secret

Don’t:

  • Update half the VPC, refactor DNS, and “accidentally” nuke the OpenShift cluster in the same commit

Small, focused commits make rollbacks easy. If you blow up production, you’ll want a single rollback, not a full forensic investigation.


One Bad Commit Title Away from Termination

Your title is what pops up in Teams right before the incident channel is created. Make it obvious enough that people don’t have to @you with “wtf did you just push?”.

Add a Tag

You might want to use the tech name or application as a tag so everyone instantly knows what’s broken or being touched:

[terraform] Stop recreating every VM
[s3] Add logs bucket (pls no public access)
[jenkins] Remove ancient Jenkinsfile we all hate
[applicationX] Set java maxmetaspace to a a sane limit

This way, you don’t have to decode which system is screaming in Teams - it’s right there in the tag.

Imperative Mood

Not “I did this,” just tell Git what to do:

Good: Fix DNS typo for prod zone

Bad: fixed dns maybe idk


Actually Explain Yourself

“Why did you touch this?” is not optional. Your co-workers - and future on-call you at 3 AM, coffee-fueled and angry - will want answers.

  • Why: what was broken, what ticket is screaming for attention
  • What: exactly what you have changed, so someone can undo your mess without summoning a voodoo priest

Example of a useful commit:

[prometheus] Don’t Wake the OOMkiller

This tweak helps avoid catastrophic memory tantrums
that would otherwise force the kernel’s OOMkiller to
step in. Think of it like giving Go a polite nudge before it
decides to redecorate your process space. It’s a soft limit -
Go might still ignore you, but at least it’s less dramatic.

The alternative, “lol blame Prom” is great… Because nothing says fun like explaining to the team why monitoring made things worse.


Don’t Make a Rebase/Merge Crime Scene

Rebasing and merging are tools, not excuses to turn your history into spaghetti.

  • Don’t rebase shared branches unless you enjoy breaking your teammates’ workflows
  • Don’t merge half-baked infra changes into main (or master - because why not) unless you love outages

Commit Messages We’ve All Seen

You know these, I know these:

bring prod back online
fixup! revert revert revert
YOLO deploy
ok it actually works now

Funny now. Less funny during the mayhem.


TL;DR

Good commits are:

  • Small (one blast radius)
  • Clear (title that won’t get you called)
  • Helpful (body that explains why it blew up)
  • Clean (no cursed merge histories)

Your Git history is your incident report log. Write it like you don’t want to be the punchline at the next team event.