feat(bump): add --merge-prerelease flag

Closes #1934.

Adds a `--merge-prerelease` CLI flag to `cz bump` that mirrors the
existing flag of `cz changelog`. When passed, it overrides the
`changelog_merge_prerelease` setting for a single bump invocation,
which is useful when you want to keep prerelease entries in the
changelog by default but collapse them on a release bump.

The implementation adds the flag to `commitizen/cli.py`, threads it
through the `BumpArgs` TypedDict, and forwards it to the embedded
`Changelog` invocation in `commands/bump.py`. The pre-existing
`Changelog` argument plumbing (`merge_prerelease` -> `tag_rules.
merge_prereleases`) is unchanged.

Also adds a parameterised test that proves the CLI flag enables
merging even when the config setting is left at its default
(`false`), reusing the existing fixture content.

Co-authored-by: Copilot <[email protected]>

Author: bearomorphism

commitizen/cli.py

@@ -312,6 +312,16 @@ def __call__(
                         "default": False,
                         "help": "Output changelog to stdout.",
                     },
+                    {
+                        "name": "--merge-prerelease",
+                        "action": "store_true",
+                        "default": None,
+                        "help": (
+                            "Collect all changes from prereleases into the next non-prerelease "
+                            "when generating the changelog. "
+                            "Overrides the `changelog_merge_prerelease` setting."
+                        ),
+                    },
                     {
                         "name": ["--git-output-to-stderr"],
                         "action": "store_true",

commitizen/commands/bump.py

@@ -56,6 +56,7 @@ class BumpArgs(Settings, total=False):
     increment: Increment | None
     local_version: bool
     manual_version: str | None
+    merge_prerelease: bool | None
     no_verify: bool
     prerelease: Prerelease | None
     retry: bool
@@ -319,6 +320,9 @@ def __call__(self) -> None:
                 # governs logic for merge_prerelease
                 "during_version_bump": self.arguments["prerelease"] is None,
             }
+            merge_prerelease = self.arguments.get("merge_prerelease")
+            if merge_prerelease is not None:
+                changelog_args["merge_prerelease"] = merge_prerelease
             if self.changelog_to_stdout:
                 try:
                     Changelog(

docs/commands/bump.md

@@ -226,6 +226,16 @@ Useful when used with `--changelog-to-stdout` and piping the output to a file.
 
 For example, `git commit` output may pollute `stdout`, so it is recommended to use this flag when piping the output to a file.
 
+### `--merge-prerelease`
+
+Collect all changes from prereleases into the next non-prerelease entry when generating the incremental changelog.
+
+This mirrors the `--merge-prerelease` flag of `cz changelog` and overrides the [`changelog_merge_prerelease`](./changelog.md#--merge-prerelease) setting for a single bump invocation. It is useful when you want to keep prerelease entries in the changelog by default but collapse them on a release bump:
+
+```bash
+cz bump --changelog --merge-prerelease
+```
+
 ### `--retry`
 
 If you use tools like [pre-commit](https://pre-commit.com/), you can add this flag.

tests/commands/test_bump_command.py

@@ -1423,6 +1423,37 @@ def test_is_initial_tag(mocker: MockFixture, tmp_commitizen_project, util: UtilF
     assert bump_cmd._is_initial_tag(None, is_yes=False) is False
 
 
+@pytest.mark.parametrize("test_input", ["rc", "alpha", "beta"])
+@pytest.mark.usefixtures("tmp_commitizen_project")
+@pytest.mark.freeze_time("2025-01-01")
+def test_changelog_cli_flag_merge_prerelease(
+    mocker: MockFixture,
+    util: UtilFixture,
+    changelog_path: Path,
+    config_path: Path,
+    file_regression: FileRegressionFixture,
+    test_input: str,
+):
+    """`cz bump --merge-prerelease` overrides the (default false) config setting."""
+    with config_path.open("a") as f:
+        f.write("update_changelog_on_bump = true\n")
+        f.write("annotated_tag = true\n")
+
+    util.create_file_and_commit("irrelevant commit")
+    mocker.patch("commitizen.git.GitTag.date", "1970-01-01")
+    git.tag("0.1.0")
+
+    util.create_file_and_commit("feat: add new output")
+    util.create_file_and_commit("fix: output glitch")
+    util.run_cli("bump", "--prerelease", test_input, "--yes")
+
+    util.run_cli("bump", "--changelog", "--merge-prerelease")
+
+    out = changelog_path.read_text()
+
+    file_regression.check(out, extension=".md")
+
+
 @pytest.mark.parametrize("test_input", ["rc", "alpha", "beta"])
 @pytest.mark.usefixtures("tmp_commitizen_project")
 @pytest.mark.freeze_time("2025-01-01")

tests/commands/test_bump_command/test_changelog_cli_flag_merge_prerelease_alpha_.md

@@ -0,0 +1,11 @@
+## 0.2.0 (2025-01-01)
+
+### Feat
+
+- add new output
+
+### Fix
+
+- output glitch
+
+## 0.1.0 (1970-01-01)

tests/commands/test_bump_command/test_changelog_cli_flag_merge_prerelease_beta_.md

@@ -0,0 +1,11 @@
+## 0.2.0 (2025-01-01)
+
+### Feat
+
+- add new output
+
+### Fix
+
+- output glitch
+
+## 0.1.0 (1970-01-01)

tests/commands/test_bump_command/test_changelog_cli_flag_merge_prerelease_rc_.md

@@ -0,0 +1,11 @@
+## 0.2.0 (2025-01-01)
+
+### Feat
+
+- add new output
+
+### Fix
+
+- output glitch
+
+## 0.1.0 (1970-01-01)

tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_10_bump_.txt

@@ -6,9 +6,10 @@ usage: cz bump [-h] [--dry-run] [--files-only] [--version-files-only]
                [--increment-mode {linear,exact}] [--check-consistency]
                [--annotated-tag]
                [--annotated-tag-message ANNOTATED_TAG_MESSAGE] [--gpg-sign]
-               [--changelog-to-stdout] [--git-output-to-stderr] [--retry]
-               [--major-version-zero] [--template TEMPLATE] [--extra EXTRA]
-               [--file-name FILE_NAME] [--prerelease-offset PRERELEASE_OFFSET]
+               [--changelog-to-stdout] [--merge-prerelease]
+               [--git-output-to-stderr] [--retry] [--major-version-zero]
+               [--template TEMPLATE] [--extra EXTRA] [--file-name FILE_NAME]
+               [--prerelease-offset PRERELEASE_OFFSET]
                [--version-scheme {pep440,semver,semver2}]
                [--version-type {pep440,semver,semver2}]
                [--build-metadata BUILD_METADATA] [--get-next]
@@ -64,6 +65,9 @@ options:
   --gpg-sign, -s        Sign tag instead of lightweight one.
   --changelog-to-stdout
                         Output changelog to stdout.
+  --merge-prerelease    Collect all changes from prereleases into the next
+                        non-prerelease when generating the changelog.
+                        Overrides the `changelog_merge_prerelease` setting.
   --git-output-to-stderr
                         Redirect git output to stderr.
   --retry               Retry commit if it fails for the first time.

tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_11_bump_.txt

@@ -6,9 +6,10 @@ usage: cz bump [-h] [--dry-run] [--files-only] [--version-files-only]
                [--increment-mode {linear,exact}] [--check-consistency]
                [--annotated-tag]
                [--annotated-tag-message ANNOTATED_TAG_MESSAGE] [--gpg-sign]
-               [--changelog-to-stdout] [--git-output-to-stderr] [--retry]
-               [--major-version-zero] [--template TEMPLATE] [--extra EXTRA]
-               [--file-name FILE_NAME] [--prerelease-offset PRERELEASE_OFFSET]
+               [--changelog-to-stdout] [--merge-prerelease]
+               [--git-output-to-stderr] [--retry] [--major-version-zero]
+               [--template TEMPLATE] [--extra EXTRA] [--file-name FILE_NAME]
+               [--prerelease-offset PRERELEASE_OFFSET]
                [--version-scheme {pep440,semver,semver2}]
                [--version-type {pep440,semver,semver2}]
                [--build-metadata BUILD_METADATA] [--get-next]
@@ -64,6 +65,9 @@ options:
   --gpg-sign, -s        Sign tag instead of lightweight one.
   --changelog-to-stdout
                         Output changelog to stdout.
+  --merge-prerelease    Collect all changes from prereleases into the next
+                        non-prerelease when generating the changelog.
+                        Overrides the `changelog_merge_prerelease` setting.
   --git-output-to-stderr
                         Redirect git output to stderr.
   --retry               Retry commit if it fails for the first time.

tests/commands/test_common_command/test_command_shows_description_when_use_help_option_py_3_12_bump_.txt

@@ -6,9 +6,10 @@ usage: cz bump [-h] [--dry-run] [--files-only] [--version-files-only]
                [--increment-mode {linear,exact}] [--check-consistency]
                [--annotated-tag]
                [--annotated-tag-message ANNOTATED_TAG_MESSAGE] [--gpg-sign]
-               [--changelog-to-stdout] [--git-output-to-stderr] [--retry]
-               [--major-version-zero] [--template TEMPLATE] [--extra EXTRA]
-               [--file-name FILE_NAME] [--prerelease-offset PRERELEASE_OFFSET]
+               [--changelog-to-stdout] [--merge-prerelease]
+               [--git-output-to-stderr] [--retry] [--major-version-zero]
+               [--template TEMPLATE] [--extra EXTRA] [--file-name FILE_NAME]
+               [--prerelease-offset PRERELEASE_OFFSET]
                [--version-scheme {pep440,semver,semver2}]
                [--version-type {pep440,semver,semver2}]
                [--build-metadata BUILD_METADATA] [--get-next]
@@ -64,6 +65,9 @@ options:
   --gpg-sign, -s        Sign tag instead of lightweight one.
   --changelog-to-stdout
                         Output changelog to stdout.
+  --merge-prerelease    Collect all changes from prereleases into the next
+                        non-prerelease when generating the changelog.
+                        Overrides the `changelog_merge_prerelease` setting.
   --git-output-to-stderr
                         Redirect git output to stderr.
   --retry               Retry commit if it fails for the first time.