Repository Hooks ================ GOALS. ====== A hook is a program triggered by a repository read or write access. The hook is handed enough information to tell what the action is, what target(s) it's operating on, and who is doing it. Depending on the hook's output or return status, the repository's hook driver may continue the action, stop it, or suspend it in some way. Subversion's hook system is being implemented in stages -- the parts needed for M3 are being written first, though the design encompasses goals beyond M3. In the long term, the system must support: 1. Commit emails. Able to report on date of commit, author, dirs and files changed, and information about the changes -- ranging from change summaries to full diffs. [Needed for M3.] 2. Pre-commit guards based on content. Examine what is about to be committed, and prevent or allow the commit based on that. [Not strictly needed for M3, but will be provided anyway.] 3. Pre-commit guards based on identity. Examine who is attempting to change what, and prevent or allow the commit accordingly. [Needed for M3.] 4. Read authorization Examine who is attempting to read what, and prevent or allow the access accordingly. [Not needed for M3; designed now, but implemented post-M3.] HOW IT WORKS. ============= Subversion's hooks are programs that live in the repository's hooks/ directory: $ ls some-repo README custom/ dav/ db/ hooks/ conf/ $ ls some-repo/hooks/ start-commit pre-commit post-commit start-commit.tmpl pre-commit.tmpl post-commit.tmpl read-sentinels write-sentinels read-sentinels.tmpl write-sentinels.tmpl $ The actual hooks are `start-commit', `pre-commit' and `post-commit'. The template (.tmpl) files are example shell scripts to get you started; look there for details about how each hook works. When a repository is created, the templates are created automatically -- to make your own hook, just copy `foo.tmpl' to `foo' and edit. (The `read-sentinels' and `write-sentinels' are not yet implemented They are intended to be more like daemons than hooks. A sentinel is started up at the beginning of a user operation. The Subversion server communicates with the sentinel using a protocol yet to be defined. Depending on the sentinel's responses, Subversion may stop or otherwise modify the operation.) Here is when they are run: start-commit: Before the committer's txn is even created. pre-commit: When the txn is finished, but before it is committed. post-commit: After the txn is committed, and we have a new rev. Note that they must be executable by the user who will invoke them (commonly the user httpd runs as), and that same user needs to be able to access the repository. Typically, `start-commit' is used to check that the user has commit privileges at all. Then the `pre-commit' hook is used to protect against commits that are disallowed due to content or location (for example, your site might require that all commits to a certain branch include a ticket number from the bug tracker), and `post-commit' is used to mail out commit messages. The pre-commit and post-commit hooks may need to know things about the change about to be committed (or that has just been committed). The solution is a standalone program, `svnlook', which was installed in the same place as the `svn' binary. Use `svnlook' to examine a txn or revision tree. It produces output that is both human- and machine-readable, so hook scripts can easily parse it. Note that `svnlook' is read-only -- it can only inspect, not change the repository. Run "svnlook" with no arguments to see how it works. More On Read and Write Sentinels (just discussion, not implemented yet!) ------------------------------------------------------------------------ (Thanks to Thom Wood for proposing this.) The `read-sentinels' and `write-sentinels' work somewhat differently. A sentinel is started whenever a revision or txn root object is opened (see svn_fs.h). All operations on paths beneath that root are first "checked" with the sentinel; the sentinel's response determines whether the operation is permitted. Our hope is that sentinels can be kept very simple: they will simply take paths on stdin, and respond with "Okay" or "Not Okay" (or slightly more formal XML equivalents). All kinds of read operations on a path will be treated as equivalent, as will all write operations. The relevant question will be simply: was the user allowed to read or write this path? The point of sentinels is to provide real-time feedback as a commit is being built (or even before the txn is started), or as a checkout or update is being produced -- but without the overhead of starting up a program anew for each path under the root. Almost all reading and writing functions in svn_fs.h will need to be wrapped by libsvn_repos, which will drive the sentinels: Read actions to be wrapped: --------------------------- svn_fs_revision_root svn_fs_is_dir svn_fs_is_file svn_fs_node_prop svn_fs_node_proplist svn_fs_txn_prop svn_fs_txn_proplist svn_fs_copied_from svn_fs_is_different svn_fs_dir_entries svn_fs_file_length svn_fs_file_contents svn_fs_youngest_rev svn_fs_revision_prop svn_fs_revision_proplist Write actions to be wrapped: ---------------------------- svn_fs_begin_txn svn_fs_commit_txn svn_fs_txn_root svn_fs_change_txn_prop svn_fs_change_node_prop svn_fs_make_dir svn_fs_delete svn_fs_delete_tree svn_fs_rename svn_fs_copy svn_fs_link svn_fs_make_file svn_fs_apply_textdelta svn_fs_change_rev_prop The exact sentinel protocol is still TBD; obviously, a precise specification is very important for sentinel implementors. FAQ (Frequently Anticipated Questions). ======================================= Q: Why is `svnlook' a read-only interface to the repository? A: Because if it changed the txn before commit, the working copy would have no way of knowing what happened, and would therefore be out of sync and not know it. Subversion currently has no way to handle this situation, and maybe never will. Someday the hooks may leave txns in a "holding" state (for supervised commits, a handy feature many have requested), but even then the working copy should be told definitively that the commit did not succeed. Later on, the commit will come through as an update.