A Brief Introduction to Git Commit Conventions
TLDR
- The Angular Commit Format structure consists of Header (required), Body (optional), and Footer (optional).
- The Header format is
<type>(<scope>): <short summary>, wheretypeis used for categorization, andsummaryshould use the imperative mood, no capitalization at the start, and no period at the end. - Use
git config --global commit.template <file_path>to set a global commit template to improve consistency in writing conventions. - Set
git config --global commit.cleanup stripto ensure that comment lines and extra blank lines in the template are automatically removed during a commit. - Use keywords like
BREAKING CHANGEorDEPRECATEDin the Footer to mark major changes, and use syntax likeCloses #<issue_number>to automatically link issues.
Commit Format Structure
The Angular Commit Format divides the message into three parts, separated by blank lines.
xml
<header>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>Header Conventions
The Header is the core of the commit message, formatted as <type>(<scope>): <short summary>.
- Type: Used to define the type of change.
feat: A new feature.fix: A bug fix.docs: Documentation-only changes.refactor: A code change that neither fixes a bug nor adds a feature.test: Adding missing tests or correcting existing tests.perf: A code change that improves performance.build: Changes that affect the build system or external dependencies.ci: Changes to CI configuration files and scripts.
- Scope: Indicates the affected module or package name; can be omitted if there is no specific scope.
- Short Summary: A concise description of the change. It is recommended to use the imperative mood (e.g., "change" instead of "changed"), no capitalization at the start, and no period at the end.
Body and Footer
- Body: Explains the motivation for the change and can contrast the behavior before and after the modification. Can be omitted if the change is simple.
- Footer: Used to mark major changes (
BREAKING CHANGE), deprecation information (DEPRECATED), or to link issues.- Issue linking keywords:
close,closes,closed,fix,fixes,fixed,resolve,resolves,resolved.
- Issue linking keywords:
Commit Template Configuration and Application
When developers are unfamiliar with the conventions or prone to missing fields, the Git Template feature can be used to standardize the format.
Configuration Steps
- Create a
.gitmessage.txtfile containing descriptions and conventions for each field. - Execute the following commands for global configuration:git
git config --global commit.template ~/.gitmessage.txt git config --global commit.cleanup strip
Parameter Explanation
commit.template: Specifies the location of the commit message template file.commit.cleanup strip: Ensures that comment lines (lines starting with#) and extra blank lines in the template are automatically removed when performing a commit.
TIP
If template is set to ./.gitmessage.txt, Git will prioritize using the file in the root directory of the current repository as the template.
Support Status in Common Git Clients
In what situations might you encounter issues where comments are not automatically removed? When using non-command-line GUI Git tools, if the tool does not correctly handle the commit.cleanup setting, comment lines might be mistakenly included as part of the commit message.
- GitKraken: You must manually check "Removes comments from commit messages" in Preferences.
- Tortoisegit: By default, it does not ignore lines starting with
#. - Git Extensions: Automatically ignores lines starting with
#. - Sourcetree: Versions 3.4.20 and above for Windows support Git Templates and will automatically ignore lines starting with
#.
Change Log
- 2024-07-23 Initial document creation.
- 2024-09-20
- Updated information regarding Git Commit Template support in Sourcetree for Windows 3.4.20.
- Corrected the explanation of the configuration file location.