Understanding Subversion repository hooks

Applies to: VisualSVN Server 5.0 and later

This article briefly describes Subversion repository hooks and how they can be configured using VisualSVN Server. The Configuring basic repository hooks section gives recommendations on configuring the most essential repository hooks.

What is a repository hook?

Repository hook is a script that runs automatically before or after a certain repository event occurs. Such events include: commit, lock, unlock, revision property change. Hook types are briefly discussed below.

Commit hooks

Commit is a process of publishing changes to a repository. Commit hooks are commonly used to validate these changes and to notify repository users about successful commits.

The start-commit hook runs immediately after a commit transaction is created. At this moment, the initial transaction properties (such as svn:author, svn:date, svn:log) are set but nothing is known yet about the commit content. It can be used to decide whether it is possible to proceed with the commit.

The pre-commit hook runs before a commit transaction is committed. This hook can access and evaluate the commit content. It can be used to ensure that the commit content satisfies your specific requirements.

The post-commit hook runs after a commit transaction is committed. It can be used to notify users about completed commits or to automatically update issue tracker tickets.

Lock hooks

Locking is a mechanism which prevents other users except the lock owner from changing the file. It is commonly used to avoid conflicts that may occur when multiple users check out and simultaneously modify the same binary file.

Note
Unlike textual files, binary files cannot be contextually merged. Therefore, some additional considerations may be required. For specific details, please see the Lock Communication section of SVN Book.

Lock hooks can be used to validate lock creation or lock removal and to notify users about locking events.

The pre-lock hook runs before a lock is created. It can be used to decide whether the lock is allowed to be created.

The post-lock hook runs after one or more paths have been locked. It can be used to notify users that files under the specified paths are now locked and cannot be changed.

The pre-unlock hook runs before a lock is removed. It can be used to decide whether the lock is allowed to be removed.

The post-unlock hook runs after one or more paths have been unlocked. It can be used to notify users that files under the specified paths are now unlocked and can be changed.

Revision property change hooks

Revision properties are unversioned metadata attached to each of repository revisions. These properties contain information about the author who created the revision, the date when the revision was created, its log message, and several other values.

The pre-revision property change hook runs before a revision property is added, modified or deleted. It can be used to allow or prohibit changes to revision properties.

Note
Changes to revision properties are prohibited by default. To allow making such changes to repository users, the pre-revision property change hook must be configured. The changes will only take place if the hook returns a zero exit value when completed.

The post-revision property change hook runs after a revision property has been added, modified or deleted. It can be used to send notifications about revision property changes.

Configuring hooks with VisualSVN Server

VisualSVN Server Manager includes a hook editor that allows administrators to create new and modify existing hook scripts. The hook editor window provides a brief argument reference for each hook type.

Follow the steps below to configure repository hooks with VisualSVN Server:

  1. Start VisualSVN Server Manager.
  2. Expand the Repositories node.
  3. Right-click a repository and select Properties.
  4. Select the Hooks tab.
  5. Select a hook from the list.
  6. Click Edit.
  7. Enter commands into the hook editor.
  8. Click OK and Apply.

Hooks are stored as script files with .cmd extension in the hooks subdirectory of your repository (for example, C:\Repositories\MyRepo\hooks). In response to a repository event, Subversion will run a corresponding hook by invoking a script file with its specific arguments.

Configuring basic repository hooks

This section gives recommendations on configuring the most essential repository hooks with VisualSVN Server. Follow the links below for hands-on instructions.

Post-commit hook for email notifications

Post-commit hook for email notifications is a recommended part of every installation. Just as it sounds like, it sends email notifications to the specified email address whenever a commit occurs. Please see the KB18: Configuring Email Notifications in VisualSVN Server article for setup instructions.

Pre-commit hook for log message validation

By default, there are no restrictions on commit log messages content. Pre-commit hook for log messages validation helps you enforce informative commit messages. Typically, you might want to prohibit empty log messages or log messages that are too short. Please see the KB140: Validating commit log messages in VisualSVN Server article for setup instructions.

Pre-commit hook for file name validation

By default, there are almost no restrictions on file and folder names in Subversion repositories. However, you might want to reject commits that include certain file names. The pre-commit hook validates file names in commits and can perform the following checks:

  • Reject files with certain extensions (e.g., *.iso, *.dll, *.exe, etc.).
  • Reject files and folders whose names differ only by case to prevent case-only name conflicts.
  • Reject files and folders with names incompatible with the Windows file naming conventions.

Please see the article KB198: Validating file names in a pre-commit hook script for more information and setup instructions.

See also

KB79: Understanding hook scripts for VDFS repositories

Last Modified: