merge: add a back_out() function to encapsulate update()

I've sent several earlier patches adding `merge.clean_update()`,
`merge.merge()` etc, one function for each use case. This patch
continues that work. I plan to hide the complex `update()` eventually.

Differential Revision: https://phab.mercurial-scm.org/D9064

mercurial/commands.py

@@ -790,7 +790,8 b' def _dobackout(ui, repo, node=None, rev='
 
     cmdutil.checkunfinished(repo)
     cmdutil.bailifchanged(repo)
-    node = scmutil.revsingle(repo, rev).node()
+    ctx = scmutil.revsingle(repo, rev)
+    node = ctx.node()
 
     op1, op2 = repo.dirstate.parents()
     if not repo.changelog.isancestor(node, op1):
@@ -821,14 +822,7 b' def _dobackout(ui, repo, node=None, rev='
         with dirstateguard.dirstateguard(repo, b'backout'):
             overrides = {(b'ui', b'forcemerge'): opts.get(b'tool', b'')}
             with ui.configoverride(overrides, b'backout'):
-                stats = mergemod.update(
-                    repo,
-                    parent,
-                    branchmerge=True,
-                    force=True,
-                    ancestor=node,
-                    mergeancestor=False,
-                )
+                stats = mergemod.back_out(ctx, parent=repo[parent])
             repo.setparents(op1, op2)
         hg._showstats(repo, stats)
         if stats.unresolvedcount:

mercurial/merge.py

@@ -2159,6 +2159,23 b' def graft('
     return stats
 
 
+def back_out(ctx, parent=None, wc=None):
+    if parent is None:
+        if ctx.p2() is not None:
+            raise error.ProgrammingError(
+                b"must specify parent of merge commit to back out"
+            )
+        parent = ctx.p1()
+    return update(
+        ctx.repo(),
+        parent,
+        branchmerge=True,
+        force=True,
+        ancestor=ctx.node(),
+        mergeancestor=False,
+    )
+
+
 def purge(
     repo,
     matcher,