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

[martinvonz (Martin von Zweigbergk)]

martinvonz created this revision.
Herald added a subscriber: mercurial-devel.
Herald added a reviewer: hg-reviewers.

REVISION SUMMARY
  Despite having spent a significant amount on time on the copy-tracing
  code, I thought `graftcopies()` (formerly known as
  `duplicatecopies()`) was needed to duplicate copies after calling
  `merge.update()` to do a merge (as `merge.graft()` does), but it's
  actually usually not needed; `merge.update()` takes care of most
  copies. This patch documents what the function is for.

REPOSITORY
  rHG Mercurial

BRANCH
  default

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,14 @@
 
 
 def graftcopies(wctx, ctx, base):
-    """reproduce copies between base and ctx in the wctx"""
+    """reproduce copies between base and ctx in the wctx
+
+    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