Implementing Hooks

Implement hooks using one of the nine hook directives below. Each one of them get a single block (anonymous function) as argument. The 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 "SVN::Look". These are SVN::Look objects which can be used to grok detailed information about the repository and the current transaction. (Please, refer to the SVN::Look documentation to know how to use it.)

• POST_COMMIT(SVN::Look)
• POST_LOCK(repos-path, username)
• POST_REVPROP_CHANGE(SVN::Look, username, property-name, action)
• POST_UNLOCK(repos-path, username)
• PRE_COMMIT(SVN::Look)
• PRE_LOCK(repos-path, path, username, comment, steal-lock-flag)
• PRE_REVPROP_CHANGE(SVN::Look, username, property-name, action)
• PRE_UNLOCK(repos-path, path, username, lock-token, break-unlock-flag)
• START_COMMIT(repos-path, username, capabilities, txn-name)

This is an example of a script implementing two hooks:

        #!/usr/bin/perl
        use SVN::Hooks;
        # ...
        START_COMMIT {
            my ($repos_path, $username, $capabilities, $txn_name) = @_;
            exists $committers{$username}
                or die "User '$username' is not allowed to commit.\n";
            $capabilities =~ /mergeinfo/
                or die "Your Subversion client does not support mergeinfo capability.\n";
        };
        PRE_COMMIT {
            my ($svnlook) = @_;
            foreach my $added ($svnlook->added()) {
                $added !~ /\.(exe|o|jar|zip)$/
                    or die "Please, don't commit binary files such as '$added'.\n";
            }
        };
        run_hook($0, @ARGV);

Note that the hook directives resemble function definitions but they're not. They are function calls, and as such must end with a semi-colon.

Most of the "start-commit" and "pre-*" 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.

Also note that each hook directive can be called more than once if you need to implement more than one specific hook. The hooks will run in the order they were defined.

Using Plugins

There are several hooks already implemented as plugin modules under the namespace "SVN::Hooks::", which you can use. The main ones are described succinctly below. Please, see their own documentation for more details.

SVN::Hooks::AllowPropChange

Allow only specified users make changes in revision properties.

SVN::Hooks::CheckCapability

Check if the Subversion client implements the required capabilities.

SVN::Hooks::CheckJira

Integrate Subversion with the JIRA <http://www.atlassian.com/software/jira/> ticketing system.

SVN::Hooks::CheckLog

Check if the log message in a commit conforms to a Regexp.

SVN::Hooks::CheckMimeTypes

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::Hooks::CheckProperty

Check for specific properties for specific kinds of files.

SVN::Hooks::CheckStructure

Check if the files and directories being added to the repository conform to a specific structure.

SVN::Hooks::DenyChanges

Deny the addition, modification, or deletion of specific files and directories in the repository. Usually used to deny modifications in the "tags" directory.

SVN::Hooks::DenyFilenames

Deny the addition of files which file names doesn't comply with a Regexp. Usually used to disallow some characteres in the filenames.

SVN::Hooks::Notify

Sends notification emails after successful commits.

SVN::Hooks::UpdateConfFile

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.

This is an example of a script using some plugins:

        #!/usr/bin/perl
        use SVN::Hooks;
        use SVN::Hooks::CheckProperty;
        use SVN::Hooks::DenyChanges;
        use SVN::Hooks::DenyFilenames;
        # 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');
        run_hook($0, @ARGV);

Those directives are implemented and exported by the hooks. Note that using hooks you don't need to be explicit about which one of the nine hooks will be triggered by the directives. This is on purpose, because some plugins can trigger more than one hook. The plugin documentation should tell you which hooks can be triggered so that you know which symbolic links you need to create in the hooks repository directory.

Configuration file

Before calling the hooks, the function "run_hook" evaluates a file called svn-hooks.conf under the conf directory in the repository, if it exists. Hence, you can choose to put all the directives in this file and not in the script under the hooks directory.

The advantage of this is that you can then manage the configuration file with the "SVN::Hooks::UpdateConfFile" and have it versioned under the same repository that it controls.

One way to do this is to use this hook script:

        #!/usr/bin/perl
        use SVN::Hooks;
        use SVN::Hooks::UpdateConfFile;
        use ...
        UPDATE_CONF_FILE(
            'conf/svn-hooks.conf' => 'svn-hooks.conf',
            validator             => [qw(/usr/bin/perl -c)],
            rotate                => 2,
        );
        run_hook($0, @ARGV);

Use this hook script and create a directory called conf at the root of the repository (besides the common trunk, branches, and tags directories). Add the svn-hooks.conf file under the conf directory. Then, whenever you commit a new version of the file, the pre-commit hook will validate it sintactically ("/usr/bin/perl -c") and copy its new version to the conf/svn-hooks.conf file in the repository. (Read the SVN::Hooks::UpdateConfFile documentation to understand it in details.)

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.

Please, see the plugins documentation to know about the directives.

run_hook

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

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 capabilities txn-name
• 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($0, @ARGV);