Skip to content

docs: document additional_dependencies for pre-commit plugin hooks - #2095

Merged
woile merged 1 commit into
commitizen-tools:masterfrom
akashchamp:docs/pre-commit-additional-dependencies
Sep 24, 2026
Merged

woile merged 1 commit into
commitizen-tools:masterfrom
akashchamp:docs/pre-commit-additional-dependencies

Conversation

@akashchamp

Copy link
Copy Markdown
Contributor

Description

Documents that a third-party commitizen plugin (e.g. cz-conventional-gitmoji) must be listed under additional_dependencies in .pre-commit-config.yaml when used with the commitizen pre-commit/prek hook. prek/pre-commit installs each hook in its own isolated environment, so a plugin that isn't part of commitizen itself is not importable unless declared, and the hook fails with The committer has not been found in the system.

Adds a "Using a third-party commitizen plugin" tip (with a working additional_dependencies example) right after the existing .pre-commit-config.yaml example in the pre-commit setup tutorial, since that's the doc page people follow to configure the hook. No code changes.

Closes #1141

Checklist

Was generative AI tooling used to co-author this PR?

  • Yes (please specify the tool below)

Generated-by: Claude (Anthropic, Claude Code) following the guidelines. I reviewed the change, reproduced the bug, and verified the documented fix myself (see "Steps to Test" below).

Code Changes

  • Add test cases to all the changes you introduce — N/A, documentation-only change (no code behavior changed)
  • Run uv run poe all locally to ensure this change passes linter check and tests — N/A code paths untouched; ran uv run mkdocs build --strict and uv run prek run --files docs/tutorials/auto_check.md instead (see below)
  • Manually test the changes:
    • Verify the feature/bug fix works as expected in real-world scenarios
    • Test edge cases and error conditions
    • Ensure backward compatibility is maintained
    • Document any manual testing steps performed
  • Update the documentation for the changes — this PR is the documentation update

Documentation Changes

  • Run uv run poe doc locally to ensure the documentation pages renders correctly
  • Check and fix any broken links (internal or external)

Expected Behavior

The pre-commit setup tutorial should tell readers that a third-party commitizen plugin needs to be added to additional_dependencies, so they don't hit The committer has not been found in the system the way the issue reporter did.

Steps to Test This Pull Request

  1. Reproduced the exact bug from the issue: created a scratch repo with pyproject.toml containing [tool.commitizen]\nname = "cz_gitmoji", and a .pre-commit-config.yaml pointing the commitizen hook at this repo without additional_dependencies. Ran git commit with stages: [commit-msg] installed via prek install --hook-type commit-msg:
    commitizen check.........................................................Failed
    - hook id: commitizen
    - exit code: 1
    
      The committer has not been found in the system.
    
      Try running 'pip install cz_gitmoji'
    
    This matches the issue's reported failure exactly.
  2. Added additional_dependencies: ["cz-conventional-gitmoji"] to the same hook config (the fix this PR documents) and re-ran the commit:
    commitizen check.........................................................Passed
    [master 83bfd29] feat: add gitmoji feature
    
    Commit succeeded (exit code 0).
  3. Built the docs to confirm the new admonition renders correctly and all links resolve: uv run mkdocs build --strict → exit code 0, no warnings.
  4. Ran the repo's pre-commit hooks against the changed file: uv run prek run --files docs/tutorials/auto_check.md → all applicable hooks (trailing-whitespace, end-of-file-fixer, blacken-docs, codespell, etc.) passed.

Additional Context

Issue: #1141. The maintainer (@Lee-W) confirmed in the issue thread that this is a documentation gap ("this is indeed something we can improve in the documentation"), and another user (@atiasn) confirmed in a follow-up comment that adding additional_dependencies: ["cz-conventional-gitmoji"] resolved the problem for them — this PR documents exactly that fix.

Using a third-party commitizen plugin (e.g. cz-conventional-gitmoji)
with the pre-commit/prek "commitizen" hook fails with "The committer
has not been found in the system" because pre-commit installs each
hook in its own isolated environment, so the plugin package is not
available unless it is listed in additional_dependencies.

Add a tip to the pre-commit tutorial explaining this and showing the
working additional_dependencies configuration.

Closes commitizen-tools#1141
@woile
woile merged commit cc2f522 into commitizen-tools:master Sep 24, 2026
19 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

commitizen check failed using the "cz-conventional-gitmoji"

2 participants