================================================================================
darcs-hooks2
================================================================================
--------------------------------------------------------------------------------
Scripting Darcs hooks thru Factor
--------------------------------------------------------------------------------

.. default-role:: code

:author: toastal


Purpose
================================================================================

:ac:`Darcs` natively supports hooks via ``_darcs/prefs/defaults`` using
``prehook`` & ``posthook`` directives. ``darcs-hooks`` is a Factor binary that
generates & manages these hook configurations from a Factor-based config file
(``_darcs/prefs/hooks.factor``).

Beyond hook management, the binary also provides some built-in helper words:

``tweak-weak-hash-file``
	replaces the old ``mark-darcs-weak-hash`` shell script by parsing ``darcs
	show repo --xml-output`` for the weak hash

``tweak-tags-atom``
	builds an Atom feed of tags from ``darcs log --xml-output`` for subscriptions

(More coming soon?)

Usage
================================================================================

.. code:: console

	$ darcs-hooks --help
	Usage:
	    darcs-hooks [--help] [command]

	Dispatch darcs hooks for the current repository.

	Arguments:
	    command    {set-up,run,make-so,version}

	Options:
	    --help    show this help and exit

``set-up``
	Writes ``_darcs/prefs/hooks.factor`` using a ``H{ … }`` hash-map. Use
	``--defaults`` to include the built-in default hooks. Use
	``--nix-release-defaults`` for the Nix release workflow hooks.

``make-so``
	Writes native darcs ``prehook`` / ``posthook`` entries to
	``_darcs/prefs/defaults``, replacing any entries for hooks managed by
	darcs-hooks. Only needs to be re-run when hooks are added or removed.

``run``
	Dispatch a hook (for example: ``pre-record``). Loads actions from
	``_darcs/prefs/hooks.factor``. If the hook is not found, exits 0.

``version``
	Print the version number.


Config file: ``_darcs/prefs/hooks.factor``
================================================================================

.. code:: factor

    USING: assocs darcs-hooks2 kernel namespaces ;

    H{
        { "post-apply" [ ] }
        { "post-obliterate" [ ] }
        { "post-record" [ ] }
    } hook-actions set-global

Each ``[ ]`` is a Factor quotation — the hook body. Replace ``[ ]`` with any
Factor code to run when the hook fires. The ``_darcs/`` directory is excluded
from darcs tracking by the ``^_`` boring pattern.


License
================================================================================

This project is licensed under the Mozilla Public License Version 2.0
(MPL-2.0_) — see the ``LICENSE.txt`` file in this project for details.

.. _MPL-2.0: https://www.mozilla.org/en-US/MPL/2.0/


Funding
================================================================================

To help out, see choices at the `maker’s website <https://toast.al/funding/>`_.