[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

Specification of hook script interface

From: Julian Foad <julianfoad_at_btopenworld.com>
Date: 2006-03-30 01:51:53 CEST

The specification of how Subversion handles a hook's output streams and error
status is in several places wrong or insufficient. The book says:

> start-commit
[...]
> If the program returns a non-zero exit value, the commit is stopped
> before the transaction is even created. If the hook program writes
> data to stderr, it will be marshalled back to the client.

That is misleading (as stderr will only be marshalled if the return code was
non-zero) and there are other errors and omissions in the descriptions of the
other hooks. A patch to fix these would be welcome. The writer of such a
patch should check what the current behaviour is in each case, and decide
whether the current behaviour is correct and should be documented or is wrong
in which case a correction could be discussed. Also check whether the
specification in the book agrees with that in the hook script templates that
are created by "svnadmin" when a new repository is created.

In the case of hooks that determine whether an operation may proceed
(start-commit, pre-commit, pre-revprop-change, pre-lock, pre-unlock), I will
state that the correct (desired) interface, as far as the hook script is
concerned, is this:

   * (The working directory, environment variables and command-line arguments
should be specified but I'm not dealing with that here.)

   * The state of stdin is undefined; the hook script must not try to read from
it. (I'm not sure that's true for all hooks: don't some of them supply
arguments via stdin?)

   * Anything sent to stdout is discarded.

   * If it returns exit code 0, the operation proceeds and anything sent to
stderr is discarded.

   * If it returns a non-zero exit value, the operation is aborted and anything
sent to stderr is marshalled back to the client.

The interfaces for post-* hooks are similar but a bit different, with the
primary difference that stderr and the exit code are ignored.

(Software engineering technical note: The specification for implementing the
Subversion core code that calls the hooks could be at a slightly higher level
of promise, e.g. instead of merely satisfying the above promises that include
"stdin is undefined", we would do well to choose a particular well-defined
behaviour such as stdin being connected to /dev/null. This creates a tolerance
gap between what is required by one side of the interface and what is provided
by the other side, which is a recognised principle for increasing robustness
when two sides are developed independently. To do the equivalent for stdout
would require that we ask hook scripts not to write to it; unfortunately it is
too late to demand that though we could recommend it.)

- Julian

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Thu Mar 30 01:52:16 2006

This is an archived mail posted to the Subversion Dev mailing list.