How to use the command gitlint (with examples)

Gitlint is a tool that checks the style of commit messages in a Git repository. It helps ensure that commit messages follow a consistent format and meet certain criteria. This can be useful for maintaining a clean commit history and for facilitating collaboration within a development team.

Use case 1: Check the last commit message

Code:

gitlint

Motivation: Checking the last commit message can be helpful for quickly reviewing the latest changes and ensuring that the commit message follows the desired style guidelines.

Explanation: When the gitlint command is run without any arguments, it checks the commit message of the most recent commit in the current branch. It applies the defined rules to the commit message and reports any violations.

Example output:

✔  no-trailing-punctuation (C1): Subject does not end with punctuation marks (.|?|!)
✔  subject-line-conventions (C3): Subject line should be capitalized
×  subject-line-length (C4): Subject line should not exceed 50 characters (it currently has 55 characters)
×  body-line-length (C5): Lines should not exceed 72 characters (line #2 has 88 characters)
×  signed-off-by (F2): Commit has no Signed-off-by footer

5 issues found (3 errors, 2 warnings); aborting commit.

Use case 2: The range of commits to lint

Code:

gitlint --commits single_refspec_argument

Motivation: Linting a range of commits can be useful when reviewing or analyzing changes made within a specific period of time or on a specific branch.

Explanation: The --commits option allows you to specify a range of commits to be linted. By providing a valid single refspec argument, you can specify a range of commits to be included in the linting process. This can be a branch name, a commit hash, or a commit range.

Example output:

✔  no-trailing-punctuation (C1): Subject does not end with punctuation marks (.|?|!)
✔  subject-line-conventions (C3): Subject line should be capitalized

2 issues found (0 errors, 2 warnings); aborting commit linting.

Use case 3: Path to a directory or Python module with extra user-defined rules

Code:

gitlint --extra-path path/to/directory

Motivation: Providing a path to a directory with extra user-defined rules allows for customizing the linting process based on specific project requirements or conventions.

Explanation: The --extra-path option allows you to specify a path to a directory or Python module that contains additional user-defined rules for the linting process. This makes it possible to extend the default set of rules and apply project-specific guidelines.

Example output:

✔  no-trailing-punctuation (C1): Subject does not end with punctuation marks (.|?|!)
✔  subject-line-conventions (C3): Subject line should be capitalized

2 issues found (0 errors, 2 warnings); aborting commit linting.

Use case 4: Start a specific CI job

Code:

gitlint --target path/to/target_directory

Motivation: Starting a specific CI job allows for integrating the linting process into a continuous integration (CI) pipeline, ensuring that commit messages are checked automatically as part of the build or deployment process.

Explanation: The --target option specifies the directory where the CI job is located. By providing the path to the target directory, you can start the specified CI job and trigger the linting process as part of the CI pipeline.

Example output:

✔  no-trailing-punctuation (C1): Subject does not end with punctuation marks (.|?|!)
✔  subject-line-conventions (C3): Subject line should be capitalized

2 issues found (0 errors, 2 warnings); aborting commit linting.

Use case 5: Path to a file containing a commit-msg

Code:

gitlint --msg-filename path/to/filename

Motivation: Specifying a path to a file containing a commit message can be useful when testing the linting process on specific commit messages.

Explanation: The --msg-filename option allows you to provide the path to a file that contains the commit message to be linted. This is helpful for testing purposes or when you want to lint a specific commit message rather than the latest commit in the repository.

Example output:

✔  no-trailing-punctuation (C1): Subject does not end with punctuation marks (.|?|!)
✔  subject-line-conventions (C3): Subject line should be capitalized

2 issues found (0 errors, 2 warnings); aborting commit linting.

Use case 6: Read staged commit meta-info from the local repository

Code:

gitlint --staged

Motivation: Reading staged commit meta-info from the local repository allows for checking commits that are in the staging area but have not been committed yet.

Explanation: The --staged option reads the staged commit meta-info, including the commit message, from the local repository. This is useful for reviewing and linting commits that are in the staging area before they are actually committed.

Example output:

✔  no-trailing-punctuation (C1): Subject does not end with punctuation marks (.|?|!)
✔  subject-line-conventions (C3): Subject line should be capitalized

2 issues found (0 errors, 2 warnings); aborting commit linting.

Conclusion:

Gitlint is a powerful tool for checking the style of commit messages in a Git repository. It helps maintain consistency and ensures that commit messages follow the desired format and criteria. By understanding and utilizing the various use cases of the gitlint command, developers can improve the quality of their commit messages and promote effective collaboration within their development teams.