Contributor guide

Development

0.4.0

Build

A C99 compiler, Make, and Git are enough for the regular build and test suite.

git clone https://github.com/ciembor/git-hooks-ext.git
cd git-hooks-ext
make
make test

The binary is written to ./git-hooks-ext. Install it under /usr/local/bin with:

sudo make install

Pre-commit checks

Activate the repository-provided hook once in a clone:

make install-dev-hooks

Before every commit it runs clang-tidy with automatic fixes, then requires 100% coverage, then runs the full test suite. If clang-tidy changes a tracked file, the hook stops so the changes can be reviewed and staged before retrying the commit.

Source layout

Files	Responsibility
`git-hooks-ext.c`	Argument validation and CLI dispatch
`hook_install.c`	Classic hook bridge installation
`hook_config.c`	Config-based bridge and event registration
`shell_command.c`	Shell quoting and command construction
`process.c`	Process execution and output reading
`git_runner.c`	Hook paths and event dispatch
`ref_update.c`, `ref_events.c`	Ref parsing and semantic event detection
`worktree.c`	Worktree command forwarding and lifecycle events

Production sources live in src/; integration and C unit tests live in tests/.

Tests

make test

tests/run.sh launches each test in a separate shell and prints TAP-style results. The same runner is used by the regular, coverage, and mutation suites.

The command compatibility matrix checks every event against real Git commands across selected releases, alongside the raw reference-transaction probe.

Debugging

Inspect a transaction without executing configured event hooks:

printf '%s\n' \
  '0000000000000000000000000000000000000000 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa refs/heads/topic' |
  ./git-hooks-ext reference-transaction committed --dry-run

branch-created topic refs/heads/topic 0000000000000000000000000000000000000000 aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

Static analysis

make lint runs clang-tidy on production and C test sources. Enabled warnings fail the command.

# macOS
brew install llvm
make lint

# Custom installation
make lint CLANG_TIDY=/path/to/clang-tidy

make lint-fix uses the same checks with automatic fixes and is the first pre-commit step.

Coverage

The coverage target requires 100% line, function, and region coverage.

make coverage
make coverage-html
open coverage/html/index.html

The text report is written to coverage/report.txt.

Mutation testing

Mull changes comparisons, boundaries, and negations in production code, then runs the full suite. The default required score is 100%.

brew install llvm@19 mull-project/mull/mull@19
make mutation

Reports are written to mutation/. To collect an initial report without enforcing the threshold, run:

make mutation MUTATION_SCORE_THRESHOLD=0

See the mutation review notes for the measured result.

Packaging

Build native packages and test them in isolated environments with these targets:

make package-source
make package-brew
make package-deb

make test-package-brew
make test-package-apt
make test-package-fedora
make test-package-arch
make test-package-alpine

Linux package tests use Podman. Outputs are written below dist/. See the complete packaging notes for platform requirements, release checks, and configuration variables.