Discussion: Clarify / standardize behavior for negative message_length_limit (should it require >= 0?)

[ttw225]

Description

I’d like to start a discussion about how message_length_limit should behave when it is set to a negative value.

My current thinking is that message_length_limit should be limited to non-negative integers (>= 0), and that negative values should be rejected with an error.

To help explore this direction, I’ve also opened a PR: #1908 .

Steps to reproduce

• cz check -l -1 --message "feat: hello"
• cz commit -l -1

Current behavior

negative message_length_limit equals to no limit

Desired behavior

I’d like to clarify the intended behavior and, if this matches the expected design, make it consistent:

• message_length_limit < 0 raises an error.
• message_length_limit = 0 disables the length limit.
• Leaving it unset in the CLI, or explicitly passing None, falls back to the config value consistently.

If maintainers prefer a different policy, I’d be happy to adjust the PR accordingly.

Screenshots

No response

Environment

Commitizen Version: 4.13.9
Python Version: 3.14.3 (main, Feb 3 2026, 15:32:20) [Clang 15.0.0 (clang-1500.1.0.2.5)]
Operating System: Darwin

[SARAMALI15792]

Investigation

I've traced this through the codebase history to understand the current behavior and context:

Timeline

1. v3.25.0 (88ef59b): Initial feature added message_length_limit argument
2. v4.10.0 (e6bcb1a): Added config option for line length warning
3. v4.13.0 (ac2b31d): Recent fix fix(message_length_limit): align the behavior of message_length_limit #1813 standardized behavior - changed default from None to 0 to mean "no limit"

Current Behavior (as of v4.13.9)

In commitizen/commands/commit.py:87-95:

def _validate_subject_length(self, message: str) -> None:
    message_length_limit = self.arguments.get(
        "message_length_limit", self.config.settings.get("message_length_limit", 0)
    )
    # By the contract, message_length_limit is set to 0 for no limit
    if (
        message_length_limit is None or message_length_limit <= 0
    ):  # do nothing for no limit
        return

The issue: message_length_limit <= 0 treats negative values as "no limit", which is inconsistent and confusing.

Root Cause

The recent fix in #1813 changed the default from None to 0 for "no limit", but the validation logic still checks <= 0 instead of == 0. This means:

• message_length_limit = 0 → no limit ✅ (intended)
• message_length_limit = -1 → no limit ✅ (unintended, should error)

Why This Is Safe to Fix

PR #1908 proposes the right approach:

1. Validate at initialization that message_length_limit >= 0
2. Change condition from <= 0 to == 0
3. Raise InvalidCommandArgumentError for negative values

This is safe because:

• The default is 0 (no limit), so existing configs without this setting are unaffected
• Negative values currently work as "no limit", but this is undocumented behavior
• Users relying on negative values can simply change to 0 (same effect, clearer intent)
• The fix aligns with the v4.13.0 design where 0 means "no limit"

Proposed Behavior (from #1908)

• message_length_limit < 0 → raises InvalidCommandArgumentError ❌
• message_length_limit = 0 → disables length limit ✅
• message_length_limit > 0 → enforces limit ✅
• Unset in CLI → falls back to config value ✅

This matches the desired behavior described in the issue.

[SARAMALI15792]

Implementation Complete

I've implemented the fix for this issue in PR #1916.

Summary

The fix validates that message_length_limit >= 0 at initialization time in both cz check and cz commit commands. Negative values now raise InvalidCommandArgumentError with a clear message.

Testing

All tests pass, including new test cases for:

• Negative CLI values raise error
• Negative config values raise error
• Zero disables limit (no limit)
• Positive values enforce limit
• CLI overrides config correctly
• Config fallback works when CLI is unset

Manual Verification

# Before fix: negative values accepted (treated as no limit)
echo "feat: hello" | cz check -l -1
# Output: Commit validation: successful!

# After fix: negative values rejected
echo "feat: hello" | cz check -l -1
# Output: message_length_limit must be a non-negative integer

The implementation aligns with the desired behavior outlined in this issue:

• message_length_limit < 0 → raises error ❌
• message_length_limit = 0 → disables length limit ✅
• message_length_limit > 0 → enforces limit ✅
• Unset in CLI → falls back to config ✅

Documentation has been updated in both docs/config/check.md and docs/config/commit.md to clarify the non-negative requirement.