graftcopies: document why the function is useful at all
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.
Differential Revision: https://phab.mercurial-scm.org/D7861
--- a/mercurial/copies.py Fri Dec 27 13:47:59 2019 -0800
+++ b/mercurial/copies.py Sun Dec 29 17:53:48 2019 -0800
@@ -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):