NAME
Git::Hooks - A framework for implementing Git hooks.
VERSION
version 0.026
SYNOPSIS
A single script can implement several Git hooks:
#!/usr/bin/env perl
use Git::Hooks;
PRE_COMMIT {
my ($git) = @_;
# ...
};
COMMIT_MSG {
my ($git, $msg_file) = @_;
# ...
};
run_hook($0, @ARGV);
Or you can use Git::Hooks plugins or external hooks, driven by the single script below. These hooks are enabled by Git configuration options. (More on this later.)
#!/usr/bin/env perl
use Git::Hooks;
run_hook($0, @ARGV);
INTRODUCTION
"Git is a fast, scalable, distributed revision control system with an unusually rich command set that provides both high-level operations and full access to internals. (https://github.com/gitster/git#readme)"
In order to really understand what this is all about you need to understand Git http://git-scm.org/ and its hooks. You can read everything about this in the documentation references on that site http://git-scm.com/documentation.
A hook is a specifically named program that is called by the git program during the execution of some operations. At the last count, there were exactly 16 different hooks which can be used (http://schacon.github.com/git/githooks.html). They must reside under the .git/hooks
directory in the repository. When you create a new repository, you get some template files in this directory, all of them having the .sample
suffix and helpful instructions inside explaining how to convert them into working hooks.
When Git is performing a commit operation, for example, it calls these four hooks in order: pre-commit
, prepare-commit-msg
, commit-msg
, and post-commit
. The first three can gather all sorts of information about the specific commit being performed and decide to reject it in case it doesn't comply to specified policies. The post-commit
can be used to log or alert interested parties about the commit just done.
There are several useful hook scripts available elsewhere, e.g. https://github.com/gitster/git/tree/master/contrib/hooks and http://google.com/search?q=git+hooks. However, when you try to combine the functionality of two or more of those scripts in a single hook you normally end up facing two problems.
- Complexity
-
In order to integrate the functionality of more than one script you have to write a driver script that's called by Git and calls all the other scripts in order, passing to them the arguments they need. Moreover, some of those scripts may have configuration files to read and you may have to maintain several of them.
- Inefficiency
-
This arrangement is inefficient in two ways. First because each script runs as a separate process, which usually have a high start up cost because they are, well, scripts and not binaries. (For a dissent view on this, see http://gnustavo.wordpress.com/2012/06/28/programming-languages-start-up-times/.) And second, because as each script is called in turn they have no memory of the scripts called before and have to gather the information about the transaction again and again, normally by calling the
git
command, which spawns yet another process.
Git::Hooks is a framework for implementing Git and driving existing external hooks in a way that tries to solve these problems.
Instead of having separate scripts implementing different functionality you may have a single script implementing all the functionality you need either directly or using some of the existing plugins, which are implemented by Perl scripts in the Git::Hooks:: namespace. This single script can be used to implement all standard hooks, because each hook knows when to perform based on the context in which the script was called.
If you already have some handy hooks and want to keep using them, don't worry. Git::Hooks can drive external hooks very easily.
USAGE
There are a few simple steps you should do in order to set up Git::Hooks so that you can configure it to use some predefined plugins or start coding your own hooks.
The first step is to create a generic script that will be invoked by Git for every hook. If you are implementing hooks in your local repository, go to its .git/hooks
sub-directory. If you are implementing the hooks in a bare repository in your server, go to its hooks
sub-directory.
You should see there a bunch of files with names ending in .sample
which are hook examples. Create a three-line script called, e.g., git-hooks.pl
, in this directory like this:
$ cd /path/to/repo/.git/hooks
$ cat >git-hooks.pl <<EOT
#!/usr/bin/env perl
use Git::Hooks;
run_hook($0, @ARGV);
EOT
$ chmod +x git-hooks.pl
Now you should create symbolic links pointing to it for each hook you are interested in. For example, if you are interested in a commit-msg
hook, create a symbolic link called commit-msg
pointing to the git-hooks.pl
file. This way, Git will invoke the generic script for all hooks you are interested in. (You may create symbolic links for all 16 hooks, but this will make Git call the script for all hooked operations, even for those that you may not be interested in. Nothing wrong will happen, but the server will be doing extra work for nothing.)
$ ln -s git-hooks.pl commit-msg
$ ln -s git-hooks.pl post-commit
$ ln -s git-hooks.pl pre-receive
As is, the script won't do anything. You have to implement some hooks in it, use some of the existing plugins, or set up some external plugins to be invoked properly. Either way, the script should end with a call to run_hook
passing to it the name with which it was called ($0
) and all the arguments it received (@ARGV
).
Implementing Hooks
You may implement your own hooks using one of the hook directives described in the HOOK DIRECTIVES section below. Your hooks may be implemented in the generic script you have created. They must be defined after the use Git::Hooks
line and before the run_hooks()
line. For example:
# Check if every added/updated file is smaller than a fixed limit.
my $LIMIT = 10 * 1024 * 1024; # 10MB
PRE_COMMIT {
my ($git) = @_;
my @changed = $git->command(qw/diff --cached --name-only --diff-filter=AM/);
foreach ($git->command('ls-files' => '-s', @changed)) {
chomp;
my ($mode, $sha, $n, $name) = split / /;
my $size = $git->command('cat-file' => '-s', $sha);
$size <= $LIMIT
or die "File '$name' has $size bytes, more than our limit of $LIMIT.\n";
}
};
# Check if every added/changed Perl file respects Perl::Critic's code
# standards.
PRE_COMMIT {
my ($git) = @_;
my %violations;
my @changed = grep {/\.p[lm]$/} $git->command(qw/diff --cached --name-only --diff-filter=AM/);
foreach ($git->command('ls-files' => '-s', @changed)) {
chomp;
my ($mode, $sha, $n, $name) = split / /;
require Perl::Critic;
state $critic = Perl::Critic->new(-severity => 'stern', -top => 10);
my $contents = $git->command('cat-file' => $sha);
my @violations = $critic->critique(\$contents);
$violations{$name} = \@violations if @violations;
}
if (%violations) {
# FIXME: this is a lame way to format the output.
require Data::Dumper;
die "Perl::Critic Violations:\n", Data::Dumper::Dumper(\%violations), "\n";
}
};
Note that you may define several hooks for the same operation. In the above example, we've defined two PRE_COMMIT hooks. Both are going to be executed when Git invokes the generic script during the pre-commit phase.
You may implement different kinds of hooks in the same generic script. The function run_hooks()
will activate just the ones for the current Git phase.
Using Plugins
There are several hooks already implemented as plugin modules under the namespace Git::Hooks::
, which you can use. The main ones are described succinctly below. Please, see their own documentation for more details.
- Git::Hooks::CheckAcls
-
Allow you to specify Access Control Lists to tell who can commit or push to the repository and affect which Git refs.
- Git::Hooks::CheckJira
-
Integrate Git with the JIRA http://www.atlassian.com/software/jira/phase ticketing system by requiring that every commit message cites valid JIRA issues.
- Git::Hooks::CheckStructure
-
Check if newly added files and references (branches and tags) comply with specified policies, so that you can impose a strict structure to the repository's file and reference hierarchies.
Each plugin may be used in one or, sometimes, multiple hooks. Their documentation is explicit about this.
These plugins are configured by Git's own configuration framework, using the git config
command or by directly editing Git's configuration files. (See git help config
to know more about Git's configuration infrastructure.)
The CONFIGURATION section below explains this in more detail.
Invoking external hooks
Since the default Git hook scripts are taken by the symbolic links to the Git::Hooks generic script, you must install any other hooks somewhere else. By default, the run_hook
routine will look for external hook scripts in the directory .git/hooks.d
(which you must create) under the repository. Below this directory you should have another level of directories, named after the default hook names, under which you can drop your external hooks.
For example, let's say you want to use some of the hooks in the standard Git package (https://github.com/gitster/git/blob/b12905140a8239ac687450ad43f18b5f0bcfb62e/contrib/hooks/update-paranoid). You should copy each of those scripts to a file under the appropriate hook directory, like this:
.git/hooks.d/pre-auto-gc/pre-auto-gc-battery
.git/hooks.d/pre-commit/setgitperms.perl
.git/hooks.d/post-receive/post-receive-email
.git/hooks.d/update/update-paranoid
Note that you may install more than one script under the same hook-named directory. The driver will execute all of them in a non-specified order. If any of them exits abnormally, the driver will exit with an appropriate error message.
CONFIGURATION
Git::Hooks is configured via Git's own configuration infrastructure. There are a few global options which are described below. Each plugin may define other specific options which are described in their own documentation.
You should get comfortable with git config
command (read git help config
) to know how to configure Git::Hooks.
When you invoke run_hook
, the command git config --list
is invoked to grok all configuration affecting the current repository. Note that this will fetch all --system
, --global
, and --local
options, in this order. You may use this mechanism to define configuration global to a user or local to a repository.
githooks.HOOK PLUGIN
To enable a plugin you must register it to the appropriate Git hook. For instance, if you want to register the CheckJira
plugin in the update
hook, you must do this:
$ git config --add githooks.update CheckJira
And if you want to register the CheckAcls
plugin in the pre-receive
hook, you must do this:
$ git config --add githooks.pre-receive CheckAcls
The complete list of Git hooks that can be used is this:
- githooks.applypatch-msg
- githooks.pre-applypatch
- githooks.post-applypatch
- githooks.pre-commit
- githooks.prepare-commit-msg
- githooks.commit-msg
- githooks.post-commit
- githooks.pre-rebase
- githooks.post-checkout
- githooks.post-merge
- githooks.pre-receive
- githooks.update
- githooks.post-receive
- githooks.post-update
- githooks.pre-auto-gc
- githooks.post-rewrite
Note that you may enable more than one plugin to the same hook. For instance, you may enable both CheckAcls
and CheckJira
for the update
hook:
$ git config --add githooks.update CheckAcls
$ git config --add githooks.update CheckJira
And you may enable the same plugin in more than one hook, if it makes sense to do so. For instance:
$ git config --add githooks.commit-msg CheckJira
$ git config --add githooks.pre-receive CheckJira
(Up to version 0.022 of Git::Hooks, the plugin names were in the form check-jira.pl
. The old form is still valid to preserve compatibility, but the standard CamelCase form for Perl module names are now preferred. The '.pl' extension in the plugin name is optional.)
githooks.plugins DIR
The plugins enabled for a hook are searched for in three places. First they're are searched for in the githooks
directory under the repository path (usually in .git/githooks
), so that you may have repository specific hooks (or repository specific versions of a hook).
Then, they are searched for in every directory specified with the githooks.plugins
option. You may set it more than once if you have more than one directory holding your hooks.
Finally, they are searched for in Git::Hooks installation.
The first match is taken as the desired plugin, which is executed and the search stops. So, you may want to copy one of the standard plugins and change it to suit your needs better. (Don't shy away from sending your changes back to us, though.)
githooks.externals [01]
By default the driver script will look for external hooks after executing every enabled plugins. You may disable external hooks invocation by setting this option to 0.
githooks.hooks DIR
You can tell this plugin to look for external hooks in other directories by specifying them with this option. The directories specified here will be looked for after the default directory .git/hooks.d
, so that you can use this option to have some global external hooks shared by all of your repositories.
Please, see the plugins documentation to know about their own configuration options.
githooks.groups GROUPSPEC
You can define user groups in order to make it easier to configure access control plugins. Use this option to tell where to find group definitions in one of these ways:
- file:PATH/TO/FILE
-
As a text file named by PATH/TO/FILE, which may be absolute or relative to the hooks current directory, which is usually the repository's root in the server. It's syntax is very simple. Blank lines are skipped. The hash (#) character starts a comment that goes to the end of the current line. Group definitions are lines like this:
groupA = userA userB @groupB userC
Each group must be defined in a single line. Spaces are significant only between users and group references.
Note that a group can reference other groups by name. To make a group reference, simple prefix its name with an at sign (@). Group references must reference groups previously defined in the file.
- GROUPS
-
If the option's value doesn't start with any of the above prefixes, it must contain the group definitions itself.
githooks.userenv STRING
When Git is performing its chores in the server to serve a push request it's usually invoked via the SSH or a web service, which take care of the authentication procedure. These services normally make the authenticated user name available in an environment variable. You may tell this hook which environment variable it is by setting this option to the variable's name. If not set, the hook will try to get the user's name from the USER
environment variable and let it undefined if it can't figure it out.
If the user name is not directly available in an environment variable you may set this option to a code snippet by prefixing it with eval:
. The code will be evaluated and its value will be used as the user name. For example, RhodeCode's (http://rhodecode.org/) up to version 1.3.6 used to pass the authenticated user name in the RHODECODE_USER
environment variable. From version 1.4.0 on it stopped using this variable and started to use another variable with more information in it. Like this:
RHODECODE_EXTRAS='{"username": "rcadmin", "scm": "git", "repository": "git_intro/hooktest", "make_lock": null, "ip": "172.16.2.251", "locked_by": [null, null], "action": "push"}'
To grok the user name from this variable, one may set this option like this:
git config check-acls.userenv \
'eval:(exists $ENV{RHODECODE_EXTRAS} && $ENV{RHODECODE_EXTRAS} =~ /"username":\s*"([^"]+)"/) ? $1 : undef'
This variable is useful for any hook that need to authenticate the user performing the git action.
githooks.admin USERSPEC
There are several hooks that perform access control checks before allowing a git action, such as the ones installed by the CheckAcls
and the CheckJira
plugins. It's useful to allow some people (the "administrators") to bypass those checks. These hooks usually allow the users specified by this variable to do whatever they want to the repository. You may want to set it to a group of "super users" in your team so that they can "fix" things more easily.
The value of each option is interpreted in one of these ways:
- username
-
A
username
specifying a single user. The username specification must match "/^\w+$/i" and will be compared to the authenticated user's name case sensitively. - @groupname
-
A
groupname
specifying a single group. - ^regex
-
A
regex
which will be matched against the authenticated user's name case-insensitively. The caret is part of the regex, meaning that it's anchored at the start of the username.
MAIN FUNCTION
run_hook(NAME, ARGS...)
This is the main routine responsible to invoke the right hooks depending on the context in which it was called.
Its first argument must be the name of the hook that was called. Usually you just pass $0
to it, since it knows to extract the basename of the parameter.
The remaining arguments depend on the hook for which it's being called. Usually you just pass @ARGV
to it. And that's it. Mostly.
run_hook($0, @ARGV);
HOOK DIRECTIVES
Hook directives are routines you use to register routines as hooks. Each one of the hook directives gets a routine-ref or a single block (anonymous routine) as argument. The routine/block will be called by run_hook
with proper arguments, as indicated below. These arguments are the ones gotten from @ARGV, with the exception of the ones identified by GIT. These are Git::More
objects which can be used to grok detailed information about the repository and the current transaction. (Please, refer to the Git::More documentation to know how to use them.)
Note that the hook directives resemble function definitions but they aren't. They are function calls, and as such must end with a semi-colon.
Most of the hooks are used to check some condition. If the condition holds, they must simply end without returning anything. Otherwise, they must die
with a suitable error message. On some hooks, this will prevent Git from finishing its operation.
Also note that each hook directive can be called more than once if you need to implement more than one specific hook.
- APPLYPATCH_MSG(GIT, commit-msg-file)
- PRE_APPLYPATCH(GIT)
- POST_APPLYPATCH(GIT)
- PRE_COMMIT(GIT)
- PREPARE_COMMIT_MSG(GIT, commit-msg-file [, msg-src [, SHA1]])
- COMMIT_MSG(GIT, commit-msg-file)
- POST_COMMIT(GIT)
- PRE_REBASE(GIT)
- POST_CHECKOUT(GIT, prev-head-ref, new-head-ref, is-branch-checkout)
- POST_MERGE(GIT, is-squash-merge)
- PRE_RECEIVE(GIT)
- UPDATE(GIT, updated-ref-name, old-object-name, new-object-name)
- POST_RECEIVE(GIT)
- POST_UPDATE(GIT, updated-ref-name, ...)
- PRE_AUTO_GC(GIT)
- POST_REWRITE(GIT, command)
METHODS FOR PLUGIN DEVELOPERS
plugins should start by importing the utility routines from Git::Hooks:
use Git::Hooks qw/:utils/;
Usually at the end, the plugin should use one or more of the hook directives defined above to install its hook routines in the appropriate hooks.
Every hook routine receives a Git::More object as its first argument. You should use it to infer all needed information from the Git repository.
Please, take a look at the code for the standard plugins under the Git::Hooks:: namespace in order to get a better understanding about this. Hopefully it's not that hard.
The utility routines implemented by Git::Hooks are the following:
is_ref_enabled(REF, SPEC, ...)
This routine returns a boolean indicating if REF matches one of the ref-specs in SPECS. REF is the complete name of a Git ref and SPECS is a list of strings, each one specifying a rule for matching ref names.
As a special case, it returns true if there is no SPEC whatsoever, meaning that by default all refs are enabled.
You may want to use it, for example, in an update
, pre-receive
, or post-receive
hook which may be enabled depending on the particular refs being affected.
Each SPEC rule may indicate the matching refs as the 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.
im_memberof(GIT, USER, GROUPNAME)
This routine tells if USER belongs to GROUPNAME. The groupname is looked for in the specification given by the githooks.groups
configuration variable.
match_user(GIT, SPEC)
This routine checks if the authenticated user (as returned by the Git::More::authenticated_user
method) matches the specification, which may be given in one of the three different forms acceptable for the githooks.admin
configuration variable above, i.e., as a username, as a @group, or as a ^regex.
im_admin(GIT)
This routine checks if the authenticated user (again, as returned by the Git::More::authenticated_user
method) matches the specifications given by the githooks.admin
configuration variable.
eval_gitconfig(VALUE)
This routine makes it easier to grok config values as Perl code. If VALUE
is a string beginning with eval:
, the remaining of it is evaluated as a Perl expression and the resulting value is returned. If VALUE
is a string beginning with file:
, the remaining of it is treated as a file name which contents are evaluated as Perl code and the resulting value is returned. Otherwise, VALUE
itself is returned.
SEE ALSO
Git::More
.
AUTHOR
Gustavo L. de M. Chaves <gnustavo@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2012 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.