Introducing CaptainHook - A Subversion Hook Framework For .NET
UPDATE: CaptainHook is now an Open Source project on SourceForge.
One potent tool for team communications on a project, especially one with distributed developers, is the simple commit email. Setting up Subversion to send out an email when a developer commits changes to the repository is fairly easy. The Subversion distribution comes with a PERL script (commit-email.pl) that works quite well for this purpose.
At least it did for me until we changed mail servers to one that did not allow SMTP relay. Try as I might, I could not get the script to authenticate with our SMTP credentials. I downloaded various other PERL modules that were supposed to be able to authenticate with no luck. I read the RFC 2554 (seat of your pants reading) and authenticated manually via telnet and compared that to the SMTP logs for the components and realized that for some reasons, these scripts were doing the wrong thing.
That’s when it occurred to me that I could probably write a simple .NET app in a minute that could send out the commit email. As I got started though, I realized that it might be nice to write something that would allow others to easily handle other Subversion hooks. Hence CaptainHook was born.
Hooks in Subversion are scripts (or executables) that are triggered by an event in the subversion version control life cycle. The following are the five hooks supported by Subversion. For a short discussion on how to install the hooks, read this post by Pete Freitag.
Note that (except for
return value of the script controls whether or not the commit should
continue. If the script returns 0, the commit continues. If it returns
anything other than 0, the commit is stopped.
|Script Name||Triggered By||Arguments||Notes|
||Before the commit transaction starts||Repository Path and username||Can be used for repository access control.|
||After the commit transaction starts but before the transaction is commited||Repository Path and transaction name||Often used to validate a commit such as checking for a non-empty log message.|
||After the commit transaction completes||Repository Path and the revision number of the commit||Can be used to send emails or backup repository.|
||Before a revision property is changed||Repository Path, Revision, Username, name of the property||Revision Property’s new value is passed into standard input. Can be used to check permission.|
||After a revision property is changed||Repository Path, Revision, Username, name of the property||Can be used to email or backup these changes.|
My goal was to provide a nice strongly typed interface and a few useful service methods for accessing Subversion. Thus handling a Subversion hook is as easy as implementing an abstract base class and calling methods on a Subversion wrapper interface.
To setup CaptainHook, simply unzip the exe file and its related
assemblies into the
hooks folder on your Subversion server. The
distribution includes a
plugins directory with a single plugin already
there. The plugins directory is where CaptainHook looks for other hook
handlers. Be sure to update the config file with settings that match
The next step is to rename the .tmpl file for the hook events you wish
CaptainHook to handle. CaptainHook comes with some sample batch files
you can use instead, one for each hook. Just copy the ones you want to
use from the
SampleBatchFiles directory into the
Now when a commit occurs, Subversion will call the
file which in turn calls CaptainHook with the
post-commit flag. This
flag indicates to CaptainHook which plugins to load. CaptainHook then
looks in the
plugins directory for any assemblies with types that
PostCommitHook abstract class. It then instantiates
instances of these types and calls the
Initialize method and then the
Note that for the time being, CaptainHook is an executable so it has to incur the cost of searching the plugin assemblies every time which may seem like overkill (and it is). However my focus was on the model for CaptainHook. At some point it will evolve to use remoting as a Server Activated Singleton or it may become a Windows Service which fit the model better. Either way, there are ways in which we can incur this cost only once. But for now, this will do and performs well enough.
Assemblies and Classes
Captain hook contains serveral assemblies.
|CaptainHook||This is the main console exe and is the starting point for the application.|
|CaptainHook.Interfaces||Contains the interface definitions. This is the only assembly you need to reference when writing a plugin.|
|CaptainHook.SubversionWrapper||This is potentially useful as a stand-alone library. It includes the
Let me know if you find this useful. It is definitely a work in progress
as not every command is implemented in the
If it turns out that several people find this useful and want to
contribute to the code, I am willing to put the code on
The zip archive contains both the source code and the binaries. I also compiled an x64 version of the exe for you 64bit kids.