Git Commit Conventions¶

How to write commit messages that are clear, searchable, and team-friendly. Commands: Git Command Set; local checks: Gitignore & Hooks.

See also: Git Command Set · Gitignore & Hooks · Collaboration

How to read this page¶

1. Concepts — parts of a message and why conventions help
2. Overview — common formats, type table, related commands
3. Scenarios — real patterns with good/bad examples
4. Symptom lookup — at the bottom

What a commit message is¶

Every git commit stores a message: a subject (usually line 1), optional body, and optional footers (trailers).

In plain terms: “Label this change so future-you and teammates know what changed and why.”

Effect: Messages live in history forever—git log, PRs, changelogs, and release tools all read them. Quality directly affects review and debugging.

Overview¶

Common format patterns¶

Conventional Commits is widely used (Angular, Semantic Release, etc.). Teams may subset it (e.g. type: without scope)—clarity beats rigid compliance.

Conventional Commits: type cheat sheet¶

Optional scope: feat(api): ..., fix(ui): ....
Breaking changes: ! after type (feat(api)!: ...) or BREAKING CHANGE: in footer.

Git commands used in this doc¶

Subject-line principles (language-agnostic)¶

Scenario: minimal bar when there is no team standard¶

Typical uses: Personal repos, teams without CONTRIBUTING yet.

In plain terms: “Subject should explain the change in five seconds.”

# Good: specific verb + context
git commit -m "Fix crash when profile avatar is missing"

# Bad: too vague
git commit -m "update"
git commit -m "fix bug"
git commit -m "WIP"

# Bad: issue number alone
git commit -m "#123"

Scenario: Conventional Commits¶

Typical uses: Open source, automated changelogs, PR titles aligned with history.

git commit -m "feat(billing): support annual subscription"
git commit -m "fix: prevent double submit on checkout"
git commit -m "docs: add API rate limit section"
git commit -m "build: upgrade eslint to 9.x"

Effect: Tools can classify feat vs fix for releases; reviewers filter git log by type.

Scenario: multiline subject + body¶

Typical uses: Refactors, behavior changes—explain why, not a file list.

git commit -m "$(cat <<'EOF'
fix(auth): reject expired refresh tokens

Previously expired tokens still passed middleware when
clock skew was under 30s. Align with OAuth spec and
return 401 with clear error code.

Refs #8842
EOF
)"

Or use the editor:

git commit
# fix(auth): reject expired refresh tokens
#
# Previously expired tokens still passed...

Effect: git log shows subject; git show reveals body and footers.

Scenario: fix the last message (not pushed yet)¶

Typical uses: Typo in subject, forgot git add a file.

git commit --amend
git commit --amend -m "feat: add password reset email"

git add forgotten.ts
git commit --amend --no-edit

In plain terms: “Last commit still local—you may rewrite it.”

Effect: Commit hash changes—only safe if not pushed to a shared branch.

Scenario: already pushed to the remote¶

Typical uses: Wrong message or need to undo, but commit is on origin/main.

git revert HEAD

# Avoid on shared main:
# git reset --hard HEAD~1 && git push --force

In plain terms: “Published history gets new commits, not erased rewrites.”

Scenario: breaking changes¶

Typical uses: Remove API, change defaults, major version bumps.

git commit -m "$(cat <<'EOF'
feat(api)!: remove legacy /v1 users endpoint

BREAKING CHANGE: clients must use /v2/users. v1 removed
after deprecation period noted in 2025-Q4 changelog.
EOF
)"

git commit -m "feat: switch default TLS to 1.3

BREAKING CHANGE: TLS 1.0/1.1 no longer supported."

Effect: Release tools may bump major version; users search logs for BREAKING CHANGE.

Scenario: trailers and issue links¶

Trailers are structured footer lines (Key: Value), common in OSS and GitHub/GitLab.

git commit -m "$(cat <<'EOF'
fix: validate upload MIME type

Co-authored-by: Alex Chen <alex@example.com>
Closes #456
EOF
)"

Typical uses:

• Squash merge combining multiple authors’ trailers
• IDE / AI tools auto-inserting footers—review before commit and drop lines the project forbids

Scenario: what lands after a PR merge¶

Typical uses: GitHub/GitLab merge produces merge or squash commits.

In plain terms: “On squash merge, PR title ≈ future commit subject.”

Scenario: working with commit-msg hooks¶

Teams validate format in a commit-msg hook (required prefix, non-empty subject). Examples: Gitignore & Hooks — commit-msg.

Effect: Bad messages fail locally before push.

Scenario: good vs bad examples¶

Quick lookup: symptom → suggestion¶

More commands: Git Command Set — git commit.