Using hooks

What actions call them and how to set up basic hooks is described in the tla tutorial. Unfortunately, it is incomplete and inaccurate, so this page is an attempt to document them properly.

The following is a list of the available hooks (since the list in the tutorial is, at the time of writing (2004.04.04) incomplete):

import
precommit (actual commit will be canceled if this hook exits with non-zero status)
commit
tag
make-archive
make-category
make-branch
make-version
find-pristine
make-pristine
make-tmp-pristine

These are all the ones AaronBentley could find by grepping through the source code.

Note: If there is no hook available for a command you'd like to hook, it may be possible to use a wrapper script instead. See aba for an example.

Note: The hook files is executed only if it has the executable bit set (man chmod) otherwise it will be ignored.

Environment Variables

ARCH_ARCHIVE

Example: foo@bar--baz-SOURCE

This is the registered name of the archive in question. While it is usually something like foo@bar--baz, it may sometimes be foo@bar--baz-SOURCE or foo@bar--baz-MIRROR.

ARCH_REVISION

Example: foo--bar--0--patch-23

Contrary to the tutorial, ARCH_REVISION is an unqualified revision name, not a patchlevel. E.g. foo--bar--0--patch-23, not patch-23 alone.

ARCH_TREE_ROOT

Example: /home/jhacker/foo

ARCH_LOG

Contains the name of a file containing the full text for the newly created log file (the file pointed to by ARCH_LOG may be temporary). Present in "commit", "tag", and "import" hooks.

Other Variables

The tutorial documents other variables, but these are not actually provided.

Command Details

precommit

Undocumented

Executed before commit. Commit aborts if the script returns an error

Sees

ARCH_ARCHIVE
ARCH_REVISION
ARCH_TREE_ROOT

commit

Executed after successful commits

Sees

ARCH_ARCHIVE
ARCH_REVISION
ARCH_TREE_ROOT
ARCH_LOG (bazaar > 1.5 only)

The tutorial documents other environment variables, but it is incorrect.

find-pristine

Undocumented

Invoked by tla update (and others?)

Used before searching for a reference tree (either a pristine or a library revision)

Sees

ARCH_ARCHIVE
ARCH_REVISION

make-pristine

Undocumented

Invoked by tla update, changes, and undo (and others?)

Used before searching for a reference tree (either a pristine or a library revision)

Sees

ARCH_ARCHIVE
ARCH_REVISION

make-tmp-pristine

Undocumented

Invoked by tla update and sync-tree (and others?)

Used before searching for a reference tree (either a pristine or a library revision)

Sees

ARCH_ARCHIVE
ARCH_REVISION

Centralized Hook

A way to run centralized hooks, with an example of how to send a mail for new revisions is provided here (using arch-trigger).

Hook-Scripts

Mike Hearn wrote a Python script to link personal arch archives to the CIA commit tracking system.

Sascha Silbe has posted a script to send a mail on every commit to gnu-arch-users.

Robin Green's in-tree hook script (see below) RunAntOnCommit - which is slightly complicated by virtue of supporting partial commits. Of course it can be trivially changed to run "make" or whatever instead.

HansUlrichNiedermann has written NdimMetaHook, a "meta hook script" which allows adding, removing and maintaining hooks in a very powerful and flexible manner.

John Meinel wrote a script for checking line endings and file permissions. tlaFileCheck.py. It uses syntax similar to that of .arch-inventory to keep track of what files should have what permissions, and line endings. It is just a pre-commit script to prevent you from checking in incorrect files.

Keeping hook scripts in the tree

Ordinarily, hook scripts are stored in ~/.arch-params/hook. On collaborative projects, each contributor must have his own copy of the hook script, and keep it up to date with some master copy; there is no standard mechanism for arranging such synchronisation. It would clearly be convenient if the hook scripts for a project could be kept in the project tree itself; JohannesBerg suggested the following hook script as a solution:

#!/bin/sh
hook="$ARCH_TREE_ROOT/{arch}/=hook"
if [ -x "$hook" ] ;  then
  "$hook" $@
fi

Each contributor need store this only once and the actual hook script may then be stored in the file {arch}/=hook in the project tree.

Note this could be a security issue because you're executing a script every time you make a commit, and the content of that script can be modified by someone else on your team.