Subversion Repository Hooks
These are the repository hooks that Subversion provides:
- start-commit
- pre-commit
- post-commit
- pre-revprop-change
- post-revprop-change
- pre-lock
- post-lock
- pre-unlock
- post-unlock
start-commit
start-commit — Notification of the beginning of a commit.
Description
The start-commit hook is run before the commit transaction is even created. It is typically used to decide whether the user has commit privileges at all.
If the start-commit hook program returns a nonzero exit value, the commit is stopped before the commit transaction is even created, and anything printed to stderr is marshalled back to the client.
Input Parameter(s)
The command-line arguments passed to the hook program, in order, are:
- Repository path
- Authenticated username attempting the commit
- Colon-separated list of capabilities that a client passes to the server, including depth, mergeinfo, and log-revprops (new in Subversion 1.5).
Common uses
Access control (e.g., temporarily lock out commits for some reason).
A means to allow access only from clients that have certain capabilities.
pre-commit
pre-commit — Notification just prior to commit completion.
Description
The pre-commit hook is run just before a commit transaction is promoted to a new revision. Typically, this hook is used to protect against commits that are disallowed due to content or location (e.g., your site might require that all commits to a certain branch include a ticket number from the bug tracker, or that the incoming log message is nonempty).
If the pre-commit hook program returns a nonzero exit value, the commit is aborted, the commit transaction is removed, and anything printed to stderr is marshalled back to the client.
Input parameter(s)
The command-line arguments passed to the hook program, in order, are:
- Repository path
- Commit transaction name
Additionally, Subversion passes any lock tokens provided by the committing client to the hook script via standard input. When present, these are formatted as a single line containing the string LOCK-TOKENS:, followed by additional lines—one per lock token—which contain the lock token information. Each lock token information line consists of the URI-escaped repository filesystem path associated with the lock, followed by the pipe (|) separator character, and finally the lock token string.
Common uses
Change validation and control
post-commit
post-commit — Notification of a successful commit.
Description
The post-commit hook is run after the transaction is committed and a new revision is created. Most people use this hook to send out descriptive emails about the commit or to notify some other tool (such as an issue tracker) that a commit has happened. Some configurations also use this hook to trigger backup processes.
If the post-commit hook returns a nonzero exit status, the commit will not be aborted since it has already completed. However, anything that the hook printed to stderr will be marshalled back to the client, making it easier to diagnose hook failures.
Input parameter(s)
The command-line arguments passed to the hook program, in order, are:
- Repository path
- Revision number created by the commit
Common uses
Commit notification; tool integration
pre-revprop-change
pre-revprop-change — Notification of a revision property change attempt.
Description
The pre-revprop-change hook is run immediately prior to the modification of a revision property when performed outside the scope of a normal commit. Unlike the other hooks, the default state of this one is to deny the proposed action. The hook must actually exist and return a zero exit value before a revision property modification can happen.
If the pre-revprop-change hook doesn’t exist, isn’t executable, or returns a nonzero exit value, no change to the property will be made, and anything printed to stderr is marshalled back to the client.
Input parameter(s)
The command-line arguments passed to the hook program, in order, are:
- Repository path
- Revision whose property is about to be modified
- Authenticated username attempting the property change
- Name of the property changed
- Change description: A (added), D (deleted), or M (modified)
Additionally, Subversion passes the intended new value of the property to the hook program via standard input.
Common uses
Access control; change validation and control
post-revprop-change
post-revprop-change — Notification of a successful revision property change.
Description
The post-revprop-change hook is run immediately after the modification of a revision property when performed outside the scope of a normal commit. As you can derive from the description of its counterpart, the pre-revprop-change hook, this hook will not run at all unless the pre-revprop-change hook is implemented. It is typically used to send email notification of the property change.
If the post-revprop-change hook returns a nonzero exit status, the change will not be aborted since it has already completed. However, anything that the hook printed to stderr will be marshalled back to the client, making it easier to diagnose hook failures.
Input parameter(s)
The command-line arguments passed to the hook program, in order, are:
- Repository path
- Revision whose property was modified
- Authenticated username of the person making the change
- Name of the property changed
Change description: A (added), D (deleted), or M (modified)
Additionally, Subversion passes to the hook program, via standard input, the previous value of the property.
Common uses
Property change notification
pre-lock
pre-lock — Notification of a path lock attempt.
Description
The pre-lock hook runs whenever someone attempts to lock a path. It can be used to prevent locks altogether or to create a more complex policy specifying exactly which users are allowed to lock particular paths. If the hook notices a preexisting lock, it can also decide whether a user is allowed to “steal” the existing lock.
If the pre-lock hook program returns a nonzero exit value, the lock action is aborted and anything printed to stderr is marshalled back to the client.
The hook program may optionally dictate the lock token which will be assigned to the lock by printing the desired lock token to standard output. Because of this, implementations of this hook should carefully avoid unexpected output sent to standard output.
Warning
If the pre-lock script takes advantage of lock token dictation feature, the responsibility of generating a unique lock token falls to the script itself. Failure to generate unique lock tokens may result in undefined—and very likely, undesired—behavior.
Input parameter(s)
The command-line arguments passed to the hook program, in order, are:
- Repository path
- Versioned path that is to be locked
- Authenticated username of the person attempting the lock
- Comment provided when the lock was created
- 1 if the user is attempting to steal an existing lock; 0 otherwise
Common uses
Access control
post-lock
post-lock — Notification of a successful path lock.
Description
The post-lock hook runs after one or more paths have been locked. It is typically used to send email notification of the lock event.
If the post-lock hook returns a nonzero exit status, the lock will not be aborted since it has already completed. However, anything that the hook printed to stderr will be marshalled back to the client, making it easier to diagnose hook failures.
Input parameter(s)
The command-line arguments passed to the hook program, in order, are:
- Repository path
- Authenticated username of the person who locked the paths
Additionally, the list of paths locked is passed to the hook program via standard input, one path per line.
Common uses
Lock notification
pre-unlock
pre-unlock — Notification of a path unlock attempt.
Description
The pre-unlock hook runs whenever someone attempts to remove a lock on a file. It can be used to create policies that specify which users are allowed to unlock particular paths. It’s particularly important for determining policies about lock breakage. If user A locks a file, is user B allowed to break the lock? What if the lock is more than a week old? These sorts of things can be decided and enforced by the hook.
If the pre-unlock hook program returns a nonzero exit value, the unlock action is aborted and anything printed to stderr is marshalled back to the client.
Input parameter(s)
The command-line arguments passed to the hook program, in order, are:
- Repository path
- Versioned path which is to be unlocked
- Authenticated username of the person attempting the unlock
- Lock token associated with the lock which is to be removed
- 1 if the user is attempting to break the lock; 0 otherwise
Common uses
Access control
post-unlock
post-unlock — Notification of a successful path unlock.
Description
The post-unlock hook runs after one or more paths have been unlocked. It is typically used to send email notification of the unlock event.
If the post-unlock hook returns a nonzero exit status, the unlock will not be aborted since it has already completed. However, anything that the hook printed to stderr will be marshalled back to the client, making it easier to diagnose hook failures.
Input parameter(s)
The command-line arguments passed to the hook program, in order, are:
- Repository path
- Authenticated username of the person who unlocked the paths
Additionally, the list of paths unlocked is passed to the hook program via standard input, one path per line.
Common uses
Unlock notification
Hook:No Access to Delete
Code
1 | @echo on |
Configuration
