A hook is a program triggered by some repository event, such as the creation of a new revision or the modification of an unversioned property. Some hooks (the so-called “pre hooks”) run in advance of a repository operation and provide a means by which to both report what is about to happen and to prevent it from happening at all. Other hooks (the “post hooks”) run after the completion of a repository event and are useful for performing tasks that examine—but don’t modify—the repository. Each hook is handed enough information to tell what that event is (or was), the specific repository changes proposed (or completed), and the username of the person who triggered the event.
The hooks subdirectory is, by default, filled with templates for various repository hooks:
$ ls repos/hooks/ post-commit.tmpl post-unlock.tmpl pre-revprop-change.tmpl post-lock.tmpl pre-commit.tmpl pre-unlock.tmpl post-revprop-change.tmpl pre-lock.tmpl start-commit.tmpl $
There is one template for each hook that the Subversion repository supports; by examining the contents of those template scripts, you can see what triggers each script to run and what data is passed to that script. Also present in many of these templates are examples of how one might use that script, in conjunction with other Subversion-supplied programs, to perform common useful tasks. To actually install a working hook, you need only place some executable program or script into the repos/hooks directory, which can be executed as the name (such as start-commit or post-commit) of the hook.
On Unix platforms, this means supplying a script or program (which could be a shell script, a Python program, a compiled C binary, or any number of other things) named exactly like the name of the hook. Of course, the template files are present for more than just informational purposes—the easiest way to install a hook on Unix platforms is simply to copy the appropriate template file to a new file that lacks the .tmpl extension, customize the hook’s contents, and ensure that the script is executable. Windows, however, uses file extensions to determine whether a program is executable, so you would need to supply a program whose basename is the name of the hook and whose extension is one of the special extensions recognized by Windows for executable programs, such as .exe for programs and .bat for batch files.
For security reasons, the Subversion repository executes hook
programs with an empty environment—that is, no environment variables
are set at all, not even $PATH
(or %PATH%
, under Windows). Because of this,
many administrators are baffled when their hook program runs fine by
hand but doesn’t work when run by Subversion. Be sure to explicitly
set any necessary environment variables in your hook program and/or
use absolute paths to
programs.
Subversion executes hooks as the same user who owns the process that is accessing the Subversion repository. In most cases, the repository is being accessed via a Subversion server, so this user is the same user as whom the server runs on the system. The hooks themselves will need to be configured with OS-level permissions that allow that user to execute them. Also, this means that any programs or files (including the Subversion repository) accessed directly or indirectly by the hook will be accessed as the same user. In other words, be alert to potential permission-related problems that could prevent the hook from performing the tasks it is designed to perform.
There are several hooks implemented by the Subversion repository, and you can get details about each of them in Repository Hooks. As a repository administrator, you’ll need to decide which hooks you wish to implement (by way of providing an appropriately named and permissioned hook program) and how. When you make this decision, keep in mind the big picture of how your repository is deployed. For example, if you are using server configuration to determine which users are permitted to commit changes to your repository, you don’t need to do this sort of access control via the hook system.
There is no shortage of Subversion hook programs and scripts that are freely available either from the Subversion community itself or elsewhere. These scripts cover a wide range of utility—basic access control, policy adherence checking, issue tracker integration, email- or syndication-based commit notification, and beyond. Or, if you wish to write your own, see Chapter 8.
While hook scripts can do almost anything, there is one
dimension in which hook script authors should show restraint: do
not modify a commit transaction using hook
scripts. Although it might be tempting to use hook scripts to
automatically correct errors, shortcomings, or policy violations
present in the files being committed, doing so can cause problems.
Subversion keeps client-side caches of certain bits of repository
data, and if you change a commit transaction in this way, those caches
become undetectably stale. This inconsistency can lead to surprising
and unexpected behavior. Instead of modifying the transaction, you
should simply validate the transaction in the
pre-commit
hook and reject the commit if it does
not meet the desired requirements. As a bonus, your users will learn
the value of careful, compliance-minded work habits.