feat(bump): add --version-files-only and deprecate --files-only

2509abhi · bearomorphism · commit 527c81434e5c · 2026-01-31T15:14:03.000+08:00
diff --git a/commitizen/cli.py b/commitizen/cli.py
@@ -209,7 +209,12 @@ def __call__(
                     {
                         "name": "--files-only",  # TODO: rename to --version-files-only
                         "action": "store_true",
-                        "help": "Bump version in the `version_files` specified in the configuration file only.",
+                        "help": "Bump version in the `version_files` specified in the configuration file only(deprecated; use --version-files-only instead).",
+                    },
+                    {
+                        "name": "--version-files-only",
+                        "action": "store_true",
+                        "help": "bump version in the files from the config",
                     },
                     {
                         "name": "--local-version",
diff --git a/commitizen/commands/bump.py b/commitizen/commands/bump.py
@@ -49,6 +49,7 @@ class BumpArgs(Settings, total=False):
     dry_run: bool
     file_name: str
     files_only: bool | None
+    version_files_only: bool | None
     get_next: bool  # TODO: maybe rename to `next_version_to_stdout`
     git_output_to_stderr: bool
     increment_mode: str
@@ -365,7 +366,14 @@ def __call__(self) -> None:
                 changelog_file_name=changelog_file_name,
             )
 
-        if self.arguments["files_only"]:
+        if self.arguments.get("files_only"):
+            warnings.warn(
+                "--files-only is deprecated and will be removed in v5. Use --version-files-only instead.",
+                DeprecationWarning,
+            )
+            raise ExpectedExit()
+
+        if self.arguments.get("version_files_only"):
             raise ExpectedExit()
 
         # FIXME: check if any changes have been staged
diff --git a/docs/commands/bump.md b/docs/commands/bump.md
@@ -109,12 +109,12 @@ Commitizen supports the [PEP 440][pep440] version format, which includes several
 
 ![cz bump --help](../images/cli_help/cz_bump___help.svg)
 
-### `--files-only`
+### `--version-files-only`
 
 Bumps the version in the files defined in [`version_files`][version_files] without creating a commit and tag on the git repository.
 
 ```bash
-cz bump --files-only
+cz bump --version-files-only
 ```
 
 ### `--changelog`
diff --git a/tests/commands/test_bump_command.py b/tests/commands/test_bump_command.py
@@ -418,7 +418,8 @@ def test_bump_files_only(tmp_commitizen_project, util: UtilFixture):
 
     util.create_file_and_commit("feat: another new feature")
     with pytest.raises(ExpectedExit):
-        util.run_cli("bump", "--yes", "--files-only")
+        util.run_cli("bump", "--yes", "--version-files-only")
+
     assert git.tag_exist("0.3.0") is False
 
     with open(tmp_version_file, encoding="utf-8") as f:
@@ -1175,7 +1176,7 @@ def test_bump_changelog_contains_increment_only(
     # it should only include v3 changes
     util.create_file_and_commit("feat(next)!: next version")
     with pytest.raises(ExpectedExit):
-        util.run_cli("bump", "--yes", "--files-only", "--changelog-to-stdout")
+        util.run_cli("bump", "--yes", "--version-files-only", "--changelog-to-stdout")
     out, _ = capsys.readouterr()
 
     assert "3.0.0" in out
@@ -1463,3 +1464,11 @@ def test_changelog_config_flag_merge_prerelease_only_prerelease_present(
         out = f.read()
 
     file_regression.check(out, extension=".md")
+
+
+@pytest.mark.usefixtures("tmp_commitizen_project")
+def test_bump_deprecate_files_only(util: UtilFixture):
+    util.create_file_and_commit("feat: new file")
+    with pytest.warns(DeprecationWarning):
+        with pytest.raises(ExpectedExit):
+            util.run_cli("bump", "--yes", "--files-only")
diff --git a/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_10_bump_.txt b/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_10_bump_.txt
@@ -1,7 +1,8 @@
-usage: cz bump [-h] [--dry-run] [--files-only] [--local-version] [--changelog]
-               [--no-verify] [--yes] [--tag-format TAG_FORMAT]
-               [--bump-message BUMP_MESSAGE] [--prerelease {alpha,beta,rc}]
-               [--devrelease DEVRELEASE] [--increment {MAJOR,MINOR,PATCH}]
+usage: cz bump [-h] [--dry-run] [--files-only] [--version-files-only]
+               [--local-version] [--changelog] [--no-verify] [--yes]
+               [--tag-format TAG_FORMAT] [--bump-message BUMP_MESSAGE]
+               [--prerelease {alpha,beta,rc}] [--devrelease DEVRELEASE]
+               [--increment {MAJOR,MINOR,PATCH}]
                [--increment-mode {linear,exact}] [--check-consistency]
                [--annotated-tag]
                [--annotated-tag-message ANNOTATED_TAG_MESSAGE] [--gpg-sign]
@@ -24,7 +25,9 @@ options:
   --dry-run             Perform a dry run, without committing or modifying
                         files.
   --files-only          Bump version in the `version_files` specified in the
-                        configuration file only.
+                        configuration file only(deprecated; use --version-
+                        files-only instead).
+  --version-files-only  bump version in the files from the config
   --local-version       Bump version only the local version portion (ignoring
                         the public version).
   --changelog, -ch      Generate the changelog for the latest version.
diff --git a/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_11_bump_.txt b/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_11_bump_.txt
@@ -1,7 +1,8 @@
-usage: cz bump [-h] [--dry-run] [--files-only] [--local-version] [--changelog]
-               [--no-verify] [--yes] [--tag-format TAG_FORMAT]
-               [--bump-message BUMP_MESSAGE] [--prerelease {alpha,beta,rc}]
-               [--devrelease DEVRELEASE] [--increment {MAJOR,MINOR,PATCH}]
+usage: cz bump [-h] [--dry-run] [--files-only] [--version-files-only]
+               [--local-version] [--changelog] [--no-verify] [--yes]
+               [--tag-format TAG_FORMAT] [--bump-message BUMP_MESSAGE]
+               [--prerelease {alpha,beta,rc}] [--devrelease DEVRELEASE]
+               [--increment {MAJOR,MINOR,PATCH}]
                [--increment-mode {linear,exact}] [--check-consistency]
                [--annotated-tag]
                [--annotated-tag-message ANNOTATED_TAG_MESSAGE] [--gpg-sign]
@@ -24,7 +25,9 @@ options:
   --dry-run             Perform a dry run, without committing or modifying
                         files.
   --files-only          Bump version in the `version_files` specified in the
-                        configuration file only.
+                        configuration file only(deprecated; use --version-
+                        files-only instead).
+  --version-files-only  bump version in the files from the config
   --local-version       Bump version only the local version portion (ignoring
                         the public version).
   --changelog, -ch      Generate the changelog for the latest version.
diff --git a/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_12_bump_.txt b/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_12_bump_.txt
@@ -1,7 +1,8 @@
-usage: cz bump [-h] [--dry-run] [--files-only] [--local-version] [--changelog]
-               [--no-verify] [--yes] [--tag-format TAG_FORMAT]
-               [--bump-message BUMP_MESSAGE] [--prerelease {alpha,beta,rc}]
-               [--devrelease DEVRELEASE] [--increment {MAJOR,MINOR,PATCH}]
+usage: cz bump [-h] [--dry-run] [--files-only] [--version-files-only]
+               [--local-version] [--changelog] [--no-verify] [--yes]
+               [--tag-format TAG_FORMAT] [--bump-message BUMP_MESSAGE]
+               [--prerelease {alpha,beta,rc}] [--devrelease DEVRELEASE]
+               [--increment {MAJOR,MINOR,PATCH}]
                [--increment-mode {linear,exact}] [--check-consistency]
                [--annotated-tag]
                [--annotated-tag-message ANNOTATED_TAG_MESSAGE] [--gpg-sign]
@@ -24,7 +25,9 @@ options:
   --dry-run             Perform a dry run, without committing or modifying
                         files.
   --files-only          Bump version in the `version_files` specified in the
-                        configuration file only.
+                        configuration file only(deprecated; use --version-
+                        files-only instead).
+  --version-files-only  bump version in the files from the config
   --local-version       Bump version only the local version portion (ignoring
                         the public version).
   --changelog, -ch      Generate the changelog for the latest version.
diff --git a/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_13_bump_.txt b/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_13_bump_.txt
@@ -1,7 +1,8 @@
-usage: cz bump [-h] [--dry-run] [--files-only] [--local-version] [--changelog]
-               [--no-verify] [--yes] [--tag-format TAG_FORMAT]
-               [--bump-message BUMP_MESSAGE] [--prerelease {alpha,beta,rc}]
-               [--devrelease DEVRELEASE] [--increment {MAJOR,MINOR,PATCH}]
+usage: cz bump [-h] [--dry-run] [--files-only] [--version-files-only]
+               [--local-version] [--changelog] [--no-verify] [--yes]
+               [--tag-format TAG_FORMAT] [--bump-message BUMP_MESSAGE]
+               [--prerelease {alpha,beta,rc}] [--devrelease DEVRELEASE]
+               [--increment {MAJOR,MINOR,PATCH}]
                [--increment-mode {linear,exact}] [--check-consistency]
                [--annotated-tag]
                [--annotated-tag-message ANNOTATED_TAG_MESSAGE] [--gpg-sign]
@@ -24,7 +25,9 @@ options:
   --dry-run             Perform a dry run, without committing or modifying
                         files.
   --files-only          Bump version in the `version_files` specified in the
-                        configuration file only.
+                        configuration file only(deprecated; use --version-
+                        files-only instead).
+  --version-files-only  bump version in the files from the config
   --local-version       Bump version only the local version portion (ignoring
                         the public version).
   --changelog, -ch      Generate the changelog for the latest version.
diff --git a/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_14_bump_.txt b/tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_14_bump_.txt
@@ -1,7 +1,8 @@
-usage: cz bump [-h] [--dry-run] [--files-only] [--local-version] [--changelog]
-               [--no-verify] [--yes] [--tag-format TAG_FORMAT]
-               [--bump-message BUMP_MESSAGE] [--prerelease {alpha,beta,rc}]
-               [--devrelease DEVRELEASE] [--increment {MAJOR,MINOR,PATCH}]
+usage: cz bump [-h] [--dry-run] [--files-only] [--version-files-only]
+               [--local-version] [--changelog] [--no-verify] [--yes]
+               [--tag-format TAG_FORMAT] [--bump-message BUMP_MESSAGE]
+               [--prerelease {alpha,beta,rc}] [--devrelease DEVRELEASE]
+               [--increment {MAJOR,MINOR,PATCH}]
                [--increment-mode {linear,exact}] [--check-consistency]
                [--annotated-tag]
                [--annotated-tag-message ANNOTATED_TAG_MESSAGE] [--gpg-sign]
@@ -24,7 +25,9 @@ options:
   --dry-run             Perform a dry run, without committing or modifying
                         files.
   --files-only          Bump version in the `version_files` specified in the
-                        configuration file only.
+                        configuration file only(deprecated; use --version-
+                        files-only instead).
+  --version-files-only  bump version in the files from the config
   --local-version       Bump version only the local version portion (ignoring
                         the public version).
   --changelog, -ch      Generate the changelog for the latest version.

Original file line number	Diff line number	Diff line change
`@@ -209,7 +209,12 @@ def __call__(`
`209`	`209`	`{`
`210`	`210`	`"name": "--files-only", # TODO: rename to --version-files-only`
`211`	`211`	`"action": "store_true",`
`212`		- "help": "Bump version in the `version_files` specified in the configuration file only.",
	`212`	+ "help": "Bump version in the `version_files` specified in the configuration file only(deprecated; use --version-files-only instead).",
	`213`	`+ },`
	`214`	`+ {`
	`215`	`+ "name": "--version-files-only",`
	`216`	`+ "action": "store_true",`
	`217`	`+ "help": "bump version in the files from the config",`
`213`	`218`	`},`
`214`	`219`	`{`
`215`	`220`	`"name": "--local-version",`