Commit Message Guide
Guidelines for writing effective Git commit messages.
Content Requirements
Section titled “Content Requirements”Commit messages need sufficient information. Avoid vague messages like:
Fix a calc engine bug(What bug?)Adjust code(Why?)Get result(What result? Why?)
Exception: Generic commits are exempt from this rule.
Perspective
Section titled “Perspective”Small to Medium Commits
Section titled “Small to Medium Commits”Most commits (99%) modify fewer than 1000 lines. For these, prioritize writing the purpose (what problem does this commit solve):
Fix cash balance not saved for LPL investment accountsFix a bug that prevents some tweaks from being applied to owned homesOptimize engine input file generation
Compare:
Add $attributes to schemas(content) vsMake Eloquent aware of any default value specified in database column definitions(purpose)
Large Commits
Section titled “Large Commits”For massive commits where listing all purposes/changes isn’t practical, write an outline/summary. This is a compromise and should be avoided unless necessary:
Refactor tweak framework, part 1(branch must link to Jira ticket)Tweak framework refactor first cutRename various tables for clarity
Generic Commits
Section titled “Generic Commits”Only for commits without specific business/technical goals, affecting multiple unrelated modules:
Code cleanup(removing unrelated deprecated code)Code clarity(renaming unrelated classes/methods/variables)Code reformat(reformatting code style)Upgrade packages(routine package upgrades)Add comments(purely adding comments)
Be Specific
Section titled “Be Specific”Make commit messages as specific as possible:
| Vague | Specific |
|---|---|
Move $age attribute | Move $age attribute from Person model to AdultPerson model |
Stop excessive logging | Stop excessive logging in report:send command |
Add a new integration type to account | Add "lpl" integration type to account |
Be Complete
Section titled “Be Complete”One commit should do one thing. Multiple changes should be separate commits.
If a commit does multiple things and splitting is too costly, the message must cover all changes - don’t mention only part of them.
Trade-offs
Section titled “Trade-offs”Minor changes not serving the commit’s main purpose can be omitted if:
- Extremely small detail
- No risk
Example: Adding type declarations to existing methods while working on a feature ticket.
Be Concise
Section titled “Be Concise”Use plain, direct language. Avoid filler words:
Add a new integration, its name is LPL→Add LPL integration
Context
Section titled “Context”Explain unnatural or unusual operations:
Lock somewhere/someone package to version 1.2.3(Why lock? When can it be unlocked?)
If branch name provides context, no need to repeat in commit message. For branch bugfix/DEV-1234-engine-output-file-may-be-missing, both Check file existence and Check engine output file existence are acceptable.
References
Section titled “References”Jira Tickets
Section titled “Jira Tickets”- If a commit serves a Jira ticket, include the ticket number (e.g.,
DEV-1234) unless the PR already contains it - If PR branch contains
DEV-1234but a commit fixes a different ticketDEV-5678, includeDEV-5678in that commit message
Other Commits
Section titled “Other Commits”Reference related commits by hash:
Fix bug introduced by [abcd123]Revert [abcd123]
Grammar
Section titled “Grammar”Syntax
Section titled “Syntax”Use natural language with proper grammar, capitalization, and punctuation:
Add fail-safe to engine execution.
Incorrect examples:
add fail-safe to tamarac api execution.(missing capitalization)Add fail-safe to Tamarac API execute.(should be “execution”)
Sentence Structure
Section titled “Sentence Structure”Start with a verb in simple present tense:
Add something...Fix something...Correct something...
Do NOT use:
- Third person singular:
Adds something... - Past tense:
Added something...
Simple commits may use nouns/gerunds: Package upgrade, Code cleanup (not recommended).
Spelling
Section titled “Spelling”Use correct English spelling. Proofread before pushing.
Proper nouns must use official capitalization:
Add LPL integrationUpgrade MySQL and Redis version
Code elements use code capitalization:
Add "lpl" to \accounts`.`integration_type` enum value`Fix SomeClass::someMethod() cannot handle exception.
Code References
Section titled “Code References”Use special formatting for code elements:
| Element | Format |
|---|---|
| Database tables/columns | Backticks: `accounts`.`integration_type` |
| Functions/methods | Parentheses: someMethod() |
| Variables | Dollar sign: $variable |
| String literals | Quotes: "lpl" |
| Composer packages | vendor/package |
Acceptable Variations
Section titled “Acceptable Variations”- Common abbreviations:
calc engine,ctor - Final period optional (but punctuation required between multiple sentences)