This page provides an overview of the custom-commit-hooks repository, explaining its purpose, architecture, and core components. For installation and usage instructions, see Getting Started. For detailed documentation of individual hooks, see Git Hooks.
The custom-commit-hooks repository provides Git hooks for the pre-commit framework that automatically enhance commit messages to follow Conventional Commits format. The system consists of two specialized hooks that operate at different stages of the Git commit lifecycle to add context and maintain consistency in commit history.
Sources: README.md1-94 CLAUDE.md1-13 AGENTS.md1-7
This repository implements a dual-hook system where each hook targets a specific commit scenario:
enhance-scope - Automatically adds filenames as scopes to conventional commit messages for single-file commitsconventional-merge-commit - Transforms Git's default merge commit messages to follow conventional commit formatBoth hooks are implemented as POSIX-compliant shell scripts and integrate with the pre-commit framework for automated execution during Git operations.
Sources: README.md10-16 README.md46-91 CLAUDE.md14-22
The following diagram maps the repository's major components to their actual file paths:
Component Descriptions:
| Component | File Path | Purpose |
|---|---|---|
enhance-scope hook | scripts/enhance-scope | Adds filename as scope to single-file commits |
conventional-merge-commit hook | scripts/conventional-merge-commit | Transforms merge commits to conventional format |
| Shared library | scripts/lib/commit-msg.sh | Common functions for commit message parsing and modification |
| Hook definitions | .pre-commit-hooks.yaml | Registers hooks with pre-commit framework |
| Hook configuration | .pre-commit-config.yaml | Configures pre-commit hooks for this repository |
| Unit tests | tests/test-unit.sh | Tests individual hook logic |
| Integration tests | tests/test-integration.sh | Tests hooks in real Git repository environments |
| Build automation | Makefile | Developer commands for testing and setup |
| Changelog generator | cliff.toml | Configuration for git-cliff changelog generation |
Sources: CLAUDE.md15-22 AGENTS.md36-48 README.md1-94
The two hooks operate at different stages of Git's commit process, as shown in this execution flow diagram:
Hook Stages:
| Stage | Hook | Entry Point | Function |
|---|---|---|---|
prepare-commit-msg | conventional-merge-commit | scripts/conventional-merge-commit | Runs before editor opens; transforms merge messages |
commit-msg | enhance-scope | scripts/enhance-scope | Runs after editor closes; adds scope to single-file commits |
Both hooks use shared functions from scripts/lib/commit-msg.sh for reading and writing commit messages, ensuring consistent behavior.
Sources: README.md46-91 CLAUDE.md14-22 AGENTS.md7
The enhance-scope hook only modifies commits when all of the following conditions are satisfied:
| Condition | Check |
|---|---|
| File count | Exactly one file being committed |
| Message format | Follows conventional commit format (e.g., feat:, fix:, docs:) |
| Existing scope | No scope already present in message |
| Filename in message | Filename not already mentioned in summary |
| Length constraint | Adding scope keeps summary under 50 characters |
Example transformation:
build: add a dependencybuild(pyproject.toml): add a dependencySources: README.md46-73 CLAUDE.md17
The conventional-merge-commit hook transforms Git's default merge commit messages by prepending chore: merge to summaries that begin with Merge.
Example transformation:
Merge branch 'feature/new-api' into mainchore: merge branch 'feature/new-api' into mainSources: README.md75-91 CLAUDE.md18
The repository is built using the following technologies:
Key characteristics:
#!/bin/sh and avoid bash-specific features for maximum portabilitySources: CLAUDE.md24-30 AGENTS.md50-55 README.md19-43
The repository maintains comprehensive test coverage through multiple test layers:
For detailed information about the testing system, see Testing Infrastructure and its subsections.
Sources: CLAUDE.md7-8 AGENTS.md28-34 AGENTS.md14-16
The repository uses multiple configuration files for different aspects of the system:
| Configuration File | Purpose | Documentation |
|---|---|---|
.pre-commit-hooks.yaml | Defines custom hooks for pre-commit framework | Hook Definitions |
.pre-commit-config.yaml | Configures 26+ hooks for this repository's development | Pre-commit Config |
cliff.toml | Configures git-cliff for changelog generation | Release Configuration |
.gitlint | Defines commit message validation rules | Gitlint Configuration |
Makefile | Provides developer commands and automation | Makefile Commands |
For comprehensive documentation of all configuration files, see Configuration Reference.
Sources: CLAUDE.md19-20 AGENTS.md44 README.md28-37
The repository provides several make targets for development tasks:
| Command | Purpose |
|---|---|
make develop | Install pre-commit hooks locally |
make test | Run all test suites |
make check | Run full validation (tests + linters) |
For detailed information about the development workflow and tools, see Development Workflow.
Sources: CLAUDE.md5-11 AGENTS.md9-26
The repository uses GitHub Actions for continuous integration and deployment:
The CI pipeline runs on multiple OS and Git version combinations for compatibility testing. For detailed CI/CD documentation, see CI/CD Pipeline.
Sources: README.md3-4 AGENTS.md9-26
conventional-merge-commit aloneSources: README.md12-17 CLAUDE.md1-3
This repository is licensed under the MIT License. See LICENSE1-22 for full text.
Sources: LICENSE1-22
Refresh this wiki