Rev 3107: cherrypicking/rebasing section for User Guide in file:///home/pqm/archives/thelove/bzr/%2Btrunk/
Canonical.com Patch Queue Manager
pqm at pqm.ubuntu.com
Thu Dec 13 14:10:53 GMT 2007
At file:///home/pqm/archives/thelove/bzr/%2Btrunk/
------------------------------------------------------------
revno: 3107
revision-id:pqm at pqm.ubuntu.com-20071213141047-tklbta8rymzfpj6y
parent: pqm at pqm.ubuntu.com-20071213083735-30doieica3xb8tcp
parent: ian.clatworthy at internode.on.net-20071213120621-xankx0juy4l5e9ju
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Thu 2007-12-13 14:10:47 +0000
message:
cherrypicking/rebasing section for User Guide
added:
doc/en/user-guide/adv_merging.txt adv_merging.txt-20071213070245-d7u7150lb2hhnvby-1
modified:
doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2
------------------------------------------------------------
revno: 3106.1.1
revision-id:ian.clatworthy at internode.on.net-20071213120621-xankx0juy4l5e9ju
parent: pqm at pqm.ubuntu.com-20071213083735-30doieica3xb8tcp
parent: ian.clatworthy at internode.on.net-20071213070416-fhr8zsrhn1nhzeop
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: ianc-integration
timestamp: Thu 2007-12-13 22:06:21 +1000
message:
cherrypicking/rebasing section for User Guide
added:
doc/en/user-guide/adv_merging.txt adv_merging.txt-20071213070245-d7u7150lb2hhnvby-1
modified:
doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2
------------------------------------------------------------
revno: 3105.2.1
revision-id:ian.clatworthy at internode.on.net-20071213070416-fhr8zsrhn1nhzeop
parent: pqm at pqm.ubuntu.com-20071213021422-mq0sexod7cz09yd6
committer: Ian Clatworthy <ian.clatworthy at internode.on.net>
branch nick: bzr.ug-advanced
timestamp: Thu 2007-12-13 17:04:16 +1000
message:
Advanced merging section for User Guide
added:
doc/en/user-guide/adv_merging.txt adv_merging.txt-20071213070245-d7u7150lb2hhnvby-1
modified:
doc/en/user-guide/index.txt index.txt-20060622101119-tgwtdci8z769bjb9-2
=== added file 'doc/en/user-guide/adv_merging.txt'
--- a/doc/en/user-guide/adv_merging.txt 1970-01-01 00:00:00 +0000
+++ b/doc/en/user-guide/adv_merging.txt 2007-12-13 07:04:16 +0000
@@ -0,0 +1,116 @@
+Advanced merging
+================
+
+Cherrypicking
+-------------
+
+At times, it can be useful to selectively merge some of the changes
+in a branch, but not all of them. This is commonly referred to as
+*cherrypicking*. Here are some examples of where cherrypicking is
+useful:
+
+* selectively taking fixes from the main development branch into
+ a release branch
+
+* selectively taking improvements out of an experimental branch into
+ a feature branch.
+
+To merge only the changes made by revision X in branch ``foo``,
+the command is::
+
+ bzr merge -c X foo
+
+To merge only the changes up to revision X in branch ``foo``,
+the command is::
+
+ bzr merge -r X foo
+
+To merge only the changes since revision X in branch ``foo``,
+the command is::
+
+ bzr merge -r X.. foo
+
+To merge only the changes from revision X to revision Y in branch ``foo``,
+the command is::
+
+ bzr merge -r X..Y foo
+
+Like a normal merge, you must explicitly commit a cherrypick. You may wish
+to see the changes made using ``bzr diff``, and run your test suite if any,
+before doing this.
+
+Unlike a normal merge, Bazaar does not currently track cherrypicks.
+In particular, the changes look like a normal commit and the (internal)
+revision history of the changes from the other branch is lost.
+In many cases where they are useful (see above), this is not a major
+problem because there are good reasons why a full merge should never
+be done at a later time. In other cases, additional conflicts will need
+to be resolved when the changes are merged again.
+
+Note: The reason why Bazaar doesn't track cherrypicks yet is that doing so
+can lead to poor performance. We are exploring ways of tracking
+this information that perform acceptably and hope to improve Bazaar's
+cherrypicking support in the future accordingly.
+
+
+Reverse cherrypicking
+---------------------
+
+Cherrypicking can be used to reverse a set of changes made by giving an
+upper bound in the revision range which is *below* the lower bound.
+For example, to back-out changes made in revision 10, the command is::
+
+ bzr merge -r 10..9
+
+If you want to take most changes, but not all, from somewhere else, you
+may wish to do a normal merge followed by a few reverse cherrypicks.
+
+
+Merging uncommitted changes
+---------------------------
+
+If you have several branches and you accidently start making changes in the
+wrong one, here are the steps to take to correct this. Assuming you began
+working in branch ``foo`` when you meant to work in branch ``bar``:
+
+1. Change into branch ``bar``.
+2. Run ``bzr merge --uncommitted foo``
+3. Check the changes came across (``bzr diff``)
+4. Change into branch ``foo``
+5. Run ``bzr revert``.
+
+.. TODO Selective file merging?
+
+
+Rebasing
+--------
+
+Another option to normal merging is *rebasing*, i.e. making it look like
+the current branch originated from a different point than it did.
+Rebasing is supported in Bazaar by the ``rebase`` command provided by
+the ``rebase`` plugin.
+
+The ``rebase`` command takes the location of another branch on which
+the branch in the current working directory will be rebased. If a branch
+is not specified then the parent branch is used, and this is usually the
+desired result.
+
+The first step identifies the revisions that are in the current branch
+that are not in the parent branch. The current branch is then set to be
+at the same revision as the target branch, and each revision is replayed
+on top of the branch. At the end of the process it will appear as though
+your current branch was branched off the current last revision of the target.
+
+Each revision that is replayed may cause conflicts in the tree. If this
+happens the command will stop and allow you to fix them up. Resolve the
+commits as you would for a ``merge``, and then run ``bzr resolve`` to
+marked them as resolved. Once you have resolved all the conflicts, you
+should run ``bzr rebase-continue`` to continue the rebase operation.
+If conflicts are encountered and you decide not to continue,
+you can run ``bzr rebase-abort``. You can also use ``rebase-todo`` to
+show the list of commits still to be replayed.
+
+Note: Some users coming from central VCS tools with poor merge tracking
+like rebasing because it's similar to how they are use to working in older
+tools, or because "perfectly clean" history seems important. Before rebasing
+in Bazaar, think about whether a normal merge is a better choice.
=== modified file 'doc/en/user-guide/index.txt'
--- a/doc/en/user-guide/index.txt 2007-12-13 01:28:03 +0000
+++ b/doc/en/user-guide/index.txt 2007-12-13 12:06:21 +0000
@@ -79,6 +79,7 @@
##############
.. include:: best_practice_intro.txt
+.. include:: adv_merging.txt
.. include:: server.txt
.. include:: hooks.txt
.. include:: version_info.txt
More information about the bazaar-commits
mailing list