subversion/libsvn_repos/hooks.txt

   1                            Repository Hooks
   2                            ================
   3
   4 GOALS.
   5 ======
   6
   7    A hook is a program triggered by a repository read or write access.
   8    The hook is handed enough information to tell what the action is,
   9    what target(s) it's operating on, and who is doing it.  Depending
  10    on the hook's output or return status, the repository's hook driver
  11    may continue the action, stop it, or suspend it in some way.
  12
  13    Subversion's hook system is being implemented in stages -- the
  14    parts needed for M3 are being written first, though the design
  15    encompasses goals beyond M3.  In the long term, the system must
  16    support:
  17
  18       1. Commit emails.
  19          Able to report on date of commit, author, dirs and files
  20          changed, and information about the changes -- ranging from
  21          change summaries to full diffs.
  22          [Needed for M3.]
  23
  24       2. Pre-commit guards based on content.
  25          Examine what is about to be committed, and prevent or allow
  26          the commit based on that.
  27          [Not strictly needed for M3, but will be provided anyway.]
  28
  29       3. Pre-commit guards based on identity.
  30          Examine who is attempting to change what, and prevent or
  31          allow the commit accordingly.
  32          [Needed for M3.]
  33
  34    4. Read authorization
  35          Examine who is attempting to read what, and prevent or allow
  36          the access accordingly.
  37          [Not needed for M3; designed now, but implemented post-M3.]
  38
  39
  40 HOW IT WORKS.
  41 =============
  42
  43 Subversion's hooks are programs that live in the repository's hooks/
  44 directory:
  45
  46    $ ls some-repo
  47    README   custom/   dav/   db/   hooks/   conf/
  48    $ ls some-repo/hooks/
  49    start-commit          pre-commit             post-commit
  50    start-commit.tmpl     pre-commit.tmpl        post-commit.tmpl
  51    read-sentinels        write-sentinels
  52    read-sentinels.tmpl   write-sentinels.tmpl
  53    $
  54
  55 The actual hooks are `start-commit', `pre-commit' and `post-commit'.
  56 The template (.tmpl) files are example shell scripts to get you
  57 started; look there for details about how each hook works.  When a
  58 repository is created, the templates are created automatically -- to
  59 make your own hook, just copy `foo.tmpl' to `foo' and edit.
  60
  61 (The `read-sentinels' and `write-sentinels' are not yet implemented
  62 They are intended to be more like daemons than hooks.  A sentinel is
  63 started up at the beginning of a user operation.  The Subversion
  64 server communicates with the sentinel using a protocol yet to be
  65 defined.  Depending on the sentinel's responses, Subversion may stop
  66 or otherwise modify the operation.)
  67
  68 Here is when they are run:
  69
  70    start-commit:  Before the committer's txn is even created.
  71    pre-commit:    When the txn is finished, but before it is committed.
  72    post-commit:   After the txn is committed, and we have a new rev.
  73
  74 Note that they must be executable by the user who will invoke them
  75 (commonly the user httpd runs as), and that same user needs to be able
  76 to access the repository.
  77
  78 Typically, `start-commit' is used to check that the user has commit
  79 privileges at all.  Then the `pre-commit' hook is used to protect
  80 against commits that are disallowed due to content or location (for
  81 example, your site might require that all commits to a certain branch
  82 include a ticket number from the bug tracker), and `post-commit' is
  83 used to mail out commit messages.
  84
  85 The pre-commit and post-commit hooks may need to know things about the
  86 change about to be committed (or that has just been committed).  The
  87 solution is a standalone program, `svnlook', which was installed in
  88 the same place as the `svn' binary.  Use `svnlook' to examine a txn or
  89 revision tree.  It produces output that is both human- and
  90 machine-readable, so hook scripts can easily parse it.  Note that
  91 `svnlook' is read-only -- it can only inspect, not change the
  92 repository.
  93
  94 Run "svnlook" with no arguments to see how it works.
  95
  96 More On Read and Write Sentinels (just discussion, not implemented yet!)
  97 ------------------------------------------------------------------------
  98
  99    (Thanks to Thom Wood <thom@collab.net> for proposing this.)
 100
 101    The `read-sentinels' and `write-sentinels' work somewhat differently.
 102    A sentinel is started whenever a revision or txn root object is opened
 103    (see svn_fs.h).  All operations on paths beneath that root are first
 104    "checked" with the sentinel; the sentinel's response determines
 105    whether the operation is permitted.
 106
 107    Our hope is that sentinels can be kept very simple: they will simply
 108    take paths on stdin, and respond with "Okay" or "Not Okay" (or
 109    slightly more formal XML equivalents).  All kinds of read operations
 110    on a path will be treated as equivalent, as will all write operations.
 111    The relevant question will be simply: was the user allowed to read or
 112    write this path?
 113
 114    The point of sentinels is to provide real-time feedback as a commit
 115    is being built (or even before the txn is started), or as a
 116    checkout or update is being produced -- but without the overhead of
 117    starting up a program anew for each path under the root.
 118
 119    Almost all reading and writing functions in svn_fs.h will need to be
 120    wrapped by libsvn_repos, which will drive the sentinels:
 121
 122       Read actions to be wrapped:
 123       ---------------------------
 124          svn_fs_revision_root
 125          svn_fs_is_dir
 126          svn_fs_is_file
 127          svn_fs_node_prop
 128          svn_fs_node_proplist
 129          svn_fs_txn_prop
 130          svn_fs_txn_proplist
 131          svn_fs_copied_from
 132          svn_fs_is_different
 133          svn_fs_dir_entries
 134          svn_fs_file_length
 135          svn_fs_file_contents
 136          svn_fs_youngest_rev
 137          svn_fs_revision_prop
 138          svn_fs_revision_proplist
 139
 140       Write actions to be wrapped:
 141       ----------------------------
 142          svn_fs_begin_txn
 143          svn_fs_commit_txn
 144          svn_fs_txn_root
 145          svn_fs_change_txn_prop
 146          svn_fs_change_node_prop
 147          svn_fs_make_dir
 148          svn_fs_delete
 149          svn_fs_delete_tree
 150          svn_fs_rename
 151          svn_fs_copy
 152          svn_fs_link
 153          svn_fs_make_file
 154          svn_fs_apply_textdelta
 155          svn_fs_change_rev_prop
 156
 157    The exact sentinel protocol is still TBD; obviously, a precise
 158    specification is very important for sentinel implementors.
 159
 160
 161 FAQ (Frequently Anticipated Questions).
 162 =======================================
 163
 164    Q: Why is `svnlook' a read-only interface to the repository?
 165
 166    A: Because if it changed the txn before commit, the working copy
 167       would have no way of knowing what happened, and would therefore
 168       be out of sync and not know it.  Subversion currently has no way
 169       to handle this situation, and maybe never will.  Someday the
 170       hooks may leave txns in a "holding" state (for supervised
 171       commits, a handy feature many have requested), but even then the
 172       working copy should be told definitively that the commit did not
 173       succeed.  Later on, the commit will come through as an update.