From 1a60f727eadd50c7532d463a87abe9cb73989d98 Mon Sep 17 00:00:00 2001
From: Vamika Singhal <vamikasinghal@gmail.com>
Date: Tue, 6 Oct 2026 15:49:25 -0700
Subject: [PATCH] docs(faq): explain how to avoid bumping dependencies that
 share the project version

Closes #819

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/faq.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/docs/faq.md b/docs/faq.md
index 568ec2fbe8..86b2f25b84 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -89,3 +89,46 @@ ignored_tag_formats = [
     "v${major}.${minor}",
 ]
 ```
+
+## Why does `cz bump` also change a dependency that has the same version as my project?
+
+When an entry in [`version_files`](config/bump.md#version_files) has no pattern, or a loose one, Commitizen replaces the current version on every line that matches it.
+If a dependency happens to use the same version string as your project, that line gets bumped too:
+
+```toml title="pyproject.toml"
+[tool.poetry]
+version = "6.1.0"
+
+[tool.poetry.dependencies]
+smart-open = {version = ">=5.2.0,<6.1.0", extras = ["s3"]}  # also becomes <6.2.0
+
+[tool.commitizen]
+version = "6.1.0"
+version_files = ["pyproject.toml:version"]
+```
+
+There are two ways to avoid this.
+
+### Option 1 (recommended): use a version provider
+
+Let a [version provider](config/version_provider.md) update the version field directly instead of listing the file in `version_files`.
+Providers edit the exact key (for example `tool.poetry.version` or `project.version`), so dependencies are never touched:
+
+```toml title="pyproject.toml"
+[tool.commitizen]
+version_provider = "poetry"  # or "pep621", "uv", "npm", "cargo", ...
+```
+
+See also the [PEP621 FAQ entry](#support-for-pep621) above.
+
+### Option 2: anchor the `version_files` pattern
+
+The part after the colon in a `version_files` entry is a regular expression, matched against each line.
+Anchor it with `^` so only lines that *start* with `version` are updated:
+
+```toml title="pyproject.toml"
+[tool.commitizen]
+version_files = ["pyproject.toml:^version"]
+```
+
+See [`version_files`](config/bump.md#version_files) for more details on the `file:pattern` syntax.