glossary

Commit Message Format

The structural rules that define how a git commit message should be organised, including its subject line, optional body, and optional footer sections.

explanation

A well-formatted commit message consists of three parts separated by blank lines. The subject line (first line) summarises the change in 50 characters or fewer using the imperative mood ("add feature" not "added feature" or "adds feature"). The body (optional) provides additional context, the reasoning, or implementation details, with lines wrapped at 72 characters. The footer (optional) contains structured metadata like issue references, co-author attributions, or breaking change notices. The Conventional Commits specification adds type and scope structure to the subject line: type(scope): subject. This makes the message both human-readable and machine-parseable. The 50-character limit for the subject is a git convention — git log --oneline truncates at this length, and GitHub and GitLab collapse long subject lines in their UIs. Common formatting mistakes include mixing past and present tense, using periods at the end of subject lines, writing vague subjects ("update stuff"), not wrapping body lines, and combining unrelated changes in a single message. A good subject line answers "if applied, this commit will [subject]".

examples

feat(search): add full-text search with PostgreSQL tsvector

fix(session): clear cookie on explicit logout even without active session

refactor(logger): extract severity mapping to standalone function

- move mapping table out of the hot path log() function
- add unit tests for each severity level mapping

The inline table was recalculated on every log call; extracting it reduces
per-call work and makes the mapping independently testable.

chore(ci): pin Node.js to 20.14.0 LTS in all workflow files

how git-agent helps

git-agent generates messages that follow the correct format automatically: a conventional subject line within 72 characters, a blank line separator, a bullet-point body explaining what changed, and a closing paragraph explaining why.

brew install gitagenthq/tap/git-agent

FAQ

Why is the 50-character subject line limit important?

git log --oneline and many Git UIs (GitHub, GitLab, Sourcetree) truncate or wrap at 72 characters. Keeping subjects under 50 characters ensures they are fully visible in the one-line log format across all contexts.

Is the commit body mandatory?

No, but it is recommended for non-trivial changes. A subject line says what changed; the body explains why the change was necessary and any context that is not obvious from the diff alone.

Should commit messages be written in English?

There is no universal rule. The convention is to match the language used in the codebase and existing history. For open-source projects intended for international contributors, English is the common choice.

Conventional Commits Pre-commit hooks feat commit template