Rev 4843: Including a discussion of revert --forget-merges as a tool for in file:///home/pqm/archives/thelove/bzr/%2Btrunk/

[Canonical.com Patch Queue Manager]

At file:///home/pqm/archives/thelove/bzr/%2Btrunk/

------------------------------------------------------------
revno: 4843 [merge]
revision-id: pqm at pqm.ubuntu.com-20091201001004-vflb5bqsnrlkfh7p
parent: pqm at pqm.ubuntu.com-20091130220445-vbfmmgocbgcs195q
parent: nmb at wartburg.edu-20091125160457-56y1yl8iw4y9q4x8
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Tue 2009-12-01 00:10:04 +0000
message:
  Including a discussion of revert --forget-merges as a tool for
  	advanced merging. (Neil Martinsen-Burrell, #190096)
modified:
  bzrlib/builtins.py             builtins.py-20050830033751-fc01482b9ca23183
  doc/en/user-guide/adv_merging.txt adv_merging.txt-20071213070245-d7u7150lb2hhnvby-1
=== modified file 'bzrlib/builtins.py'
--- a/bzrlib/builtins.py	2009-11-30 22:04:45 +0000
+++ b/bzrlib/builtins.py	2009-12-01 00:10:04 +0000
@@ -4085,6 +4085,16 @@
     revert ." in the tree root to revert all files but keep the merge record,
     and "bzr revert --forget-merges" to clear the pending merge list without
     reverting any files.
+
+    Using "bzr revert --forget-merges", it is possible to apply the changes
+    from an arbitrary merge as a single revision.  To do this, perform the
+    merge as desired.  Then doing revert with the "--forget-merges" option will
+    keep the content of the tree as it was, but it will clear the list of
+    pending merges.  The next commit will then contain all of the changes that
+    would have been in the merge, but without any mention of the other parent
+    revisions.  Because this technique forgets where these changes originated,
+    it may cause additional conflicts on later merges involving the source and
+    target branches.
     """
 
     _see_also = ['cat', 'export']

=== modified file 'doc/en/user-guide/adv_merging.txt'
--- a/doc/en/user-guide/adv_merging.txt	2009-04-04 02:50:01 +0000
+++ b/doc/en/user-guide/adv_merging.txt	2009-11-25 16:04:57 +0000
@@ -47,6 +47,29 @@
 be done at a later time. In other cases, additional conflicts will need
 to be resolved when the changes are merged again.
 
+Merging without parents
+-----------------------
+
+A related technique to cherrypicking, in that it makes changes without
+reference to the revisions that they came from is to perform a merge, but
+forget about the parent revisions before committing.  This has the effect of
+making all of the changes that would have been in the merge happen in a single
+commit.  After the merge and before the corresponding commit, you can do::
+
+  bzr revert --forget-merges
+
+to keep the changes in the working tree, but remove the record of the
+revisions where the changes originated.  The next commit would then record
+all of those changes without any record of the merged revisions.
+
+This is desired by some users to make their history "cleaner", but you should
+be careful that the loss of history does not outweigh the value of cleanliness,
+particularly given Bazaar's capabilities for progressively disclosing merged
+revisions.  In particular, because this will include the changes from the
+source branch, but without attribution to that branch, it can lead to
+additional conflicts on later merges that involve the same source and
+target branches.
+
 
 Reverse cherrypicking
 ---------------------