|
3053.9.1
by Ian Clatworthy
Doc tweaks from David Roberts and Aaron Bentley for 1.0 (Ian Clatworthy) |
1 |
Pseudo merging |
2 |
============== |
|
|
3105.2.1
by Ian Clatworthy
Advanced merging section for User Guide |
3 |
|
4 |
Cherrypicking |
|
5 |
------------- |
|
6 |
||
7 |
At times, it can be useful to selectively merge some of the changes |
|
8 |
in a branch, but not all of them. This is commonly referred to as |
|
9 |
*cherrypicking*. Here are some examples of where cherrypicking is |
|
10 |
useful: |
|
11 |
||
12 |
* selectively taking fixes from the main development branch into |
|
13 |
a release branch |
|
14 |
||
15 |
* selectively taking improvements out of an experimental branch into |
|
16 |
a feature branch. |
|
17 |
||
18 |
To merge only the changes made by revision X in branch ``foo``, |
|
19 |
the command is:: |
|
20 |
||
21 |
bzr merge -c X foo |
|
22 |
||
23 |
To merge only the changes up to revision X in branch ``foo``, |
|
24 |
the command is:: |
|
25 |
||
26 |
bzr merge -r X foo |
|
27 |
||
28 |
To merge only the changes since revision X in branch ``foo``, |
|
29 |
the command is:: |
|
30 |
||
31 |
bzr merge -r X.. foo |
|
32 |
||
33 |
To merge only the changes from revision X to revision Y in branch ``foo``, |
|
34 |
the command is:: |
|
35 |
||
36 |
bzr merge -r X..Y foo |
|
37 |
||
38 |
Like a normal merge, you must explicitly commit a cherrypick. You may wish |
|
39 |
to see the changes made using ``bzr diff``, and run your test suite if any, |
|
40 |
before doing this. |
|
41 |
||
42 |
Unlike a normal merge, Bazaar does not currently track cherrypicks. |
|
43 |
In particular, the changes look like a normal commit and the (internal) |
|
44 |
revision history of the changes from the other branch is lost. |
|
45 |
In many cases where they are useful (see above), this is not a major |
|
46 |
problem because there are good reasons why a full merge should never |
|
47 |
be done at a later time. In other cases, additional conflicts will need |
|
48 |
to be resolved when the changes are merged again. |
|
49 |
||
50 |
||
51 |
Reverse cherrypicking |
|
52 |
--------------------- |
|
53 |
||
54 |
Cherrypicking can be used to reverse a set of changes made by giving an |
|
55 |
upper bound in the revision range which is *below* the lower bound. |
|
56 |
For example, to back-out changes made in revision 10, the command is:: |
|
57 |
||
58 |
bzr merge -r 10..9 |
|
59 |
||
60 |
If you want to take most changes, but not all, from somewhere else, you |
|
61 |
may wish to do a normal merge followed by a few reverse cherrypicks. |
|
62 |
||
63 |
||
64 |
Merging uncommitted changes |
|
65 |
--------------------------- |
|
66 |
||
67 |
If you have several branches and you accidently start making changes in the |
|
68 |
wrong one, here are the steps to take to correct this. Assuming you began |
|
69 |
working in branch ``foo`` when you meant to work in branch ``bar``: |
|
70 |
||
71 |
1. Change into branch ``bar``. |
|
72 |
2. Run ``bzr merge --uncommitted foo`` |
|
73 |
3. Check the changes came across (``bzr diff``) |
|
74 |
4. Change into branch ``foo`` |
|
75 |
5. Run ``bzr revert``. |
|
76 |
||
77 |
.. TODO Selective file merging? |
|
78 |
||
79 |
||
80 |
Rebasing |
|
81 |
-------- |
|
82 |
||
83 |
Another option to normal merging is *rebasing*, i.e. making it look like |
|
84 |
the current branch originated from a different point than it did. |
|
85 |
Rebasing is supported in Bazaar by the ``rebase`` command provided by |
|
86 |
the ``rebase`` plugin. |
|
87 |
||
88 |
The ``rebase`` command takes the location of another branch on which |
|
89 |
the branch in the current working directory will be rebased. If a branch |
|
90 |
is not specified then the parent branch is used, and this is usually the |
|
91 |
desired result. |
|
92 |
||
93 |
The first step identifies the revisions that are in the current branch |
|
94 |
that are not in the parent branch. The current branch is then set to be |
|
95 |
at the same revision as the target branch, and each revision is replayed |
|
96 |
on top of the branch. At the end of the process it will appear as though |
|
97 |
your current branch was branched off the current last revision of the target. |
|
98 |
||
99 |
Each revision that is replayed may cause conflicts in the tree. If this |
|
100 |
happens the command will stop and allow you to fix them up. Resolve the |
|
101 |
commits as you would for a ``merge``, and then run ``bzr resolve`` to |
|
102 |
marked them as resolved. Once you have resolved all the conflicts, you |
|
103 |
should run ``bzr rebase-continue`` to continue the rebase operation. |
|
104 |
If conflicts are encountered and you decide not to continue, |
|
105 |
you can run ``bzr rebase-abort``. You can also use ``rebase-todo`` to |
|
106 |
show the list of commits still to be replayed. |
|
107 |
||
108 |
Note: Some users coming from central VCS tools with poor merge tracking |
|
109 |
like rebasing because it's similar to how they are use to working in older |
|
110 |
tools, or because "perfectly clean" history seems important. Before rebasing |
|
|
3053.9.1
by Ian Clatworthy
Doc tweaks from David Roberts and Aaron Bentley for 1.0 (Ian Clatworthy) |
111 |
in Bazaar, think about whether a normal merge is a better choice. In |
112 |
particular, rebasing a private branch before sharing it is OK but |
|
113 |
rebasing after sharing a branch with someone else is **strongly** discouraged. |