Add --splice support to merge command

Added ``--splice`` support to the :func:`.merge` command. Previously, the
merge command would suggest using ``--splice`` when attempting to merge
non-head revisions, but the flag was not actually accepted by the command.
The ``splice`` parameter is now available in both the command-line
interface and the :func:`.command.merge` function, matching the existing
support in :func:`.command.revision`.  Pull request courtesy Kadir Can
Ozden.

Fixes: #1712
Closes: #1794
Pull-request: #1794
Pull-request-sha: a0f9b6d

Change-Id: I12125061777b829b98663adab1701154c6f7c3ac

Author: bysiber

alembic/command.py

@@ -385,6 +385,7 @@ def merge(
     message: Optional[str] = None,
     branch_label: Optional[_RevIdType] = None,
     rev_id: Optional[str] = None,
+    splice: bool = False,
 ) -> Optional[Script]:
     """Merge two revisions together.  Creates a new migration file.
 
@@ -399,6 +400,11 @@ def merge(
     :param rev_id: hardcoded revision identifier instead of generating a new
      one.
 
+    :param splice: if True, allow the merge to create a new branch point
+     even if the given revisions are not heads.
+
+     .. versionadded:: 1.18.5
+
     .. seealso::
 
         :ref:`branches`
@@ -435,6 +441,7 @@ def nothing(rev, context):
         refresh=True,
         head=revisions,
         branch_labels=branch_label,
+        splice=splice,
         **template_args,  # type:ignore[arg-type]
     )
 

docs/build/unreleased/1712.rst

@@ -0,0 +1,11 @@
+.. change::
+    :tags: usecase, commands
+    :tickets: 1712
+
+    Added ``--splice`` support to the :func:`.merge` command. Previously, the
+    merge command would suggest using ``--splice`` when attempting to merge
+    non-head revisions, but the flag was not actually accepted by the command.
+    The ``splice`` parameter is now available in both the command-line
+    interface and the :func:`.command.merge` function, matching the existing
+    support in :func:`.command.revision`.  Pull request courtesy Kadir Can
+    Ozden.

tests/test_command.py

@@ -276,6 +276,38 @@ def test_merge_cmd_revision_environment(self, rev_env):
 
         assert os.path.exists(rev.path)
 
+    def test_merge_cmd_splice(self):
+        """merge with --splice allows non-head revisions to be merged."""
+        cfg = self.cfg
+        self.a, self.b, self.c = three_rev_fixture(cfg)
+        self.d, self.e, self.f = multi_heads_fixture(
+            cfg, self.a, self.b, self.c
+        )
+        # e and f are heads, but b is not a head.
+        # merging b and c (at least one is not a head) should fail
+        # without splice.
+        with expect_raises_message(
+            util.CommandError,
+            "please specify --splice",
+        ):
+            command.merge(
+                self.cfg,
+                [self.b, self.d],
+                rev_id="should_fail",
+            )
+        # with splice=True, it should succeed
+        command.merge(
+            self.cfg,
+            [self.b, self.d],
+            rev_id="splice_merge",
+            splice=True,
+        )
+        rev = ScriptDirectory.from_config(self.cfg).get_revision(
+            "splice_merge"
+        )
+        assert os.path.exists(rev.path)
+        eq_(rev.module.down_revision, (self.b, self.d))
+
 
 class CurrentTest(_BufMixin, TestBase):
     @classmethod