6.4 Driving Process Automation with arch Hooks

In some circumstances, it is very useful to trigger actions upon the detection of changes to an archive. For example, you might want to send an email notification whenever new revisions are checked in.

This process occurs through arch by use of hooks. Each time that arch performs a command that modifies an archive, arch will attempt to run ~/.arch-params/hook, which must be set as executable.

Aguments given to the hook $1 : action performed (e.g. commit)

Environment Variables

6.4.1 Arguments Given to hook

Whenever arch performs a command that affects an archive, arch will run hook with the first argument set as the action performed. If I user runs a command (such as make-archive) then hook will be called multiple times with multiple arguments (such as make-archive, make-category, make branch and make-version)

The arguments that may be seen are:

import, commit, tag, make-archive, make-category, make-branch and make-version.

6.4.2 Environment Variables Passed to hook

Tla also passes certain variables to the hook when appropriate. Variables passed by Tla are prefaced with ARCH_. Variables that may be passed include:

Name : ARCH_ARCHIVE Description : The archive involved in the action Seen : all actions Example : lord@emf.net–2003-example

Name : ARCH_CATEGORY Description : Name of category created Seen : make-category Example : hello-world

Name : ARCH_BRANCH Description : Name of branch being created Seen : make-branch Example : mainline

Name : ARCH_VERSION Description : Name of version being created Seen : make-version Example : 0.1

Name : ARCH_REVISION Descriptoin : Name of revision involved Seen : import, tag, commit Example : patch-6

Name : ARCH_LOCATION Description : Location of archive being created Seen : make-archive Example : /usr/lord/archives/2003-example

Name : ARCH_TREE_ROOT Description : Seen : commit, import Example : /home/lord/wd

Name : ARCH_TAGGED_ARCHIVE Description : Seen : tag Example :

Name : ARCH_TAGGED_REVISION Description : Seen : Example :

6.4.3 An Example of Using hook

          #!/bin/sh

          if [ "$1" == "commit" ]; then
             tla push-mirror lord@emf.net--2003-example \
                lord@emf.net--2003-example-MIRROR;
             fi

6.4.4 A more complex Examples of Using hook

          #!/bin/sh

          case "$1" in
             commit)
                case "$ARCH_CATEGORY" in
                   hello-world)
                      case "$ARCH_BRANCH" in
                        mainline)
                             RELEASETYPE="stable"
                        ;;
                        devel)
                           RELEASETYPE="unstable"
                        ;;
                        *)

                      echo "The $RELEASETYPE version of Hello, World been upgraded. \
                         New versions are available at ftp.hello.com" |\
                         mailto hello-users@hello.com -s "Hello upgraded"
                   ;;
                   goodbye-world)
                      case "$ARCH_BRANCH" in
                        mainline)
                             RELEASETYPE="stable"
                        ;;
                        devel)
                           RELEASETYPE="unstable"
                        ;;
                           RELEASETYPE="[unknown]"
                        *)
                      esac;
                      echo "The stable version of Goodbye, Cruel World been upgraded. \
                         New versions are available at ftp.hello.com" |\
                         mailto hello-users@hello.com -s "Hello upgraded"
                   ;;
                 esac
             ;;
          esac

6.4.5 Robustness Issues with hook

Unfortunately, some fundamental physical properties of the universe make it impossible for arch to guarantee that hook will be invoked only once for each new category, branch, version, or revision. A (presumably rare) well timed interrupt or system failure can cause notify to invoke actions more than once for a given change to the archive.

Consequently, actions should be designed to be robust against that eventuality.

Additionally, if arch has been run concurrantly, then the hook may run concurrantly as well. This means that projects using hook should take care that hook is capable of running with simultaneous copies.