← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/user-guide/adv_merging.txt

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2007-12-13 14:10:47 UTC
  • mfrom: (3106.1.1 ianc-integration)
  • Revision ID: pqm@pqm.ubuntu.com-20071213141047-tklbta8rymzfpj6y
cherrypicking/rebasing section for User Guide

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/adv_merging.txt
 
1
Advanced merging
 
2
================
 
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
Note: The reason why Bazaar doesn't track cherrypicks yet is that doing so
 
51
can lead to poor performance. We are exploring ways of tracking
 
52
this information that perform acceptably and hope to improve Bazaar's
 
53
cherrypicking support in the future accordingly.
 
54
 
 
55
 
 
56
Reverse cherrypicking
 
57
---------------------
 
58
 
 
59
Cherrypicking can be used to reverse a set of changes made by giving an
 
60
upper bound in the revision range which is *below* the lower bound.
 
61
For example, to back-out changes made in revision 10, the command is::
 
62
 
 
63
  bzr merge -r 10..9
 
64
 
 
65
If you want to take most changes, but not all, from somewhere else, you
 
66
may wish to do a normal merge followed by a few reverse cherrypicks.
 
67
 
 
68
 
 
69
Merging uncommitted changes
 
70
---------------------------
 
71
 
 
72
If you have several branches and you accidently start making changes in the
 
73
wrong one, here are the steps to take to correct this. Assuming you began
 
74
working in branch ``foo`` when you meant to work in branch ``bar``:
 
75
 
 
76
1. Change into branch ``bar``.
 
77
2. Run ``bzr merge --uncommitted foo``
 
78
3. Check the changes came across (``bzr diff``)
 
79
4. Change into branch ``foo``
 
80
5. Run ``bzr revert``.
 
81
 
 
82
.. TODO Selective file merging?
 
83
 
 
84
 
 
85
Rebasing
 
86
--------
 
87
 
 
88
Another option to normal merging is *rebasing*, i.e. making it look like
 
89
the current branch originated from a different point than it did.
 
90
Rebasing is supported in Bazaar by the ``rebase`` command provided by
 
91
the ``rebase`` plugin.
 
92
 
 
93
The ``rebase`` command takes the location of another branch on which
 
94
the branch in the current working directory will be rebased. If a branch
 
95
is not specified then the parent branch is used, and this is usually the
 
96
desired result.
 
97
 
 
98
The first step identifies the revisions that are in the current branch
 
99
that are not in the parent branch. The current branch is then set to be
 
100
at the same revision as the target branch, and each revision is replayed
 
101
on top of the branch. At the end of the process it will appear as though
 
102
your current branch was branched off the current last revision of the target.
 
103
 
 
104
Each revision that is replayed may cause conflicts in the tree. If this
 
105
happens the command will stop and allow you to fix them up. Resolve the
 
106
commits as you would for a ``merge``, and then run ``bzr resolve`` to
 
107
marked them as resolved. Once you have resolved all the conflicts, you
 
108
should run ``bzr rebase-continue`` to continue the rebase operation.
 
109
If conflicts are encountered and you decide not to continue,
 
110
you can run ``bzr rebase-abort``. You can also use ``rebase-todo`` to
 
111
show the list of commits still to be replayed.
 
112
 
 
113
Note: Some users coming from central VCS tools with poor merge tracking
 
114
like rebasing because it's similar to how they are use to working in older
 
115
tools, or because "perfectly clean" history seems important. Before rebasing
 
116
in Bazaar, think about whether a normal merge is a better choice.