SVN::Hooks - A framework for implementing Subversion hooks.
Version 0.14
A single, simple script like the following can be used as any kind of Subversion hook.
#!/usr/bin/perl use SVN::Hooks; use SVN::Hooks::DenyFilenames; use SVN::Hooks::DenyChanges; use SVN::Hooks::CheckProperty; ... run_hook($0, @ARGV);
Of course, you'll have to configure the plugins (the sub-modules of SVN::Hooks), but this is just another (almost as) simple Perl script like this.
# Accept only letters, digits, underlines, periods, and hifens DENY_FILENAMES(qr/[^-\/\.\w]/i); # Disallow modifications in the tags directory DENY_UPDATE(qr:^tags:); # OpenOffice.org documents need locks CHECK_PROPERTY(qr/\.(?:od[bcfgimpst]|ot[ghpst])$/i => 'svn:needs-lock');
In order to really understand what this is all about you'll need to understand Subversion and its hooks.
Subversion is a version control system, and as such it is used to maintain current and historical versions of files and directories. Each revision maintains information about all the changes introduced since the previous one: date, author, log message, files changed, files renamed, etc.
Subversion uses a client/server model. The server maintains the repository, which is the database containing all the historical information we talked about above. The users use a Subversion client tool to query and change the repository but also to maintain one or More working areas. A working area is a directory in the user machine containing a copy of a particular revision of the repository. The user can use the client tool to make all sorts of changes in his working area and to "commit" them all in an atomic operation that bumps the repository to a new revision.
A hook is a specifically named program that is called by the Subversion server during the execution of some operations. There are exactly nine hooks which must reside under the conf directory in the repository. When you create a new repository, you get nine template files in this directory, all of them having the .tmpl suffix and helpful instructions inside explaining how to convert them into working hooks.
conf
.tmpl
When Subversion is performing a commit operation on behalf of a client, for example, it calls first the start-commit hook, then the pre-commit hook, and then the post-commit hoook. The first two can gather all sorts of information about the specific commit transaction being performed and decide to reject it in case it doesn't comply to a set of policies. The post-commit can be used to log or alert interested parties about the commit just done.
start-commit
pre-commit
post-commit
There are several useful hook scripts available, mainly for those three associated with the commit operation. 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.
In order to integrate the funcionality of more than one script you have to write a driver script that's called by Subversion 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.
This arrangement is inefficient in two ways. First because each script runs is a separate process, which usually have a high startup cost because they are, well, scripts and not binaries. 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 svnlook command, which spawns yet another process.
svnlook
SVN::Hooks is a framework for implementing Subversion hooks that tries to solve these problems.
Instead of having separate scripts implementing different functionality you have a single script using a single simple configuration file. Different plugins, implemented by Perl modules in the SVN::Hooks:: namespace, implement the different functionality. Moreover, a single script can be used to implement all the nine standard hooks, because each plugin knows when to perform based on the context in which they were called.
Each plugin is implemented as a Perl module. The main ones are described succinctly below. Please, see their own documentation for more details.
Allow changes in revision log messages.
Check if the log message in a commit conforms to a Regexp.
Check if the files added to the repository have the svn:mime-type property set. Moreover, for text files, check if the properties svn:eol-style and svn:keywords are also set.
svn:mime-type
svn:eol-style
svn:keywords
Check for specific properties for specific kinds of files.
Check if the files and directories being added to the repository conform to a specific structure.
Deny the addition, modification, or deletion of specific files and directories in the repository. Usually used to deny modifications in the tags directory.
tags
Deny the addition of files which file names doesn't comply with a Regexp. Usually used to disallow some characteres in the filenames.
Require that the log message in a commit includes references to issues in the JIRA ticketing system.
Sends notification emails after succesful commits.
Allows you to maintain Subversion configuration files versioned in the same repository where they are used. Usually used to maintain the configuration file for the hooks and the repository access control file.
In the Subversion server, go to the hooks directory under the directory where the repository was created. You should see there the nine hook templates. Create a script there using all the plugins in which you are interested.
hooks
$ cd /path/to/repo/hooks $ cat svn-hooks.pl #!/usr/bin/perl use strict; use warnings; use SVN::Hooks; use SVN::Hooks::AllowLogChange; use SVN::Hooks::CheckLog; use SVN::Hooks::CheckMimeTypes; use SVN::Hooks::CheckProperty; use SVN::Hooks::CheckStructure; use SVN::Hooks::DenyChanges; use SVN::Hooks::DenyFilenames; use SVN::Hooks::JiraAcceptance; use SVN::Hooks::Notify; use SVN::Hooks::UpdateRepoFile; run_hook($0, @ARGV); $ chmod +x svn-hooks.pl
This script will serve for any hook. Create symbolic links pointing to it for each hook you are interested in.
$ ln -s svn-hooks.pl pre-commit $ ln -s svn-hooks.pl post-commit $ ln -s svn-hooks.pl pre-revprop-change
The default configuration file for the hook is called svn-hooks.conf in the conf directory under the directory where the repository was created. It's just another Perl script calling special functions acting as configuration directives that were defined by the plugins.
svn-hooks.conf
$ cd ../conf $ cat svn-hooks.conf DENY_FILENAMES(qr:[^-/\.\w]:i); CHECK_MIMETYPES(); # Binary+editable files must have the svn:needs-lock property set CHECK_PROPERTY(qr/\.(?:do[ct]x?|xl[bst]x?|pp[st]x?|rtf|od[bcfgimpst]|ot[ghpst]|sd[acdpsw]|s[tx][cdiw]|mpp|vsd)$/i => 'svn:needs-lock'); DENY_UPDATE(qr:^tags:); 1;
Being a Perl script, it's possible to get fancy with the configuration file, using variables, functions, and whatever. But for most purposes it consists just in a series of configuration directives.
Don't forget to end it with the 1; statement, though, because it's evaluated with a do statement and needs to end with a true expression.
1;
do
Please, see the plugins documentation to know about the directives.
Yet to do.
SVN::Hooks exports a single function, run_hook, which is responsible to invoke the right plugins 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.
$0
Its second argument must be the path to the directory where the repository was created.
The remaining arguments depend on the hook for which it's being called, like this:
start-commit repo-path user
pre-commit repo-path txn
post-commit repo-path rev
pre-lock repo-path path user
post-lock repo-path user
pre-unlock repo-path path user
post-unlock repo-path user
pre-revprop-change repo-path rev user propname action
post-revprop-change repo-path rev user propname action
But as these are exactly the arguments Subversion passes when it calls the hooks, you usually call run_hook like this:
run_hook
run_hook($0, @ARGV);
Gustavo Chaves, <gnustavo@cpan.org>
<gnustavo@cpan.org>
Please report any bugs or feature requests to bug-svn-hooks at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=SVN-Hooks. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-svn-hooks at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc SVN::Hooks
You can also look for information at:
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=SVN-Hooks
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/SVN-Hooks
CPAN Ratings
http://cpanratings.perl.org/d/SVN-Hooks
Search CPAN
http://search.cpan.org/dist/SVN-Hooks
Copyright 2008 CPqD, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install SVN::Hooks, copy and paste the appropriate command in to your terminal.
cpanm
cpanm SVN::Hooks
CPAN shell
perl -MCPAN -e shell install SVN::Hooks
For more information on module installation, please visit the detailed CPAN module installation guide.