Git Commit Message StyleGuide
TOC
About
This is an attempt to standardize the format of commit messages, for the sake of uniformity in git log, best practices for writing commit messages & fun!
Using emojis at the beginning of commit messages, other than being fun, provides a simple way to indicate the intention of that commit, an ease for the eyes when browsing/reviewing git log. It's also a simple measure of the fact that how much that commit is focused on a single purpose, which is a good practice.
If these rules and/or using emojis is an overkill for your productivity or simply losing its purposes, please tailor them to your needs or don't use them.
Summary of the reasons for these conventions:
- Fun!
- Simple navigation through git history (e.g. ignoring style changes).
- Automatic generating of the changelog.
Commit Message Format
<type>(<scope>): <subject>
<body>
<footer>
Message Subject(first line)
- Capitalize the
<subject>. - Do not end the first line with a period.
- Total characters of the first line MUST be Less than or Equal to 50 characters Long.
- Use the present tense ("Add feature" not "Added feature").
- Use the imperative mood ("Move cursor to..." not "Moves cursor to...").
- Use
<type>to identify what type of changes introduced in this commit; Allowed<type>keywords:- An Emoji(see below for list of Suggested Emojis)
- Or a Text:
- feat: new feature for the user(or β¨ emoji)
- fix: bug fix for the user(or
π emoji) - docs: changes to the documentation(or
π emoji) - style: formatting, missing semi colons, etc; no production code change(or π¨ emoji)
- refactor: refactoring production code, eg. renaming a variable(or
π emoji) - test: adding missing tests, refactoring tests; no production code change(or π¬ emoji)
- chore: updating grunt tasks etc; no production code change
- If you need more than one keyword or emoji to use, you should probably think twice!. This usally means you need to break this commit into more smaller commits; If thats not the case then separate each emoji with a space.
- Use
<scope>to identify which component this<type>is related to; Example<scope>values:- init
- runner
- watcher
- config
- web-server
- proxy
- etc.
- The
<scope>can also be empty (e.g. if the change is a global or difficult to assign to a single component), in which case the parentheses are omitted.
Message Body
- Includes motivation for the change and contrasts with previous behavior.
- Use the body to explain whats and whys vs. hows.
- Wrap each line of the body at 72 characters.
Message Footer
- Reference issues this commit is related to with the status of that Issue; Ex.
Issue #27,Ref T27orRef T27, T56orFixes T8. - Supported issue tracker status keywords:
- Fixes
- Fixed
- Closes
- Closed
- Resolves
- Resolved
- Ref
- Issue
- Issues
- More info on issue tracker status keywords:
- It's also recommended to use Full URL to the Issues, instead of just issue ID Number; Doing so will ease browsing issues from terminal.
- In the case of multiple issues separate them with commas, Ex.
Closes #27, #56.
Notes
- Use valid MarkDown format in the
<body>. - All WIP(Work In Progress) commits SHOULD have the
π§ Emoji. - All WIP commits SHOULD be avoided!.
- Referencing Issues by using special keywords like
FixesorResolveswill mark them as closed automatically! For more information about automatic issue closing using ketwords see their documentation(linked above). - There is NO new-line after the
<footer>. - Every emoji text(
:emoji:) is counted as one character!. - See ToDo Grammar StyleGuide for more Information on
@XXXComment Tags.
Suggested Emojis
| Emoji | Raw Emoji Code | Description |
|---|---|---|
:art: |
when improving the format/structure of the code | |
| π° | :newspaper: |
when creating a new file |
| π | :pencil: |
when performing minor changes/fixing the code or language |
:racehorse: |
when improving performance | |
| π | :books: |
when writing docs |
:bug: |
when reporting a bug, with @FIXMEComment Tag |
|
:ambulance: |
when fixing a bug | |
| π§ | :penguin: |
when fixing something on Linux |
:apple: |
when fixing something on Mac OS | |
| π | :checkered_flag: |
when fixing something on Windows |
:fire: |
when removing code or files, maybe with @CHANGED Comment Tag |
|
| π | :tractor: |
when change file structure. Usually together with π¨ |
:hammer: |
when refactoring code | |
| β | :umbrella: |
when adding tests |
| π¬ | :microscope: |
when adding code coverage |
:green_heart: |
when fixing the CI build | |
:lock: |
when dealing with security | |
| β¬οΈ | :arrow_up: |
when upgrading dependencies |
:arrow_down: |
when downgrading dependencies | |
:fast_forward: |
when forward-porting features from an older version/branch | |
:rewind: |
when backporting features from a newer version/branch | |
:shirt: |
when removing linter/strict/deprecation warnings | |
:lipstick: |
when improving UI/Cosmetic | |
:wheelchair: |
when improving accessibility | |
:globe_with_meridians: |
when dealing with globalization/internationalization/i18n/g11n | |
:construction: |
WIP(Work In Progress) Commits, maybe with @REVIEW Comment Tag |
|
:gem: |
New Release | |
:egg: |
New Release with Python egg | |
:ferris_wheel: |
New Release with Python wheel package | |
| π | :bookmark: |
Version Tags |
:tada: |
Initial Commit | |
:speaker: |
when Adding Logging | |
| π | :mute: |
when Reducing Logging |
:sparkles: |
when introducing New Features | |
:zap: |
when introducing Backward-InCompatible Features, maybe with @CHANGED Comment Tag |
|
| π‘ | :bulb: |
New Idea, with @IDEA Comment Tag |
:snowflake: |
changing Configuration, Usually together with |
|
:ribbon: |
Customer requested application Customization, with @HACK Comment Tag |
|
:rocket: |
Anything related to Deployments/DevOps | |
:elephant: |
PostgreSQL Database specific (Migrations, Scripts, Extensions, ...) | |
:dolphin: |
MySQL Database specific (Migrations, Scripts, Extensions, ...) | |
:leaves: |
MongoDB Database specific (Migrations, Scripts, Extensions, ...) | |
:bank: |
Generic Database specific (Migrations, Scripts, Extensions, ...) | |
:whale: |
Docker Configuration | |
:handshake: |
when Merge files | |
:cherries: |
when Commit Arise from one or more Cherry-Pick Commit(s) |
Tools
- Commit(CLI): This is a nifty CLI tool to aid in standardizing commit messages based on this document, thanks to @jakeasmith.
- gitMoji(Firefox & Chrome Extension): Enhance your commits with emojis!, thanks to @louisgrasset.
Fun Emoji Usages
- CodeEmoji: Mozillaβs Codemoji enciphers your messages with emoji for fun and profit
- Emoji Based Diagram: Emoji Based Diagram of Data Bearing Subscription Updates(WebPush VAPID)
Contributing
To add a new Emoji to the list: Create an Issue & Send a PR.
License
The Code is licensed under the MIT License.