Commit Validation

🚀Commit Validation

Active

Keep commit validation available in every project while enabling Commitizen only when the project intentionally adopts it.

Command[tool.custy.commit.validation]

📦Category

Configuration

🚀Quick Command

provider = auto | custy | commitizen | git

---

provider selectionoptional CommitizenGit hooks

---

⚙️

Default Provider

auto

🛡️

Strict by Default

No

✅

Built-in Validator

Always available

💻

External Tool

cz (optional)

Recommended Configuration

.config/custy/config.toml

toml

[tool.custy.commit.validation]
provider = "auto"
require_tool = false

This default does not require Commitizen. Custy activates cz only when it finds both recognized project configuration and an available executable.

---

Behavior Matrix

Provider	Commitizen config	cz installed	Result
auto	No	No	Use Custy validation.
auto	No	Yes	Use Custy validation; installation alone does not activate Commitizen.
auto	Yes	Yes	Run Custy validation, then Commitizen validation.
auto	Yes	No	Warn and fall back to Custy.
auto with require_tool = true	Yes	No	Stop before mutation with COMMITIZEN_NOT_AVAILABLE.
custy	Any	Any	Use only Custy's built-in conventional-message rules.
commitizen	Yes	Yes	Require both Custy and Commitizen validation.
commitizen	No or invalid	Any	Stop before mutation with a focused configuration error.
git	Any	Any	Require a readable, non-empty UTF-8 message file; allow project-specific message formats.

💡Use auto for mixed repositories

auto is the best shared default when Custy is used across projects with different tooling. Use commitizen when a repository intentionally requires the same Commitizen policy in local development, containers, and CI.

---

Properties

📋Properties

Property	Type	Description	Default	Required
provider	auto | custy | commitizen | git	Select automatic discovery, Custy's internal rules, strict Commitizen integration, or basic Git message-file safety checks.	auto	No
require_tool	Boolean	In auto mode, turn a detected invalid or unavailable Commitizen integration from a warning and fallback into an early error.	false	No

---

What Auto Detects

Custy recognizes these project configuration sources:

• .cz.toml
• .cz.yaml or .cz.yml
• .cz.json
• [tool.commitizen] in pyproject.toml

Custy separately checks whether the cz executable is available. It never installs Commitizen during a command and never enables it only because the executable happens to be installed globally.

---

CLI Override

--check-cz is the backward-compatible strict override. For that invocation, it behaves like:

Terminal

toml

provider = "commitizen"
require_tool = true

Use persistent TOML configuration for team policy. Use --check-cz for an intentional one-time verification.

---

Install Optional Commitizen Support

Terminal

bash

pip install "custy[commitizen]"

Custy's production Docker image includes this optional extra so supported Commitizen workflows are available in the container. A project-specific pre-commit installation remains separate.

---

Versioning and Message Validation Are Independent

[tool.custy.cli.versioning].strategy = "commitizen" asks Commitizen to help resolve versions. [tool.custy.commit.validation].provider = "commitizen" asks it to validate the final commit message. A project may enable either one, both, or neither.

⚠️Git hooks still run

Provider selection does not disable pre-commit, commit-msg, or other Git hooks. If a hook fails, Custy reports GIT_HOOK_FAILED with captured output. A hook installed on Windows may contain a Windows Python path and cannot run unchanged inside Linux Docker; install that hook in the environment where Git will execute it.

Continue

🚀Related Commands

Commands commonly used together with this command.

Commit Configuration

Combine provider policy with templates, staging, and backups.

Commit Troubleshooting

Resolve Commitizen and Git-hook failures.

Docker

Understand container tools and mounted repository hooks.