Git::Hooks::CheckLog - Git::Hooks plugin to enforce commit log policies
version 2.1.7
This Git::Hooks plugin hooks itself to the hooks below to enforce policies on the commit log messages.
commit-msg
This hook is invoked during the commit, to check if the commit log message complies.
update
This hook is invoked multiple times in the remote repository during git push, once per branch being updated, to check if the commit log messages of all commits being pushed comply.
git push
pre-receive
This hook is invoked once in the remote repository during git push, to check if the commit log messages of all commits being pushed comply.
ref-update
This hook is invoked when a push request is received by Gerrit Code Review, to check if the commit log messages of all commits being pushed comply.
patchset-created
This hook is invoked when a push request is received by Gerrit Code Review for a virtual branch (refs/for/*), to check if the commit log messages of all commits being pushed comply.
Projects using Git, probably more than projects using any other version control system, have a tradition of establishing policies on the format of commit log messages. The REFERENCES section below lists some of the most important.
This plugin allows one to enforce most of the established policies. The default configuration already enforces the most common one.
To enable it you should add it to the githooks.plugin configuration option:
git config --add githooks.plugin CheckLog
The plugin is configured by the following git options.
By default, the message of every commit is checked. If you want to have them checked only for some refs (usually some branch under refs/heads/), you may specify them with one or more instances of this option.
The refs can be specified as a complete ref name (e.g. "refs/heads/master") or by a regular expression starting with a caret (^), which is kept as part of the regexp (e.g. "^refs/heads/(master|fix)").
^
By default, the message of every commit is checked. If you want to exclude some refs (usually some branch under refs/heads/), you may specify them with one or more instances of this option.
The refs can be specified as in the same way as to the ref option above.
ref
Note that the ref option has precedence over the noref option, i.e., if a reference matches both options it will be checked.
noref
The first line of a Git commit log message is usually called the 'title'. It must be separated by the rest of the message (it's 'body') by one empty line. This option, which is 1 by default, makes the plugin check if there is a proper title in the log message.
This option specifies a limit to the width of the title's in characters. It's 50 by default. If you set it to 0 the plugin imposes no limit on the title's width.
This option defines the policy regarding the title's ending in a period ('.'). It can take three values:
deny
This means that the title SHOULD NOT end in a period. This is the default value of the option, as this is the most common policy.
allow
This means that the title MAY end in a period, i.e., it doesn't matter.
require
This means that the title SHOULD end in a period.
This option may be specified more than once. It defines a list of regular expressions that will be matched against the title. If the '!' prefix is used, the title must not match the REGEXP.
This option specifies a limit to the width of the commit log message's body lines, in characters. It's 72 by default. If you set it to 0 the plugin imposes no limit on the body line's width.
Only lines starting with a non-whitespace character are checked against the limit. It's a common style to quote things with indented lines and we like to make those lines free of any restriction in order to keep the quoted text authentic.
This option may be specified more than once. It defines a list of regular expressions that will be matched against the commit log messages. If the '!' prefix is used, the log must not match the REGEXP.
This option makes the plugin spell check the commit log message using Text::SpellChecker. Any spelling error will cause the commit or push to abort.
Text::SpellChecker
Note that Text::SpellChecker isn't required to install Git::Hooks. So, you may see errors when you enable this check. Please, refer to the module's own documentation to see how to install it and its own dependencies (which are Text::Hunspell or Text::Aspell).
Git::Hooks
Text::Hunspell
Text::Aspell
The Text::SpellChecker module uses defaults to infer which language it must use to spell check the message. You can make it use a particular language passing its ISO code to this option.
This option requires the commit to have at least one Signed-off-by footer.
Signed-off-by
git-commit(1) Manual Page
This Git manual page has a section called DISCUSSION which discusses some common log message policies.
Linus Torvalds GitHub rant
In this note, Linus says why he dislikes GitHub's pull request interface, mainly because it doesn't allow him to enforce log message formatting policies.
MediaWiki Git/Commit message guidelines
This document defines MediaWiki's project commit log message guidelines.
Proper Git Commit Messages and an Elegant Git History
This is a good discussion about commit log message formatting and the reasons behind them.
GIT Commit Good Practice
This document defines the OpenStack's project commit policies.
A Note About Git Commit Messages
This blog post argues briefly and convincingly for the use of a particular format for Git commit messages.
Git Commit Messages: 50/72 Formatting
This StackOverflow question has a good discussion about the topic.
What do you try to leave in your commit messages?
A blog post from Kohsuke Kawaguchi, Jenkins's author, explaining what information he usually includes in his commit messages and why.
Gustavo L. de M. Chaves <gnustavo@cpan.org>
This software is copyright (c) 2017 by CPqD <www.cpqd.com.br>.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Git::Hooks, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Git::Hooks
CPAN shell
perl -MCPAN -e shell install Git::Hooks
For more information on module installation, please visit the detailed CPAN module installation guide.