How to Write Clear Git Commit Messages and Enforce Them with Webhooks

Background

In many teams, developers are forced to write a commit message for every push, but messages often become inconsistent, mixed‑language, or vague (e.g., "fix bug"), making later maintenance difficult. To improve code quality and developer efficiency, the team decided to monitor and enforce a standardized Git commit message format.

Commit Message Specification

The adopted format follows the widely used Angular convention: <type>(<scope>): <subject> type (required) indicates the category of the change. Allowed types are:

feat – new feature

fix / to – bug fix (fix creates a diff and automatically resolves; to creates a diff without auto‑fix, suitable for multi‑step fixes)

docs – documentation

style – formatting changes that do not affect code execution

refactor – code restructuring without new features or bug fixes

perf – performance or experience improvements

test – adding tests

chore – build or auxiliary tool changes

revert – revert to previous version

merge – code merge

sync – synchronize mainline or branch bugs

scope (optional) describes the part of the codebase affected (e.g., data layer, controller, view). Multiple scopes can be represented with "*".

subject (required) is a concise description of the commit purpose, limited to 50 characters, preferably in Chinese, and without a trailing period.

Example messages:

fix(DAO):用户查询缺少username属性

feat(Controller):用户查询接口开发

Benefits of the Standard

Facilitates traceability of changes and understanding of project history.

Encourages granular, purposeful commits rather than lumping unrelated changes.

Enables automated generation of changelogs.

Monitoring Service

To ensure compliance, a webhook is triggered on each push. The webhook extracts the commit message, validates it against the specification, and sends warning messages for violations. It also checks for large code changes, file deletions, or renames, recording all events in a database for statistical analysis.

The service flow includes:

Service registration – adds repository information.

Duplicate verification – prevents re‑validation of the same merge request.

Message alert – notifies developers (e.g., via DingTalk) of non‑compliant messages or risky operations.

Database storage – persists commit metadata and compliance rates.

Images illustrate the overall architecture and alert flow:

Future Considerations

Git hooks can be implemented on the client side (pre‑commit, commit‑msg, etc.) or server side (pre‑receive, post‑receive). Client‑side hooks can reject non‑conforming commits before they reach the server, while server‑side post‑receive hooks (as currently used) only send warnings. With higher repository permissions, a pre‑receive hook could block violations outright. Additionally, commit metadata can be linked to bugs or requirements, enabling richer traceability.

Conclusion

Standardizing commit messages and monitoring them through automated hooks dramatically improves code quality, reduces maintenance overhead, and supports reliable changelog generation. Investing minimal effort in defining and enforcing these conventions yields significant long‑term productivity gains for developers.