.. _git-hooks:

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
----------------------

.. list-table::
   :header-rows: 1
   :widths: 25 20 55

   * - 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:

.. code-block:: bash

   bash BASH/CARDAMOM_SETUP_GIT_HOOKS.sh

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

.. code-block:: bash

   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:

.. code-block:: bash

   CARDAMOM_SKIP_AUTOCOMPILE=1 git checkout my-branch

To compile by hand at any time, see :doc:`compilation`.