App::GitHooks - Extensible plugins system for git hooks.
Version 1.6.1
App::GitHooks is an extensible and easy to configure git hooks framework that supports many plugins.
App::GitHooks
Here's an example of it in action, running the pre-commit hook checks before the commit message can be entered:
pre-commit
Here is another example, with a Perl file that fails compilation this time:
Install this distribution (with cpanm or your preferred CPAN client):
cpanm App::GitHooks
Install the plugins you are interested in (with cpanmor your prefered CPAN client), as App::GitHooks does not bundle them. See the list of plugins below, but for example:
cpanm App::GitHooks::Plugin::BlockNOCOMMIT cpanm App::GitHooks::Plugin::DetectCommitNoVerify ...
Go to the git repository for which you want to set up git hooks, and run:
githooks install
Enjoy!
App::GitHooks requires git v1.7.4.1 or above.
applypatch-msg
pre-applypatch
post-applypatch
prepare-commit-msg
commit-msg
post-commit
pre-rebase
post-checkout
post-merge
pre-receive
update
post-receive
post-update
pre-auto-gc
post-rewrite
App::GitHooks::Plugin::BlockNOCOMMIT
Prevent committing code with #NOCOMMIT mentions.
App::GitHooks::Plugin::BlockProductionCommits
Prevent commits in a production environment.
App::GitHooks::Plugin::DetectCommitNoVerify
Find out when someone uses --no-verify and append the pre-commit checks to the commit message.
App::GitHooks::Plugin::ForceRegularUpdate
Force running a specific tool at regular intervals.
App::GitHooks::Plugin::MatchBranchTicketID
Detect discrepancies between the ticket ID specified by the branch name and the one in the commit message.
App::GitHooks::Plugin::PerlCompile
Verify that Perl files compile without errors.
App::GitHooks::Plugin::PerlCritic
Verify that all changes and addition to the Perl files pass PerlCritic checks.
App::GitHooks::Plugin::PerlInterpreter
Enforce a specific Perl interpreter on the first line of Perl files.
App::GitHooks::Plugin::PgBouncerAuthSyntax
Verify that the syntax of PgBouncer auth files is correct.
App::GitHooks::Plugin::PrependTicketID
Derive a ticket ID from the branch name and prepend it to the commit-message.
App::GitHooks::Plugin::RequireCommitMessage
Require a commit message.
App::GitHooks::Plugin::RequireTicketID
Verify that staged Ruby files compile.
App::GitHooks::Plugin::ValidatePODFormat
Validate POD format in Perl and POD files.
App::GitHooks::Plugin::RubyCompile
App::GitHooks::Plugin::PreventTrailingWhitespace
Prevent trailing whitespace from being committed.
App::GitHooks uses Config::Tiny, so the configuration should follow the following format:
general_key_1 = value general_key_2 = value [section_1] section_1_key 1 = value
The file is divided between the global configuration options at the beginning of the file (such as general_key_1 above) and plugin specific configuration options which are located in distinct sections (such as section_1_key in the [section_1] section).
general_key_1
section_1_key
[section_1]
App::GitHooks supports setting custom options by creating one of the following files, which are searched in descending order of preference:
A file of any name anywhere on your system, if you set the environment variable GITHOOKSRC_FORCE to its path.
GITHOOKSRC_FORCE
Note that you should normally use GITHOOKSRC. This option is provided mostly for testing purposes, when configuration options for testing in a reliable manner are of the utmost importance and take precedence over any repository-specific settings.
GITHOOKSRC
A .githooksrc file at the root of the git repository.
.githooksrc
The settings will then only apply to that repository.
A file of any name anywhere on your system, if you set the environment variable GITHOOKSRC to its path.
Note that .githooksrc files at the top of a repository or in a user's home directory will take precedence over a file specified by the GITHOOKSRC environment variable.
A .githooksrc file in the home directory of the current user.
The settings will then apply to all the repositories that have hooks set up. Note that if .githooksrc file is defined at the root of a repository, that configuration file will take precedence over the one defined in the home directory of the current user (as it is presumably more specific). Auto-merge of options across multiple .githooksrc files in an inheritance fashion is not currently supported.
project_prefixes
A comma-separated list of project prefixes, in case you want to use this in extract_ticket_id_from_commit or extract_ticket_id_from_branch.
extract_ticket_id_from_commit
extract_ticket_id_from_branch
project_prefixes = OPS, DEV
A regular expression with _one_ capturing group that will be applied to the first line of a commit message to extract the ticket ID referenced, if there is one.
extract_ticket_id_from_commit = /^($project_prefixes-\d+|--): /
A regular expression with _one_ capturing group that will be applied to branch names to extract a ticket ID. This allows creating one branch per ticket and having the hooks check that the commit messages and the branch names are in sync.
extract_ticket_id_from_branch = /^($project_prefixes-?\d+)/
normalize_branch_ticket_id
A replacement expression that normalizes the ticket ID captured with extract_ticket_id_from_branch.
normalize_branch_ticket_id = s/^(.*?)-?(\d+)$/\U$1-$2/
skip_directories
A regular expression to filter the directory names that should be skipped when analyzing files as part of file-level checks.
skip_directories = /^cpan(?:-[^\/]+)?\//
force_plugins
A comma-separated list of the plugins that must be present on the system and will be executed. If any plugins from this list are missing, the action will error out. If any other plugins not in this list are installed on the system, they will be ignored.
force_plugins = App::GitHooks::Plugin::ValidatePODFormat, App::GitHooks::Plugin::RequireCommitMessage
limit_plugins
Deprecated. Use force_plugins instead.
force_interactive
Force the application to consider that the terminal is interactive (`1`) or non-interactive (`0`) independently of whether the actual STDOUT is interactive or not.
force_use_colors
Force the output to use colors (`1`) or to not use colors (`0`) independently of the ability of STDOUT to display colors.
force_is_utf8
Allows the output to use utf-8 characters (`1`) or not (`0`), independently of whether the output declares supporting utf-8.
commit_msg_no_edit
Allows skipping the loop to edit the message when the commit message checks failed.
Run the specified hook.
App::GitHooks::run( name => $name, arguments => \@arguments, );
Arguments:
name (mandatory)
The name of the git hook calling this class. See the "VALID GIT HOOK NAMES" section for acceptable values.
arguments (optional)
An arrayref of arguments passed originally to the git hook.
exit (optional, default 1)
Indicate whether the method should exit (1) or simply return the exit status without actually exiting (0).
Create a new App::GitHooks object.
my $app = App::GitHooks->new( name => $name, arguments => \@arguments, );
Clone the current object and override its properties with the arguments specified.
my $cloned_app = $app->clone( name => $hook_name, # optional );
name (optional)
The name of the invoking hook.
Return an arrayref of all the plugins installed and available for a specific git hook on the current system.
my $plugins = $app->get_hook_plugins( $hook_name );
$hook_name
The name of the git hook for which to find available plugins.
Return a hashref of the plugins available for every git hook.
my $all_plugins = $self->get_all_plugins();
Retrieve the configuration information for the current project.
my $config = $app->get_config();
By default App::GitHooks detects whether it is running in interactive mode, but this allows forcing it to run in non-interactive mode.
# Retrieve the current setting. my $force_non_interactive = $app->force_non_interactive(); # Force non-interactive mode. $app->force_non_interactive( 1 ); # Go back to the default behavior of detecting the current mode. $app->force_non_interactive( 0 );
Return a character to use to indicate a failure.
my $failure_character = $app->get_failure_character()
Return a character to use to indicate a success.
my $success_character = $app->get_success_character()
Return a character to use to indicate a warning.
my $warning_character = $app->get_warning_character()
Return a App::GitHooks::StagedChanges object corresponding to the changes staged in the current project.
App::GitHooks::StagedChanges
my $staged_changes = $app->get_staged_changes();
Allows disabling the use of colors in App::GitHooks's output.
# Retrieve the current setting. my $use_colors = $app->use_colors(); # Disable colors in the output. $app->use_colors( 0 );
Return the underlying Git::Repository object for the current project.
Git::Repository
my $repository = $app->get_repository();
Return the name of the git hook that called the current instance.
my $hook_name = $app->get_hook_name();
Return the arguments passed originally to the git hook.
my $command_line_arguments = $app->get_command_line_arguments();
Return the App::GitHooks::Terminal object associated with the current instance.
App::GitHooks::Terminal
my $terminal = $app->get_terminal();
Format information while respecting the format width and indentation.
my $string = $app->wrap( $information, $indent );
Print text with colors.
$app->color( $color, $text );
Convert a dash-separated string to camelcase.
my $camelcase_string = App::GitHooks::_to_camelcase( $string );
This function is useful to convert git hook names (commit-msg) to module names (CommitMsg).
Symlink your git hooks under .git/hooks to a file with the following content:
#!/usr/bin/env perl use strict; use warnings; use App::GitHooks; App::GitHooks->run( name => $0, arguments => \@ARGV, );
All you need to do then is install the plugins you are interested in!
This distribution also includes a hooks/ directory that you can symlink / copy to .git/hooks/ instead , to get all the hooks set up properly in one swoop.
hooks/
.git/hooks/
Important: adjust /usr/bin/env perl as needed, if that line is not a valid interpreter, your git actions will fail with error: cannot run .git/hooks/[hook name]: No such file or directory.
/usr/bin/env perl
error: cannot run .git/hooks/[hook name]: No such file or directory
Please report any bugs or feature requests through the web interface at https://github.com/guillaumeaubert/App-GitHooks/issues/new. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
You can find documentation for this module with the perldoc command.
perldoc App::GitHooks
You can also look for information at:
GitHub's request tracker
https://github.com/guillaumeaubert/App-GitHooks/issues
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/app-githooks
CPAN Ratings
http://cpanratings.perl.org/d/app-githooks
MetaCPAN
https://metacpan.org/release/App-GitHooks
Guillaume Aubert, <aubertg at cpan.org>.
<aubertg at cpan.org>
Copyright 2013-2015 Guillaume Aubert.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/
To install App::GitHooks, copy and paste the appropriate command in to your terminal.
cpanm
CPAN shell
perl -MCPAN -e shell install App::GitHooks
For more information on module installation, please visit the detailed CPAN module installation guide.