Multi-line Commit Body
Learn how to write effective multi-line commit message bodies. Covers when to add a body, how to structure it, line wrapping at 72 characters, and best practices.
Detailed Explanation
Writing Effective Commit Message Bodies
The body of a commit message is where you explain the why behind a change. While the subject line describes what changed, the body provides context, motivation, and details that help future developers (including your future self) understand the reasoning.
When to Add a Body
Add a body when:
- The change is not self-explanatory from the subject line
- There is important context or motivation to document
- The commit fixes a non-obvious bug that could recur
- You want to explain why this approach was chosen over alternatives
- The commit affects multiple files or systems
Format Rules
- Separate the subject from the body with a blank line
- Wrap body lines at 72 characters
- Use the body to explain what and why, not how
Example
fix(parser): handle escaped quotes in JSON strings
The previous regex-based parser failed when processing
JSON strings containing escaped double quotes (\").
This caused a parse error for any configuration file
with file paths or regex patterns containing quotes.
Replace the regex with a character-by-character state
machine that properly tracks escape sequences. This
approach is also ~30% faster for large inputs.
Closes #789
Structuring the Body
A good body follows this pattern:
- Paragraph 1: What was the problem or motivation?
- Paragraph 2: What approach did you take and why?
- Paragraph 3 (optional): What alternatives were considered?
- Footer: Issue references, co-authors, etc.
The 72-Character Rule
Git recommends wrapping body lines at 72 characters because:
git logindents output by 4 spaces- 72 + 4 = 76, which fits in 80-column terminals
- It ensures consistent readability across tools
- Many Git hosting platforms render commits with this assumption
Bullet Points in Bodies
You can use bullet points for lists:
refactor: reorganize project directory structure
- Move all API routes from /routes to /api
- Extract shared middleware into /middleware
- Consolidate database models in /models
- Update import paths across all files
Use Case
You have fixed a subtle parsing bug that took significant investigation to diagnose. The fix involves replacing a regex-based approach with a state machine. You want to document the root cause and the reasoning behind the new approach so that future maintainers understand why the code is written this way.