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

2509abhi · bearomorphism · commit 09db284c7376 · 2026-01-15T21:03:42.000+08:00
diff --git a/commitizen/cli.py b/commitizen/cli.py
@@ -208,6 +208,11 @@ def __call__(
                     {
                         "name": "--files-only",
                         "action": "store_true",
+                        "help": "Bump version in config files (deprecated; use --version-files-only instead).",
+                    },
+                    {
+                        "name": "--version-files-only",
+                        "action": "store_true",
                         "help": "bump version in the files from the config",
                     },
                     {
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
@@ -366,7 +367,14 @@ def __call__(self) -> None:
                 else None,
             )
 
-        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.
+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
@@ -470,7 +470,7 @@ 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")
 
     tag_exists = git.tag_exist("0.3.0")
     assert tag_exists is False
@@ -1267,7 +1267,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
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]
@@ -22,7 +23,9 @@ positional arguments:
 options:
   -h, --help            show this help message and exit
   --dry-run             show output to stdout, no commit, no modified files
-  --files-only          bump version in the files from the config
+  --files-only          Bump version in config files (deprecated; use
+                        --version-files-only instead).
+  --version-files-only  bump version in the files from the config
   --local-version       bump only the local version portion
   --changelog, -ch      generate the changelog for the newest version
   --no-verify           this option bypasses the pre-commit and commit-msg
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]
@@ -22,7 +23,9 @@ positional arguments:
 options:
   -h, --help            show this help message and exit
   --dry-run             show output to stdout, no commit, no modified files
-  --files-only          bump version in the files from the config
+  --files-only          Bump version in config files (deprecated; use
+                        --version-files-only instead).
+  --version-files-only  bump version in the files from the config
   --local-version       bump only the local version portion
   --changelog, -ch      generate the changelog for the newest version
   --no-verify           this option bypasses the pre-commit and commit-msg
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]
@@ -22,7 +23,9 @@ positional arguments:
 options:
   -h, --help            show this help message and exit
   --dry-run             show output to stdout, no commit, no modified files
-  --files-only          bump version in the files from the config
+  --files-only          Bump version in config files (deprecated; use
+                        --version-files-only instead).
+  --version-files-only  bump version in the files from the config
   --local-version       bump only the local version portion
   --changelog, -ch      generate the changelog for the newest version
   --no-verify           this option bypasses the pre-commit and commit-msg
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]
@@ -22,7 +23,9 @@ positional arguments:
 options:
   -h, --help            show this help message and exit
   --dry-run             show output to stdout, no commit, no modified files
-  --files-only          bump version in the files from the config
+  --files-only          Bump version in config files (deprecated; use
+                        --version-files-only instead).
+  --version-files-only  bump version in the files from the config
   --local-version       bump only the local version portion
   --changelog, -ch      generate the changelog for the newest version
   --no-verify           this option bypasses the pre-commit and commit-msg
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]
@@ -22,7 +23,9 @@ positional arguments:
 options:
   -h, --help            show this help message and exit
   --dry-run             show output to stdout, no commit, no modified files
-  --files-only          bump version in the files from the config
+  --files-only          Bump version in config files (deprecated; use
+                        --version-files-only instead).
+  --version-files-only  bump version in the files from the config
   --local-version       bump only the local version portion
   --changelog, -ch      generate the changelog for the newest version
   --no-verify           this option bypasses the pre-commit and commit-msg

Original file line number	Diff line number	Diff line change
`@@ -208,6 +208,11 @@ def __call__(`
`208`	`208`	`{`
`209`	`209`	`"name": "--files-only",`
`210`	`210`	`"action": "store_true",`
	`211`	`+ "help": "Bump version in config files (deprecated; use --version-files-only instead).",`
	`212`	`+ },`
	`213`	`+ {`
	`214`	`+ "name": "--version-files-only",`
	`215`	`+ "action": "store_true",`
`211`	`216`	`"help": "bump version in the files from the config",`
`212`	`217`	`},`
`213`	`218`	`{`