/ 
Git-Hooks-0.043
River stage one • 5 direct dependents • 5 total dependents
/ Git::Hooks::CheckLog

NAME

Git::Hooks::CheckLog - Git::Hooks plugin to enforce commit log policies.

VERSION

version 0.043

DESCRIPTION

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.

  • 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 more important ones.

This plugin allows one to enforce most of the more 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

NAME

Git::Hooks::CheckLog - Git::Hooks plugin to enforce commit log policies.

CONFIGURATION

The plugin is configured by the following git options.

githooks.checklog.title-required [01]

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.

githooks.checklog.title-max-width N

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.

githooks.checklog.title-period [deny|allow|require]

This option defines the policy regarding the title's ending in a period (a.k.a. full stop ('.')). 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.

githooks.checklog.body-max-width N

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.

githooks.checklog.match [!]REGEXP

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 isn't used, the log has to match the REGEXP. Otherwise, the log must not match the REGEXP.

githooks.checklog.spelling [01]

This option makes the plugin spell check the commit log message using Text::SpellChecker. Any spell error will cause the commit or push to abort.

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).

githooks.checklog.spelling-lang ISO

The Text::SpellChecker module uses defaults to infer which language is must use to spell check the message. You can make it use a particular language passing its ISO code to this option.

i18n.commitEncoding ENCODING

This is not a CheckLog option. In fact, this is a native option of Git, which semantics is defined in git help config. It tells Git which character encoding the commit messages are stored in and defaults to utf-8.

When this plugin is used in the commit-msg hook, the message file is read and its contents are checked against the encoding specified by this option.

EXPORTS

This module exports the following routines that can be used directly without using all of Git::Hooks infrastructure.

check_message_file GIT, MSGFILE

This is the routine used to implement the commit-msg hook. It needs a Git::More object and the name of a file containing the commit message.

check_affected_refs GIT

This is the routing used to implement the update and the pre-receive hooks. It needs a Git::More object.

check_patchset GIT, HASH

This is the routine used to implement the patchset-created Gerrit hook. It needs a Git::More object and the hash containing the arguments passed to the hook by Gerrit.

REFERENCES

  • 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 the 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.

AUTHOR

Gustavo L. de M. Chaves <gnustavo@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 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.