D7861: graftcopies: document why the function is useful at all

[martinvonz (Martin von Zweigbergk)]

martinvonz updated this revision to Diff 19253.

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST UPDATE
  https://phab.mercurial-scm.org/D7861?vs=19252&id=19253

BRANCH
  default

CHANGES SINCE LAST ACTION
  https://phab.mercurial-scm.org/D7861/new/

REVISION DETAIL
  https://phab.mercurial-scm.org/D7861

AFFECTED FILES
  mercurial/copies.py

CHANGE DETAILS

diff --git a/mercurial/copies.py b/mercurial/copies.py
--- a/mercurial/copies.py
+++ b/mercurial/copies.py
@@ -857,7 +857,21 @@
 
 
 def graftcopies(wctx, ctx, base):
-    """reproduce copies between base and ctx in the wctx"""
+    """reproduce copies between base and ctx in the wctx
+
+    Unlike mergecopies(), this function will only consider copies between base
+    and ctx; it will ignore copies between base and wctx. Also unlike
+    mergecopies(), this function will apply copies to the working copy (instead
+    of just returning information about the copies). That makes it cheaper
+    (especially in the common case of base==ctx.p1()) and useful also when
+    experimental.copytrace=off.
+
+    merge.update() will have already marked most copies, but it will only
+    mark copies if it thinks the source files are related (see
+    merge._related()). It will also not mark copies if the file wasn't modified
+    on the local side. This function adds the copies that were "missed"
+    by merge.update().
+    """
     new_copies = pathcopies(base, ctx)
     _filter(wctx.p1(), wctx, new_copies)
     for dst, src in pycompat.iteritems(new_copies):



To: martinvonz, #hg-reviewers
Cc: mercurial-devel