Git hooks

What git hooks are

Git hooks are scripts that git runs automatically when a particular event happens in a repository — after a commit, after a pull, after switching branch, and so on. They are ordinary executable scripts named after the event they respond to, and they run locally on your own machine. Nothing in a hook is pushed to or enforced by the remote: hooks are a convenience for keeping your working copy consistent, not a substitute for CI.

By default git looks for hooks in .git/hooks, which is not version controlled. CARDAMOM instead keeps its hooks in a tracked .githooks directory and points git at it with core.hooksPath, so every developer gets the same hooks.

Hooks used by CARDAMOM

Hook	Runs when	What it does
`.githooks/post-checkout`	You switch branch	Regenerates the demo cbf.nc file, then recompiles the C code.
`.githooks/post-merge`	`git pull` / merge	Regenerates the demo cbf.nc file, then recompiles the C code.
`.githooks/cardamom-autocompile`	Called by the two hooks above	Runs `BASH/CARDAMOM_COMPILE.sh`. Not a hook itself — a shared helper.

The demo file is regenerated by PYTHON/check_fun/DEMO_CBF_NC_GENERATOR.py.

Why the compilation hook matters

The compiled executables (*.exe) are gitignored, so they are never part of a checkout. Without a hook, switching branch or pulling new C source leaves the old binaries in place, and you silently keep running code that no longer matches the source you are reading. Keeping the rebuild in a hook means CARDAMOM_MDF.exe and CARDAMOM_RUN_MODEL.exe always correspond to the checked-out source.

Compilation is defined in cardamom-autocompile only, so a given git event triggers at most one rebuild. Scripts that use the executables — such as CARDAMOM_CBF_NC_FILE_STRESS_TEST.py — assume compilation has already happened and never invoke the compiler themselves.

A failed compilation never blocks the git operation; the hook reports the failure and leaves the full compiler output in /tmp/CARDAMOM_COMPILE.log.

Installing the hooks

Once per clone:

bash BASH/CARDAMOM_SETUP_GIT_HOOKS.sh

This makes the hooks executable and sets core.hooksPath to .githooks. To confirm it worked:

git config core.hooksPath     # should print .githooks

Skipping the rebuild

To run a git command without recompiling — useful for a quick branch switch, or when you are deliberately keeping an older binary:

CARDAMOM_SKIP_AUTOCOMPILE=1 git checkout my-branch

To compile by hand at any time, see Compilation.