Skip to content

Commit 984bb62

Browse files
sedat4rasclaude
andcommitted
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>
1 parent 30afd63 commit 984bb62

File tree

1 file changed

+44
-0
lines changed

1 file changed

+44
-0
lines changed

docs/faq.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,50 @@ legacy_tag_formats = [
7676
]
7777
```
7878

79+
## A dependency has the same version as my project — how do I prevent it from being bumped?
80+
81+
When using [`version_files`](config/bump.md#version_files) to track your project version,
82+
Commitizen searches for the current version string and replaces it with the new one.
83+
If a dependency in the same file happens to share the exact same version number, it will
84+
also be updated, which is usually undesirable.
85+
86+
There are two ways to avoid this:
87+
88+
### Option 1 — Anchor the pattern with `^`
89+
90+
Prefix the file entry with `^` to match only lines that *start* with `version`:
91+
92+
```toml
93+
[tool.commitizen]
94+
version_files = ["pyproject.toml:^version"]
95+
```
96+
97+
This ensures only lines like `version = "1.2.3"` are matched, not dependency
98+
specifications that happen to contain the same version string.
99+
100+
### Option 2 (recommended) — Use a `version_provider`
101+
102+
Instead of `version_files`, use the appropriate
103+
[`version_provider`](config/version_provider.md) for your project type. Commitizen
104+
will then update exactly the right field without any regex-based text replacement.
105+
106+
For example, if you use `pyproject.toml` with a `[project]` table (PEP 621):
107+
108+
```toml
109+
[tool.commitizen]
110+
version_provider = "pep621"
111+
```
112+
113+
Or for Poetry users:
114+
115+
```toml
116+
[tool.commitizen]
117+
version_provider = "poetry"
118+
```
119+
120+
See the [version providers reference](config/version_provider.md) for all available
121+
options.
122+
79123
## How to avoid warnings for expected non-version tags?
80124

81125
You can explicitly ignore them with [`ignored_tag_formats`](config/bump.md#ignored_tag_formats).

0 commit comments

Comments
 (0)