Skip to main content

Why Commit Messages Matter

When you push to gitGost, your commit message becomes the PR description. Since you’re contributing anonymously, you can’t edit the PR or add comments to provide context—the commit message is your only voice.
Your commit message is the only way to explain your changes to maintainers. Make it clear, detailed, and professional.

Commit Message Anatomy

A well-structured commit message has three parts:
<type>: <short summary>

<detailed explanation>

<additional context>

Example

git commit -m "fix: correct API timeout handling in HTTP client

The previous timeout of 5 seconds was too short for slow networks,
causing unnecessary request failures. This commit increases the 
timeout to 30 seconds and adds exponential backoff for retries.

Tested with simulated network delays of 10-25 seconds.
Fixes issue with API calls failing on 3G connections."
This becomes the PR description:
Anonymous contribution via gitGost
fix: correct API timeout handling in HTTP client The previous timeout of 5 seconds was too short for slow networks, causing unnecessary request failures. This commit increases the timeout to 30 seconds and adds exponential backoff for retries. Tested with simulated network delays of 10-25 seconds. Fixes issue with API calls failing on 3G connections.

This is an anonymous contribution made via gitGost.

The First Line: Short Summary

The first line is critical—it appears in:
  • Git logs
  • GitHub PR titles
  • Email notifications
  • Commit lists

Best Practices

1

Use a type prefix

Start with a conventional commit type:
  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation only
  • style: - Formatting, whitespace
  • refactor: - Code restructuring
  • test: - Adding/updating tests
  • chore: - Build, dependencies
# Good
feat: add dark mode support
fix: resolve memory leak in cache
docs: update API examples

# Bad (no type)
Added dark mode
Memory leak fixed
2

Keep it under 50 characters

GitHub truncates long summaries:
# Good (45 chars)
fix: correct GPIO pin mapping in BCM2835 driver

# Bad (78 chars)
fix: correct the GPIO pin mapping in the BCM2835 driver for Raspberry Pi boards
Use git log --oneline locally to preview how your summary appears.
3

Use imperative mood

Write as if commanding the codebase:
# Good (imperative)
fix: add validation for empty input
refactor: extract common utility functions

# Bad (past tense)
fix: added validation for empty input
refactor: extracted common utility functions

# Bad (present tense)
fix: adds validation for empty input
Think: “This commit will add validation…”
4

Don't end with a period

# Good
feat: implement user authentication

# Bad
feat: implement user authentication.

The Body: Detailed Explanation

After a blank line, write a detailed explanation:

What to Include

Explain why this change is necessary:
fix: increase API request timeout

The default timeout of 5s was causing failures on slow networks.
Users on 3G connections or behind corporate proxies were seeing
frequent request failures, especially during peak hours.

This commit increases the timeout to 30s and adds retry logic
with exponential backoff (1s, 2s, 4s, 8s).
Describe testing steps:
test: add integration tests for payment flow

Added end-to-end tests covering:
- Successful payment processing
- Card declined scenarios
- Network timeout handling
- Duplicate transaction prevention

All tests pass with 100% coverage of payment module.
Run with: npm test -- payment.test.js
Mention limitations:
refactor: switch to new config parser

Migrates from YAML to TOML for configuration files.
The new parser is 3x faster and has better error messages.

Note: This breaks compatibility with YAML configs.
Users need to migrate using: ./scripts/migrate-config.sh

Format Guidelines

  • Wrap at 72 characters per line
  • Use blank lines between paragraphs
  • Use bullet points for lists
  • Be specific, not vague

Examples: Good vs. Bad

Example 1: Bug Fix

fix: bug

Example 2: New Feature

Added new feature

Example 3: Documentation

docs: updated README

Anonymous Contribution Tips

Since you’re contributing anonymously, avoid revealing your identity:

❌ Don’t Include

  • Personal names or usernames
  • Company names or projects
  • Email addresses
  • Timezone references (“I pushed this at 3am”)
  • Personal anecdotes (“This always annoys me”)

✅ Do Include

  • Technical rationale
  • Objective testing results
  • Links to public documentation
  • Neutral language

Bad Example (Reveals Identity)

fix: update API endpoint

At AcmeCorp, we noticed this endpoint was broken.
I've been using this library for 5 years and this
always bugged me. Finally got around to fixing it!

Tested on our internal systems.
Problems:
  • Mentions company name (“AcmeCorp”)
  • Uses “I” and “me” (personal)
  • References internal systems

Good Example (Anonymous)

fix: correct response format in /api/status endpoint

The endpoint was returning HTTP 200 with an error message
in the body instead of using proper HTTP error codes.

Now returns:
- 200 OK: service healthy
- 503 Service Unavailable: service degraded

Matches the documented API specification.
Why it works:
  • No personal pronouns
  • No company/project references
  • Objective, technical description
  • References public documentation

Multi-Line Commit Messages

To write multi-line messages, use an editor:
# Opens your default editor (vim, nano, etc.)
git commit
Or use multiple -m flags:
git commit \
  -m "fix: correct timeout handling" \
  -m "The previous timeout of 5s was too short." \
  -m "Increased to 30s with exponential backoff."
Or use a heredoc:
git commit -m "$(cat <<EOF
fix: correct timeout handling

The previous timeout of 5s was too short for slow networks.
Increased to 30s with exponential backoff (1s, 2s, 4s, 8s).

Tested with simulated network delays up to 25s.
EOF
)"

Commit Message Template

Create a template file ~/.gitmessage:
# Type: Summary (50 chars max)

# Why is this change needed?
# 

# How does it address the issue?
# 

# What testing was done?
# 

# Any caveats or limitations?
# 
Then configure Git to use it:
git config --global commit.template ~/.gitmessage
Now git commit opens with this template.

Linking to Issues

If the repository has a public issue tracker, you can reference issues:
fix: resolve memory leak in background worker

The worker was not releasing database connections after
completing tasks, causing connection pool exhaustion.

Fixes #1234
GitHub will automatically close issue #1234 when the PR is merged if you use keywords like Fixes, Closes, or Resolves.

Multiple Commits

If pushing multiple commits, each commit message should be clear:
git log --oneline
# a1b2c3d docs: update API examples
# e4f5g6h test: add integration tests
# i7j8k9l feat: add user authentication
All three messages appear in the PR—don’t rely on only the last commit being descriptive.

Reviewing Your Message

Before pushing, review your commit message:
git log -1 --pretty=format:"%B"
Ask yourself:
  • Is the summary under 50 characters?
  • Does it explain why, not just what?
  • Would a maintainer understand without context?
  • Does it avoid personal/company information?
  • Is it professional and respectful?
If yes to all, you’re good to push!

Common Mistakes

Too Vague

# Bad
fix: update code

# Good
fix: prevent null pointer exception in user parser

Too Detailed (in summary)

# Bad (summary too long)
fix: update the JSON parser to handle malformed input by catching exceptions and returning error messages instead of crashing

# Good
fix: prevent crash when parsing malformed JSON

# (Details go in body)
The parser now catches exceptions and returns descriptive errors.

No Context

# Bad
fix: change timeout

# Good
fix: increase API timeout for slow networks

The 5s timeout was too short for 3G connections.
Increased to 30s with exponential backoff.

Best Practices Summary

Be Specific

Explain what changed and why. Avoid vague summaries like “fix bug” or “update code.”

Be Concise

Keep the summary under 50 characters. Save details for the body.

Be Anonymous

Avoid personal pronouns (I, we, our) and company references. Use neutral, technical language.

Be Professional

Write respectfully. You’re asking maintainers to accept your code—make it easy for them.

Tools and Resources

Commit Message Linters

Use tools to enforce good commit messages:

Style Guides

Examples from Real Projects

Linux Kernel

fix: correct GPIO mapping bug in BCM2835 driver

The GPIO pin mapping for pins 23-27 was incorrect due to
a typo in the register offset calculation. This caused
GPIO operations on these pins to fail silently.

Corrected the register offset from 0x20 to 0x24.

Tested on Raspberry Pi 4 Model B.

Node.js

fix: prevent memory leak in HTTP keep-alive connections

HTTP connections with keep-alive enabled were not being
properly released when the connection was closed by the
remote peer. This caused the connection pool to grow
unbounded, eventually exhausting file descriptors.

Now explicitly destroys sockets when the peer closes.

Fixes: https://github.com/nodejs/node/issues/12345

Next Steps

Basic Usage

Learn the fundamentals of using gitGost

Anonymous Push

Understand how metadata is stripped

Tor Integration

Hide your IP address with Tor

Threat Model

Understand anonymity guarantees

Build docs developers (and LLMs) love