From 984bb628c4850a145a7b0692263e0815956961b7 Mon Sep 17 00:00:00 2001
From: Sedat <sedataraswork@gmail.com>
Date: Mon, 23 Mar 2026 22:22:17 +1100
Subject: [PATCH] docs: add FAQ entry for dependency version conflict

Closes #819

When a dependency shares the same version as the project, Commitizen's
version_files replacement will match both. Add a FAQ section explaining:
- Option 1: anchor the version_files pattern with ^ to match line starts
- Option 2 (recommended): use version_provider to avoid regex matching entirely

Co-authored-by: Claude <noreply@anthropic.com>
---
 docs/faq.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/docs/faq.md b/docs/faq.md
index 568ec2fbe8..89e1a0f6ca 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -76,6 +76,50 @@ legacy_tag_formats = [
 ]
 ```
 
+## A dependency has the same version as my project — how do I prevent it from being bumped?
+
+When using [`version_files`](config/bump.md#version_files) to track your project version,
+Commitizen searches for the current version string and replaces it with the new one.
+If a dependency in the same file happens to share the exact same version number, it will
+also be updated, which is usually undesirable.
+
+There are two ways to avoid this:
+
+### Option 1 — Anchor the pattern with `^`
+
+Prefix the file entry with `^` to match only lines that *start* with `version`:
+
+```toml
+[tool.commitizen]
+version_files = ["pyproject.toml:^version"]
+```
+
+This ensures only lines like `version = "1.2.3"` are matched, not dependency
+specifications that happen to contain the same version string.
+
+### Option 2 (recommended) — Use a `version_provider`
+
+Instead of `version_files`, use the appropriate
+[`version_provider`](config/version_provider.md) for your project type. Commitizen
+will then update exactly the right field without any regex-based text replacement.
+
+For example, if you use `pyproject.toml` with a `[project]` table (PEP 621):
+
+```toml
+[tool.commitizen]
+version_provider = "pep621"
+```
+
+Or for Poetry users:
+
+```toml
+[tool.commitizen]
+version_provider = "poetry"
+```
+
+See the [version providers reference](config/version_provider.md) for all available
+options.
+
 ## How to avoid warnings for expected non-version tags?
 
 You can explicitly ignore them with [`ignored_tag_formats`](config/bump.md#ignored_tag_formats).