{
    "slug": "commit_message_best_practices",
    "term": "Commit Message Best Practices",
    "category": "style",
    "difficulty": "beginner",
    "short": "Clear commit messages that explain why a change was made, not just what — enabling efficient git log navigation, automated changelog generation, and informed code archaeology.",
    "long": "The seven rules of a good commit: (1) Separate subject from body with a blank line, (2) Limit subject to 50 chars, (3) Capitalise subject, (4) No period at end, (5) Use imperative mood ('Add' not 'Added'), (6) Wrap body at 72 chars, (7) Use the body to explain what and why, not how. Conventional Commits format (feat:, fix:, chore:) enables automated semantic versioning and changelog generation. git log --oneline should tell a story of the project's evolution.",
    "aliases": [
        "git commit message",
        "conventional commits",
        "commit style"
    ],
    "tags": [
        "style",
        "git",
        "documentation"
    ],
    "misconception": "Commit messages are for the commit author — commit messages are primarily for future developers (and your future self) trying to understand why a change was made 18 months ago.",
    "why_it_matters": "Good commit messages turn git log into documentation — a well-written commit explaining why a security check was added prevents future developers from 'cleaning up' the code and reintroducing a vulnerability.",
    "common_mistakes": [
        "'WIP', 'fix', 'update', 'misc' — meaningless; what work, what fix, what update?",
        "Subject line > 72 characters — truncated in most git tools.",
        "No body explaining the why — the diff shows what changed; the message should explain why.",
        "Past tense ('Added feature') instead of imperative ('Add feature') — inconsistent with git's own messages."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "conventional_commits",
        "changelog",
        "git_hooks_deep",
        "semantic_versioning"
    ],
    "prerequisites": [
        "conventional_commits",
        "git_hooks_workflow",
        "semantic_versioning"
    ],
    "refs": [
        "https://www.conventionalcommits.org/",
        "https://cbea.ms/git-commit/"
    ],
    "bad_code": "# Useless commit history:\ngit log --oneline\nabc123 fix\ndef456 update\nghi789 WIP\njkl012 changes\n# 6 months later: which commit introduced the security regression?\n# No way to know without reading every diff",
    "good_code": "# Conventional Commits — searchable, automatable:\ngit log --oneline\nabc123 fix(auth): prevent session fixation after password reset\ndef456 feat(checkout): add Apple Pay support\nghi789 refactor(user): extract email validation to ValueObject\njkl012 security: rotate JWT signing key after exposure in logs\n\n# Full commit with body:\nfix(auth): prevent session fixation after password reset\n\nSession was not regenerated after successful password reset,\nallowing an attacker with a pre-existing session ID to take\nover the account. Fixes CVE-2026-1234.\n\nCloses #456",
    "quick_fix": "Write commit messages as 'what and why', not 'what and how' — the diff shows what changed, the message should explain why it changed and what problem it solves",
    "severity": "low",
    "effort": "low",
    "created": "2026-03-16",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/commit_message_best_practices",
        "html_url": "https://codeclaritylab.com/glossary/commit_message_best_practices",
        "json_url": "https://codeclaritylab.com/glossary/commit_message_best_practices.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Commit Message Best Practices](https://codeclaritylab.com/glossary/commit_message_best_practices) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/commit_message_best_practices"
            }
        }
    }
}