# 
# 
# patch "cmd_merging.cc"
#  from [9d5dd534dcf01048c51d70b9494d5c455d988644]
#    to [72a355cbf0cc7d06dc3c320f1335b53ca34c2d70]
# 
# patch "monotone.texi"
#  from [f05dadb3d39c670a9f726fca0995a1872a20fca9]
#    to [364c5758986ba267ad91559b3d7a6ac869c197a5]
# 
============================================================
--- cmd_merging.cc	9d5dd534dcf01048c51d70b9494d5c455d988644
+++ cmd_merging.cc	72a355cbf0cc7d06dc3c320f1335b53ca34c2d70
@@ -608,13 +608,17 @@
     % result.directory_loop_conflicts.size());
 }
 
-CMD(cherrypatch, N_("workspace"), "[-r FROM] -r TO",
-    N_("cherrypick changes from other parts of history into workspace.\n"
-       "This command takes arbitrary changes made at any point in history,\n"
-       "and applies them to your current workspace, as if you had made the\n"
-       "edits by hand.\n"
+CMD(pluck, N_("workspace"), "[-r FROM] -r TO",
+    N_("Apply changes made at arbitrary places in history to current workspace.\n"
+       "This command takes changes made at any point in history, and\n"
+       "edits your current workspace to include those changes.  The end result\n"
+       "is identical to 'mtn diff -r FROM -r TO | patch -p0', except that\n"
+       "this command uses monotone's merger, and thus intelligently handles\n"
+       "renames, conflicts, and so on.\n"
+       "\n"
        "If one revision is given, applies the changes made in that revision\n"
        "compared to its parent.\n"
+       "\n"
        "If two revisions are given, applies the changes made to get from the\n"
        "first revision to the second."),
     OPT_REVISION)
============================================================
--- monotone.texi	f05dadb3d39c670a9f726fca0995a1872a20fca9
+++ monotone.texi	364c5758986ba267ad91559b3d7a6ac869c197a5
@@ -4320,6 +4320,33 @@
 becomes the new default branch of the workspace (even if you also
 specify an explicit @option{--revision} argument).
 
address@hidden mtn pluck address@hidden
address@hidden mtn pluck address@hidden address@hidden
+
+This command takes changes made at any point in history, and attempts
+to edit your current workspace to include those changes.  The end
+result is identical to 'mtn diff -r FROM -r TO | patch -p0', except
+that this command uses monotone's merger, and thus intelligently
+handles renames, conflicts, and so on.
+
+If only one revision is given, applies the changes made in @var{to} as
+compared to @var{to}'s parent.  If two revisions are given, applies
+the changes made to get from @var{from} to @var{to}.
+
+Note that this is not a true cherrypick operation.  A true cherrypick,
+as that word is used in version control theory, involves applying some
+changes out of context, and then recording the identity between the
+original changes and the newly applied changes for the use of later
+merges.  This command does the first part, not the second.  As far as
+monotone is concerned, the changes made by @command{mtn pluck} are
+exactly like those made in an editor; the command is simply a
+convenient way to make certain edits quickly.  In practice, this is
+rarely a problem.  @command{mtn pluck} should almost always be used
+between branches that will never be merged --- for instance,
+backporting fixes from a development branch to a stable branch.  It is
+not recommended to rely on this command as a central part of one's
+workflow.
+
 @item mtn refresh_inodeprints
 This command puts the current workspace into @ref{Inodeprints} mode,
 if it was not already, and forces a full inodeprints cache refresh.