Chapter 2: Git, GitHub and Git Bash

2.11 Commit message hygiene

By Ravindra Bagale · Last updated: 25 October 2026

Why: the problem

Open the history of a messy project and you see messages like "fix", "changes", "final" and "asdf". Now imagine an outage at Paytm and you must find the commit that changed the payment timeout. These messages tell you nothing. Good commit messages are a gift to your team and to yourself six months later. Reviewers read the message before the code. Tools also read messages: Jira links issues from them, release tools build notes from them, and some teams block pushes with bad messages. In this lesson you will learn a simple shape: a short subject in the imperative mood, a blank line, and a body that says why. You will also learn Conventional Commits, used by many open source projects, and you will set up a commit template and a hook that rejects bad messages.

What we will build

You will rewrite bad messages into good ones, write a multi-line commit with a body and an issue key, create a commit template, and add a commit-msg hook that blocks messages like "fix".

What: every term in plain English

• Subject line — The first line. Short, 50 characters or less, no full stop.
• Imperative mood — Write like a command: Add, Fix, Remove. "Add cart test", not "Added".
• Body — Lines after a blank line that explain why and what changed.
• Issue key — A ticket ID like SHOP-142 that links the commit to Jira.
• Conventional Commits — A style: type(scope): subject, like fix(cart): round price.
• Commit template — A file Git shows when you write a message.
• commit-msg hook — A script that checks the message before the commit is saved.
• Atomic commit — One commit, one logical change.

How: step by step

1. See bad messages

   git log --oneline -5
   

   What it does: Notice vague words.

   Output

   a1 fix
   b2 changes
   c3 final
   

2. Write a good subject

   git commit --allow-empty -m "Fix cart total rounding for 0.5 paise"
   

   What it does: Command style, clear and short.

   Output

   [main d4] Fix cart total rounding for 0.5 paise
   

3. Write a subject and body

   git commit --allow-empty -m "Raise payment timeout to 10s" -m "Bank API p99 is 7s at lunch peak. 5s caused failed orders. Refs SHOP-142."
   

   What it does: Two -m flags: subject and body.

   Output

   [main e5] Raise payment timeout to 10s
   

4. Read it

   git log -1
   

   What it does: The body explains why.

   Output

   Raise payment timeout to 10s
   
   Bank API p99 is 7s at lunch peak. 5s caused failed orders. Refs SHOP-142.
   

5. Create a template

   nano ~/.gitmessage
   

   What it does: Paste the template from Example 2.

   Output

   (file saved)
   

6. Use the template

   git config --global commit.template ~/.gitmessage
   

   What it does: git commit without -m now shows it.

   Output

   (no output)
   

7. Check subject lengths

   git log --format="%s" -10 | awk '{ print length, $0 }'
   

   What it does: Find long subjects.

   Output

   38 Raise payment timeout to 10s
   

Example 1: Rewrite five bad messages

Stack. Git

Goal. Rewrite five bad messages.

before-after.txt

BAD: fix
GOOD: Fix 500 error on /health when DB is down

BAD: changes
GOOD: Add Redis cache for menu API

BAD: final version
GOOD: Bump app version to 1.4.0

BAD: updated file
GOOD: Remove unused payment retry flag

BAD: Added the new feature for discount and also fixed bug
GOOD (two commits):
  Add 10% festival discount to cart
  Fix discount applied twice on refresh

What each line does

• Fix 500 error ... — Says what and where.
• Add Redis cache ... — Starts with a verb.
• Bump app version — A common verb for versions.
• Remove unused ... — Clear about deletion.
• Two commits — One idea per commit.

Green output

$ git log --oneline -3
f6 Fix discount applied twice on refresh
e5 Add 10% festival discount to cart
d4 Bump app version to 1.4.0

Expected result. The log now reads like a changelog.

Example 2: A team commit template

Stack. Git

Goal. A team commit template.

~/.gitmessage

# Subject: imperative, max 50 chars, no full stop
# Example: Fix cart total rounding

# Body: why is this change needed? what changed?

# Ticket: SHOP-123

What each line does

• Lines with # — Comments; Git removes them.
• Subject hint — Reminds the shape.
• Body hint — Asks why.
• Ticket — Link to Jira.

Green output

$ git commit
(nano opens with the template)
[main a7] Add order id to payment logs

Expected result. Everyone writes the same shape without thinking.

Example 3: Block bad messages with a commit-msg hook

Stack. Git hooks, Bash

Goal. Block bad messages with a commit-msg hook.

.git/hooks/commit-msg

#!/usr/bin/env bash
msg=$(head -1 "$1")
if [ ${#msg} -gt 72 ]; then
  echo "Subject too long (${#msg} chars). Keep it under 72."; exit 1
fi
case "$msg" in
  fix|changes|update|wip|final|asdf)
    echo "Message too vague: '$msg'. Say what you changed."; exit 1;;
esac
exit 0

test.sh

chmod 755 .git/hooks/commit-msg
git commit --allow-empty -m "fix"
git commit --allow-empty -m "Fix login redirect after OTP"

What each line does

• head -1 "$1" — Git passes the message file as $1.
• ${#msg} -gt 72 — Length check.
• case ... esac — Reject vague words.
• exit 1 — Stops the commit.

Green output

Message too vague: 'fix'. Say what you changed.
[main b8] Fix login redirect after OTP

Expected result. The hook teaches the team good habits automatically.

Example 4: Use Conventional Commits to build release notes

Stack. Git

Goal. Use Conventional Commits to build release notes.

conventional.sh

git commit --allow-empty -qm "feat(cart): add festival discount"
git commit --allow-empty -qm "fix(payment): retry once on bank timeout"
git commit --allow-empty -qm "docs(readme): add run steps"
echo "## Features";  git log --format="- %s" -3 --grep="^feat"
echo "## Fixes";     git log --format="- %s" -3 --grep="^fix"

What each line does

• feat(cart): — A new feature in the cart area.
• fix(payment): — A bug fix in payments.
• docs(readme): — Documentation only.
• --grep="^feat" — Pick only feature commits.

Green output

## Features
- feat(cart): add festival discount
## Fixes
- fix(payment): retry once on bank timeout

Expected result. Release tools such as semantic-release read these prefixes to choose the next version.

Verify: did it work?

1. Check last subjects

   git log --format="%s" -5
   

   What it does: All start with a verb or type.

   Output

   feat(cart): add festival discount
   

2. Check template set

   git config --global commit.template
   

   What it does: Path printed.

   Output

   /home/ravi/.gitmessage
   

3. Hook works

   git commit --allow-empty -m wip; echo $?
   

   What it does: Exit code 1.

   Output

   Message too vague: 'wip'. Say what you changed.
   1
   

When it is red 1

Message too vague: 'fix'. Say what you changed.

Cause. The hook blocked your message.

Fix, step by step

1. Write what and where: Fix null price in cart API.

When it is red 2

Subject too long (95 chars). Keep it under 72.

Cause. Too much in the subject.

Fix, step by step

1. Move details to the body with a second -m.

When it is red 3

remote: GitLab: Commit message does not follow the pattern '^(feat|fix|docs)'

Cause. The server has a push rule for messages.

Fix, step by step

1. git commit --amend -m "fix(cart): ..." for the last commit.
2. For older ones, git rebase -i and reword. Only if not shared.

Cleanup

1. Remove the hook

   rm .git/hooks/commit-msg
   

   What it does: Only in the lab repo.

   Output

   (no output)
   

Practice tasks

Homework: try at home

Recap

• Short imperative subject, blank line, body with why.
• Add the ticket key.
• One idea per commit.
• Conventional Commits help release notes.
• Templates and hooks keep the team consistent.

FAQ

Do I need a body every time?

No. Small changes can be subject only.

Is Conventional Commits required?

Only if your team uses it. Follow team rules.

Can I fix an old message?

Yes with git rebase -i reword, only on unpushed commits.

English or Marathi messages?

English, so everyone in the company can read them.

Can GitLab enforce messages?

Yes, with push rules in project settings.

Interview questions

1. What makes a good commit message?

   A short imperative subject, a blank line, and a body explaining why, plus a ticket key.

2. Why does imperative mood matter?

   It matches Git's own messages like Merge branch and reads as what the commit will do.

3. What are Conventional Commits?

   A format type(scope): subject that tools use for changelogs and versions.

4. How do you enforce message rules?

   commit-msg hooks locally and push rules or CI checks on the server.

5. How do you change the last message?

   git commit --amend -m "new message" before push.

Samajla ka?

Ravi Sir's Cards for this lesson

Revision cardInterview card

मराठी cards