Hooks

Hooks are short scripts that Fossil runs at defined points of processing. Administrators can use hooks to help enforce policy or connect Fossil to a continuous integration (CI) system.

Interim Documentation.

• This is a work-in-progress. The interface is in flux. For the time being, the documentation as a list of bullet points. We hope to transform this into a proper document later, after things settle down.

• Contributions and suggestions to the hook system and/or the documentation are welcomed.

General Notes.

• Each hooks has a "type", as "sequence", and a "command". The command is a shell command that runs at the appropriate time. The type is currently one of "after-receive", "before-commit", or "disabled". The sequence is an arbitrary integer.

• There can be multiple hooks of the same type. When that is the case, the hooks are run in order of ascending sequence.

• Use the "fossil hook" command to create, edit, and delete hooks.

• Use the "fossil hook test" command to test new hooks.

Hook Scripts

• All scripts are expected to run relatively quickly. If a long-running process is started by a hook, it should be run in the background so that the original script can return.

• The "%F" sequence inside the script is translated into the name of the fossil executable.

• The "%R" sequence in the script is translated in to the name of the repository.

• The "%A" sequence becomes the name of an auxiliary input files, the meaning of which depends on the hook type. The auxiliary filename might be an empty string. Take care to use appropriate quoting!

After-Receive Hooks

• The "after-receive" hook is run by the backoffice whenever new artifacts are received into the repository. The artifacts have already been committed and so there is nothing that the after-receive hook can do to block them.

• The exit code from the after-receive script is ignored.

• The standard intput to the after-receive script is a list of new artifacts, one per line. The first token on each line is the hash of the new artifact. After the hash is a human-readable text description of what the artifact represents.

• Sometimes the same artifact can represent two or more things. For example, the same artifact might represent two or more files in the check-out (assuming the files hold identical content). In that case, the text description that is input to the after-receive hook only shows one of the possible uses for the artifact.

• If two or more pushes occur against a repository at about the same time, then the set of artifacts added by both pushes might be combined into a single after-receive callback.

• Fossil holds a write transaction on the repository while the after-receive hook is running. If the script needs to access the database, then the database will need to be in WAL mode so that readers can co-exist with the writer. Or the script might just launch a background process that waits until the hook script finishes and the transaction commits before it tries to access the repository database.

Before-Commit Hooks

• Before-commit hooks run during the "fossil commit" command before the user is prompted for the check-in comment. Fossil holds a write-transaction on the repository when the before-commit hook is running, so the repository needs to be in WAL mode if the script needs to access the repository.

• The %A substitution is the name of a "commit description file" that shows the details of the commit in progress. To see what a "commit description file" looks like, set a before-commit hook with a command of "cat %Q" and then run a sample commit with the --dry-run option.

• If any before-commit hook returns a non-zero exit code, then the commit is abandoned. All before-commit hooks must exit(0) in order for the commit to proceed.

• The --no-validate flag to the "fossil commit" command prevents any before-commit hooks from running.

• The --trace flag to the "fossil commit" command shows each before-commit hook as it is run.

• If a before-commit hook fails, it should print an error message on standard output or standard error. Otherwise, the user won't know what went wrong, because Fossil won't tell them.

• Nothing is written to standard input of the before-commit hook. The information transmitted to the before-commit hook is contained in the "%A" auxiliary file. The before-commit hook must open and read that file if it wants access to the commit information.