Git Lint is a command line interface for linting Git commits by ensuring you maintain a clean, easy to read, debuggable, and maintainable project history. Having a consistent commit history leads to improved code reviews and is a perfect companion to tools like Milestoner for versioning and producing automated release notes of your deploys.
- Features
- Requirements
- Setup
-
Usage
- Command Line Interface (CLI)
- Configuration
-
Analyzers
- Commit Author Capitalization
- Commit Author Email
- Commit Author Name
- Commit Body Bullet Capitalization
- Commit Body Bullet Delimiter
- Commit Body Bullet Only
- Commit Body Leading Line
- Commit Body Line Length
- Commit Body Paragraph Capitalization
- Commit Body Phrase
- Commit Body Presence
- Commit Body Tracker Shorthand
- Commit Body Word Repeat
- Commit Signature
- Commit Subject Length
- Commit Subject Prefix
- Commit Subject Suffix
- Commit Subject Word Repeat
- Commit Trailer Collaborator Capitalization
- Commit Trailer Collaborator Email
- Commit Trailer Collaborator Key
- Commit Trailer Collaborator Name
- Commit Trailer Duplicate
- Commit Trailer Format Key
- Commit Trailer Format Value
- Commit Trailer Issue Key
- Commit Trailer Issue Value
- Commit Trailer Milestone Key
- Commit Trailer Milestone Value
- Commit Trailer Order
- Commit Trailer Reviewer Key
- Commit Trailer Reviewer Value
- Commit Trailer Signer Capitalization
- Commit Trailer Signer Email
- Commit Trailer Signer Key
- Commit Trailer Signer Name
- Commit Trailer Tracker Key
- Commit Trailer Tracker Value
- Git
- Rake
- Continuous Integration (CI)
- Style Guide
- Development
- Tests
- License
- Security
- Code of Conduct
- Contributions
- Developer Certificate of Origin
- Versions
- Community
- Credits
-
Enforces a Git Rebase Workflow.
-
Enforces a clean and consistent Git commit history.
-
Supports Git default branch configuration.
-
Provides a customizable suite of analyzers.
-
Provides Git Hook support for local use.
-
Provides Continuous Integration (CI) support.
To install with security, run:
# đź’ˇ Skip this line if you already have the public certificate installed.
gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)
gem install git-lint --trust-policy HighSecurity
To install without security, run:
gem install git-lint
From the command line, type: git-lint --help
To check if your Git commit history is clean, run: git-lint analyze --branch
. It will exit with a failure if at least one issue with error severity is detected.
This gem does not check commits on your default branch (i.e. main
). This is intentional as you
would, generally, not want to rewrite or fix commits on the main
branch. This gem is best used on
feature branches as it automatically detects all commits made since creation of the feature branch.
Here is an example workflow, using gem defaults with issues detected:
cd example
git checkout -b test
touch text.txt
git add --all .
git commit --message "This is a bogus commit message that is also terribly long and will word wrap"
git-lint analyze --branch
Output:
Running Git Lint... 83dbad531d84a184e55cbb38c5b2a4e5fa5bcaee (Brooke Kuhlmann, 0 seconds ago): This is a bogus commit message that is also terribly long and will word wrap. Commit Body Presence Warning. Use minimum of 1 line (non-empty). Commit Subject Length Error. Use 72 characters or less. Commit Subject Prefix Error. Use: /Fixed/, /Added/, /Updated/, /Removed/, /Refactored/. Commit Subject Suffix Error. Avoid: /\./, /\?/, /\!/. 1 commit inspected. 4 issues detected (1 warning, 3 errors).
This gem can be configured via a global configuration:
$HOME/.config/git-lint/configuration.yml
It can also be configured via XDG environment variables. The default configuration is:
commits:
author:
capitalization:
enabled: true
severity: error
email:
enabled: true
severity: error
name:
enabled: true
severity: error
minimum: 2
body:
bullet_capitalization:
enabled: true
severity: error
includes:
- "\\-"
- "\\*"
bullet_delimiter:
enabled: true
severity: error
includes:
- "\\-"
- "\\*"
bullet_only:
enabled: true
severity: error
includes:
- "\\-"
- "\\*"
leading_line:
enabled: true
severity: warn
line_length:
enabled: false
severity: error
maximum: 72
paragraph_capitalization:
enabled: true
severity: error
phrase:
enabled: true
severity: error
excludes:
- "absolutely"
- "actually"
- "all intents and purposes"
- "along the lines"
- "at this moment in time"
- "basically"
- "blacklist"
- "each and every one"
- "everyone knows"
- "fact of the matter"
- "furthermore"
- "however"
- "in due course"
- "in the end"
- "last but not least"
- "matter of fact"
- "obviously"
- "of course"
- "really"
- "simply"
- "things being equal"
- "whitelist"
- "would like to"
- "\\beasy\\b"
- "\\bjust\\b"
- "\\bquite\\b"
- "as\\sfar\\sas\\s.+\\sconcerned"
- "of\\sthe\\s(fact|opinion)\\sthat"
presence:
enabled: true
severity: warn
minimum: 1
tracker_shorthand:
enabled: true
severity: error
excludes:
- "(f|F)ix(es|ed)?\\s\\#\\d+"
- "(c|C)lose(s|d)?\\s\\#\\d+"
- "(r|R)esolve(s|d)?\\s\\#\\d+"
word_repeat:
enabled: true
severity: error
signature:
enabled: false
severity: error
includes:
- Good
subject:
length:
enabled: true
severity: error
maximum: 72
prefix:
enabled: true
severity: error
delimiter: " "
includes:
- Fixed
- Added
- Updated
- Removed
- Refactored
suffix:
enabled: true
severity: error
excludes:
- "\\."
- "\\?"
- "\\!"
word_repeat:
enabled: true
severity: error
trailer:
collaborator_capitalization:
enabled: true
severity: error
collaborator_email:
enabled: true
severity: error
collaborator_key:
enabled: true
severity: error
collaborator_name:
enabled: true
severity: error
minimum: 2
duplicate:
enabled: true
severity: error
format_key:
enabled: true
severity: error
format_value:
enabled: true
severity: error
includes:
- asciidoc
- markdown
issue_key:
enabled: true
severity: error
issue_value:
enabled: true
severity: error
includes:
- "[\\w-]+"
milestone_key:
enabled: true
severity: error
milestone_value:
enabled: true
severity: error
includes:
- major
- minor
- patch
order:
enabled: true
severity: error
reviewer_key:
enabled: true
severity: error
reviewer_value:
enabled: true
severity: error
includes:
- clickup
- github
- jira
- linear
- shortcut
- tana
signer_capitalization:
enabled: true
severity: error
signer_email:
enabled: true
severity: error
signer_key:
enabled: true
severity: error
signer_name:
enabled: true
severity: error
minimum: 2
tracker_key:
enabled: true
severity: error
tracker_value:
enabled: true
severity: error
includes:
- "[\\w\\-\\s]+"
By default, most analyzers are enabled. Accepted values are true
or false
. If you wish to
disable a analyzer, set it to false
.
By default, most analyzers are set to error
severity. If you wish to reduce the severity level of
a analyzer, you can set it to warn
instead. Here are the accepted values and what each means:
-
warn
: Will count as an issue and display a warning but will not cause the program/build to fail. Use this if you want to display issues as reminders or cautionary warnings. -
error
: Will count as an issue, display error output, and cause the program/build to fail. Use this setting if you want to ensure bad commits are prevented.
Some analyzers support include or exclude lists. These lists can consist of strings, regular
expressions, or a combination thereof. Regardless of your choice, all lists are automatically
converted to regular expression for use by the analyzers. This means a string like "example"
becomes /example/
and a regular expression of "\\AExample."` becomes `/\AExample./
.
If you need help constructing complex regular expressions for these lists, try launching an IRB
session and using Regexp.new
or Regexp.escape
to experiment with the types of words/phrases you
want to turn into regular expressions. For purposes of the YAML configuration, these need to be
expressed as strings with special characters escaped properly for internal conversion to a regular
expression.
The following details the various analyzers provided by this gem to ensure a high standard of commits for your project.
Enabled | Severity | Defaults |
---|---|---|
true |
error |
none |
Ensures author name is properly capitalized. Example:
# Disallowed jayne cobb dr. simon tam # Allowed Jayne Cobb Dr. Simon Tam
Enabled | Severity | Defaults |
---|---|---|
true |
error |
none |
Ensures author email address exists. Git requires an author email when you use it for the first time too. This takes it a step further to ensure the email address loosely resembles an email address.
# Disallowed mudder_man # Allowed jayne@serenity.com
Enabled | Severity | Defaults |
---|---|---|
true |
error |
minimum: 2 |
Ensures author name consists of, at least, a first and last name. Example:
# Disallowed Kaylee # Allowed Kaywinnet Lee Frye
Enabled | Severity | Defaults |
---|---|---|
true |
error |
includes: |
Ensures commit body bullet lines are capitalized. Example:
# Disallowed - an example bullet. # Allowed * An ASCII Doc bullet. * link:https://demo.com[Demo] * link:https://demo.com[demo] - A Markdown bullet. - [Demo](https://demo.com) - [demo](https://demo.com)
Enabled | Severity | Defaults |
---|---|---|
true |
error |
includes: |
Ensures commit body bullets are delimited by a space. Example:
# Disallowed -An example bullet. # Allowed - An example bullet.
Enabled | Severity | Defaults |
---|---|---|
true |
error |
includes: |
Ensures a single bullet is never used when a paragraph could be used instead. Example:
# Disallowed - Pellentque morbi-trist sentus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu_libero sit amet quam. # Allowed Pellentque morbi-trist sentus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu_libero sit amet quam.
Enabled | Severity | Defaults |
---|---|---|
true |
error |
none |
Ensures there is a leading, empty line, between the commit subject and body. Generally, this isn’t an issue but sometimes the Git CLI can be misused or a misconfigured Git editor will smash the subject line and start of the body as one run-on paragraph. Example:
# Disallowed Curabitur eleifend wisi iaculis ipsum. Pellentque morbi-trist sentus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu_libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat's eleifend leo. Quisque et sapien ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, commodo vitae, orn si amt wit. # Allowed Curabitur eleifend wisi iaculis ipsum. Pellentque morbi-trist sentus et netus et malesuada fames ac turpis egestas. Vestibulum tortor quam, feugiat vitae, ultricies eget, tempor sit amet, ante. Donec eu_libero sit amet quam egestas semper. Aenean ultricies mi vitae est. Mauris placerat's eleifend leo. Quisque et sapien ullamcorper pharetra. Vestibulum erat wisi, condimentum sed, commodo vitae, orn si amt wit.
Enabled | Severity | Defaults |
---|---|---|
false |
error |
maximum: 72 |
Ensures each line of the commit body doesn’t extend beyond the maximum column limit.
Enabled | Severity | Defaults |
---|---|---|
true |
error |
none |
Ensures each paragraph of the commit body is capitalized. Example:
# Disallowed curabitur eleifend wisi iaculis ipsum. # Allowed Curabitur eleifend wisi iaculis ipsum.
Enabled | Severity | Defaults |
---|---|---|
true |
error |
excludes: (see configuration) |
Ensures non-descriptive words/phrases are avoided in order to keep commit message bodies informative and specific. The exclude list is case insensitive. Detection of excluded words/phrases is case insensitive as well. Example:
# Disallowed Obviously, the existing implementation was too simple for my tastes. Of course, this couldn't be allowed. Everyone knows the correct way to implement this code is to do just what I've added in this commit. Easy! # Allowed Necessary to fix due to a bug detected in production. The included implementation fixes the bug and provides the missing spec to ensure this doesn't happen again.
Enabled | Severity | Defaults |
---|---|---|
true |
warn |
minimum: 1 |
Ensures a minimum number of lines are present within the commit body. Lines with empty characters (i.e. whitespace, carriage returns, etc.) are considered to be empty.
Automatically ignores fixup! commits as they are not meant to have bodies.
Enabled | Severity | Defaults |
---|---|---|
true |
error |
excludes: (see configuration) |
Ensures commit body doesn’t use issue tracker shorthand. The exclude list defaults to GitHub Issues but can be customized for any issue tracker.
There are several reasons for excluding issue tracker links from commit bodies:
-
Not all issue trackers preserve issues (meaning they can be deleted). This makes make reading historic commits harder to understand why the change was made when the reference no longer works.
-
When disconnected from the internet or working on a laggy connection, it’s hard to understand why a commit was made when all you have is a shorthand issue reference with no supporting context.
-
During the course of a repository’s life, issue trackers can be replaced (rare but does happen). If the old issue tracker service is no longer in use, none of the commit body shorthand will be of any relevance.
Instead of using tracker shorthand syntax, take the time to write a short summary as to why the commit was made. Doing this will make it easier to understand why the commit was made, keeps the commit self-contained, and makes learning about/debugging the commit faster.
Enabled | Severity |
---|---|
true |
error |
Ensures commit bodies don’t contain repeated words. Example:
# Disallowed Necessary to to fix production error. # Allowed Necessary to fix production error.
Enabled | Severity | Defaults |
---|---|---|
false |
error |
includes: |
Ensures all commit signatures are properly signed for improved security and validity of code being committed by various authors. By default, only "Good" signatures are allowed but you can expand this list if desired (although not recommended for security reasons). Valid options are:
-
Bad (B)
-
Error (E)
-
Good (G)
-
None (N)
-
Revoked (R)
-
Unknown (U)
-
Expired (X)
-
Expired Key (Y)
All of the above obtained when using the pretty formats as provided by Git Log.
Enabled | Severity | Defaults |
---|---|---|
true |
error |
maximum: 72 |
Ensures the commit subject length is no more than 72 characters in length. This default is more lenient than the 50/72 rule as it gives one the ability to formulate a more descriptive subject line without being too wordy or suffer being word wrapped.
Automatically ignores fixup! or squash! commit prefixes when calculating subject length.
Enabled | Severity | Defaults |
---|---|---|
true |
error |
includes: (see below) |
delimiter: " " |
Ensures each commit subject uses consistent prefixes that explain what is being committed. The
includes
are case sensitive and default to the following prefixes:
-
Fixed - Identifies what was fixed. The commit should be as small as possible and consist of changes to implementation and spec only. In some cases this might be a single line change. The important point is the change is applied to existing code which corrects behavior that wasn’t properly implemented earlier.
-
Removed - Identifies what was removed. The commit should be as small as possible and consist only of removed lines/files from the existing implementation. This might also mean breaking changes requiring the publishing of a major version release in the future.
-
Added - Identifies what was added. The commit should be as small as possible and consist of implementation and spec. Otherwise, it might be a change to an existing file which adds new behavior.
-
Updated - Identifies what was updated. The commit should be as small as possible and not add or fix existing behavior. This can sometimes be a grey area but is typically reserved for updates to documentation, code comments, dependencies, etc.
-
Refactored - Identifies what was refactored. Refactoring is for changing code structure without changing observable behavior. The commit should be as small as possible and not mix multiple kinds of changes at once. Refactored code should never break existing implementation behavior or corresponding specs because, if that happens, then one of the other four prefixes is what you want to use instead.
In practice, it is quite rare to need a prefix other than what has been detailed above to explain what is being committed. These prefixes are not only short and easy to remember but also have the added benefit of categorizing the commits for building release notes, change logs, etc. This becomes handy when coupled with another tool, Milestoner, for producing consistent project milestones and Git tag histories. For a deeper dive on subject prefixes and good commit messages in general, please read about commit anatomy to learn more. 🎉
Each prefix is delimited by a space which is the default setting but can be customized if desired. Whatever you choose for a delimiter will not affect Git’s special bang prefixes as described in the tip below.
đź’ˇ This analyzer automatically ignores amend!, fixup!, or squash! commit prefixes when used as a Git Hook in order to not disturb interactive rebase workflows.
Enabled | Severity | Defaults |
---|---|---|
true |
error |
excludes: |
Ensures commit subjects are suffixed consistently. The exclude list is case sensitive and prevents the use of punctuation. This is handy when coupled with a tool, like Milestoner, which automates project milestone releases.
Enabled | Severity |
---|---|
true |
error |
Ensures commit subjects don’t contain repeated words. Example:
# Disallowed Added specs specs # Allowed Added specs
Enabled | Severity | Defaults |
---|---|---|
true |
error |
none |
Ensures collaborator name is properly capitalized. Example:
# Disallowed shepherd derrial book # Allowed Shepherd Derrial Book
Enabled | Severity | Defaults |
---|---|---|
true |
error |
none |
Ensures collaborator email address is valid for commit trailer.
# Disallowed Co-authored-by: River Tam <invalid> # Allowed Co-authored-by: River Tam <river@firefly.com>
Enabled | Severity |
---|---|
true |
error |
Ensures collaborator trailer key is correct format.
# Disallowed co-authored-by: River Tam <river@firefly.com> # Allowed Co-authored-by: River Tam <river@firefly.com>
Enabled | Severity | Defaults |
---|---|---|
true |
error |
minimum: 2 |
Ensures collaborator name consists of, at least, a first and last name. Example:
# Disallowed Co-authored-by: River <river@firefly.com> # Allowed Co-authored-by: River Tam <river@firefly.com>
Enabled | Severity | Defaults |
---|---|---|
true |
error |
minimum: 2 |
Ensures commit trailer keys are not duplicated. Example:
# Disallowed Co-authored-by: Shepherd Derrial Book <shepherd@firefly.com> Co-authored-by: Shepherd Derrial Book <shepherd@firefly.com> # Allowed Co-authored-by: Malcolm Reynolds <malcolm@firefly.com> Co-authored-by: Shepherd Derrial Book <shepherd@firefly.com>
Enabled | Severity |
---|---|
true |
error |
Ensures format trailer key is correct format.
# Disallowed format: markdown # Allowed Format: markdown
Enabled | Severity | Defaults |
---|---|---|
true |
error |
includes: |
Ensures format trailer value is a valid value.
# Disallowed Format: plain # Allowed Format: asciidoc
Enabled | Severity |
---|---|
true |
error |
Ensures issue trailer key is correct format.
# Disallowed issue: 123 # Allowed Issue: 123
Enabled | Severity | Defaults |
---|---|---|
true |
error |
includes: |
Ensures issue trailer value is correct format.
# Disallowed Issue: 123+45 # Allowed Issue: 123
Enabled | Severity |
---|---|
true |
error |
Ensures milestone trailer key is correct format.
# Disallowed milestone: patch # Allowed Milestone: patch
Enabled | Severity | Defaults |
---|---|---|
true |
error |
includes: |
Ensures milestone trailer value is correct format for semantic versioning purposes.
# Disallowed Milestone: bogus # Allowed Milestone: patch
Enabled | Severity |
---|---|
true |
error |
Ensures milestone trailers are alphabetically sorted.
# Disallowed Issue: 123 Milestone: patch Format: asciidoc # Allowed Format: asciidoc Issue: 123 Milestone: patch
Enabled | Severity |
---|---|
true |
error |
Ensures reviewer trailer key is correct format.
# Disallowed reviewer: tana # Allowed Reviewer: tana
Enabled | Severity | Defaults |
---|---|---|
true |
error |
includes: |
Ensures reviewer trailer value is correct format for linking/referencing the code review system.
# Disallowed Reviewer: bogus # Allowed Reviewer: tana
Enabled | Severity | Defaults |
---|---|---|
true |
error |
none |
Ensures commit signer trailer name is properly capitalized.
# Disallowed Signed-off-by: jayne cobb # Allowed Signed-off-by: Jayne Cobb
Enabled | Severity | Defaults |
---|---|---|
true |
error |
none |
Ensures commit signer trailer email is properly capitalized.
# Disallowed Signed-off-by: Jayne Cobb <invalid> # Allowed Signed-off-by: Jayne Cobb <jcobb@firefly.com>
Enabled | Severity |
---|---|
true |
error |
Ensures signer trailer key is correct format.
# Disallowed signed-off-by: Jayne Cobb # Allowed Signed-off-by: Jayne Cobb
Enabled | Severity | Defaults |
---|---|---|
true |
error |
minimum: 2 |
Ensures signer name consists of, at least, a first and last name.
# Disallowed Signed-off-by: Jayne # Allowed Signed-off-by: Jayne Cobb
Enabled | Severity |
---|---|
true |
error |
Ensures tracker trailer key is correct format.
# Disallowed tracker: linear # Allowed Tracker: linear
Your default branch configuration is respected no matter if it is set globally or locally. If the
default branch is not set then Git Lint will fall back to master
for backwards compatibility.
When the next major version is released, the default branch fallback will change from master
to
main
. You can set your default branch at any time by running the following from the command line:
git config --add init.defaultBranch main
đź’ˇ When setting your default branch, ensure you use a consistent Git configuration across all of your environments.
This gem supports Git Hooks.
It is highly recommended you manage Git Hooks as global scripts as it’ll reduce project
maintenance costs for you. To configure global Git Hooks, add the following to your
$HOME/.gitconfig
:
[core] hooksPath = ~/.git_template/hooks
Then you can customize Git Hooks for all of your projects. Check out these examples.
If a global configuration is not desired, you can add Git Hooks at a per project level by editing
any of the scripts within the .git/hooks
directory of the repository.
The commit-msg hook — which is the best way to use this gem as a Git Hook — is provided as a
--hook
option. Usage:
git-lint --hook PATH
As shown above, the --hook
command accepts a file path (i.e. .git/COMMIT_EDITMSG
) which
is provided to you by Git within the .git/hooks/commit-msg
script. Here is a working example of
what that script might look like:
#! /usr/bin/env bash
set -o nounset
set -o errexit
set -o pipefail
IFS=$'\n\t'
if ! command -v git-lint > /dev/null; then
printf "%s\n" "[git]: Git Lint not found. To install, run: gem install git-lint."
exit 1
fi
git-lint --hook "${BASH_ARGV[0]}"
Whenever you attempt to add a commit, Git Lint will check your commit for issues prior to saving it.
The post-commit hook is possible via the analyze
command. Usage:
git-lint analyze --commit SHA
The post-commit hook can be used multiple ways but, generally, you’ll want to check the last
commit made. Here is a working example which can be used as a .git/hooks/post-commit
script:
#! /usr/bin/env bash
set -o nounset
set -o errexit
set -o pipefail
IFS=$'\n\t'
if ! command -v git-lint > /dev/null; then
printf "%s\n" "[git]: Git Lint not found. To install, run: gem install git-lint."
exit 1
fi
git-lint analyze --commit $(git log --pretty=format:%H -1)
Whenever a commit has been saved, this script will run Git Lint to check for issues.
You can add Rake support by adding the following to your Rakefile
:
begin
require "git/lint/rake/register"
rescue LoadError => error
puts error.message
end
Git::Lint::Rake::Register.call
Once required and registered, the following tasks will be available (i.e. bundle exec rake -T
):
rake git_lint
This gem automatically configures itself for known CI build servers (see below for details). If you have a build server that is not listed, please log an issue or provide an implementation with support.
Calculation of commits is done by analyzing all feature branch commits ahead of the default branch (i.e. "main"). In other words, git log --oneline main..your_feature_branch
.
Detection and configuration happens automatically by checking the CIRCLECI
environment variable.
No additional setup required!
Detection happens automatically by checking the GITHUB_ACTIONS
environment variable as supplied by
the GitHub environment. The only configuration required is to add a .github/workflows/git_lint.yml
to your repository with the following contents:
name: Git Lint
on: pull_request
jobs:
run:
runs-on: ubuntu-latest
container:
image: ruby:latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
ref: ${{github.head_ref}}
- name: Install
run: gem install git-lint
- name: Analyze
run: git-lint --analyze
The above will ensure Git Lint runs as an additional check on each Pull Request.
Detection and configuration happens automatically by checking the NETLIFY
environment variable. No
additional setup required!
In addition to what is described above and automated for you, the following style guide is also worth considering:
-
Use a Git Rebase Workflow instead of a Git Merge Workflow.
-
Use
git commit --amend
when fixing a previous commit, addressing code review feedback, etc. -
Use
git commit --fixup
when fixing an earlier commit, addressing code review feedback, etc., and don’t need to modify the original commit message. -
Use
git commit --squash
when fixing an earlier commit, addressing code review feedback, etc., and want to combine multiple commit messages into a single commit message. Avoid using squash to blindly combine multiple commit messages without editing them into a single, coherent message. -
Use
git rebase --interactive
when cleaning up commit history, order, messages, etc. This should be done prior to submitting a code review or when code review feedback has been addressed and you are ready to rebase ontomain
. -
Use
git push --force-with-lease
instead ofgit push --force
when pushing changes after an interactive rebasing session. -
Avoid checking in development-specific configuration files (add to
.gitignore
instead). -
Avoid checking in sensitive information (i.e. security keys, passphrases, etc).
-
Avoid "WIP" (a.k.a. "Work in Progress") commits and/or code review labels. Be confident with your code and colleagues' time. Use branches, stashes, etc. instead — share a link to a feature branch diff if you have questions/concerns during development.
-
Avoid using Git Submodules. This practice leads to complicated project cloning, deployments, maintenance, etc. Use separate repositories to better organize and split out this work. Sophisticated package managers, like Bundler, exist to manage these dependencies better than what multiple Git Submodules can accomplish.
-
Avoid using Git LFS for tracking binary artifacts/resources. These files are not meant for version control and lead to large repositories that are time consuming to clone/deploy. Use storage managers like Git Annex, Amazon S3, or LakeFS which are better suited for binary assets that don’t change often.
Ensure signed commits, pushes, and tags are enabled within your global Git Configuration to reduce an attack vector. Run the following commands to enable:
git config --global commit.gpgSign true
git config --global push.gpgSign true
git config --global tag.gpgSign true
-
Use a commit subject that explains what is being committed.
-
Use a commit message body that explains why the commit is necessary. Additional considerations:
-
If the commit has a dependency to the previous commit or is a precursor to the commit that will follow, make sure to explain that.
-
Include links to dependent projects, stories, etc. if available.
-
-
Use small, atomic commits:
-
Easier to review and provide feedback.
-
Easier to review implementation and corresponding tests.
-
Easier to document with detailed subjects (especially when grouped together in a pull request).
-
Easier to reword, edit, squash, fix, or drop when interactively rebasing.
-
Easier to combine together versus tearing apart a larger commit into smaller commits.
-
-
Use logically ordered commits:
-
Each commit should tell a story and be a logical building block to the next commit.
-
Each commit should, ideally, be the implementation plus corresponding test. Avoid committing changes that are a jumble of mixed ideas as they are hard to decipher and a huge insult not only to the reviewer but your future self.
-
Each commit, when reviewed in order, should be able to explain how the feature or bug fix was completed and implemented properly.
-
-
Keep refactored code separate from behavioral changes. This makes the review process easier because you don’t have to sift through all the line and format changes to figure out what is new or changed.
-
Use feature branches for new work.
-
Maintain branches by rebasing upon
main
on a regular basis.
-
Use tags to denote milestones/releases:
-
Makes it easier to record milestones and capture associated release notes.
-
Makes it easier to compare differences between versions.
-
Provides a starting point for debugging production issues (if any).
-
-
Avoid rebasing a shared branch. If you must do this, clear communication should be used to warn those ahead of time, ensure that all of their work is checked in, and that their local branch is deleted first.
-
Use hooks to augment and automate your personal workflow such as checking code quality, detecting forgotten debug statements, etc.
-
Use hooks globally rather than locally per project. Doing this applies the same functionality across all projects automatically, reduces maintenance per project, and provides consistency across all projects. This can best be managed via your Dotfiles.
-
Avoid forcing global or local project hooks as a team-wide mandate. Hooks are a personal tool much like editors or other tools one choose to do their work. For team consistency, use a continuous integration build server instead.
For an in depth look at how to conduct code reviews, please read my article on this subject to learn more.
To contribute, run:
git clone https://github.com/bkuhlmann/git-lint
cd git-lint
bin/setup
You can also use the IRB console for direct access to all objects:
bin/console
-
Built with Gemsmith.
-
Engineered by Brooke Kuhlmann.