← 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

(vila) Fix test failures blocking package builds. (Vincent Ladeuil)

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/adv_merging.txt
 
1
Pseudo 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
Merging without parents
 
51
-----------------------
 
52
 
 
53
A related technique to cherrypicking, in that it makes changes without
 
54
reference to the revisions that they came from is to perform a merge, but
 
55
forget about the parent revisions before committing.  This has the effect of
 
56
making all of the changes that would have been in the merge happen in a single
 
57
commit.  After the merge and before the corresponding commit, you can do::
 
58
 
 
59
  bzr revert --forget-merges
 
60
 
 
61
to keep the changes in the working tree, but remove the record of the
 
62
revisions where the changes originated.  The next commit would then record
 
63
all of those changes without any record of the merged revisions.
 
64
 
 
65
This is desired by some users to make their history "cleaner", but you should
 
66
be careful that the loss of history does not outweigh the value of cleanliness,
 
67
particularly given Bazaar's capabilities for progressively disclosing merged
 
68
revisions.  In particular, because this will include the changes from the
 
69
source branch, but without attribution to that branch, it can lead to
 
70
additional conflicts on later merges that involve the same source and
 
71
target branches.
 
72
 
 
73
 
 
74
Reverse cherrypicking
 
75
---------------------
 
76
 
 
77
Cherrypicking can be used to reverse a set of changes made by giving an
 
78
upper bound in the revision range which is *below* the lower bound.
 
79
For example, to back-out changes made in revision 10, the command is::
 
80
 
 
81
  bzr merge -r 10..9
 
82
 
 
83
If you want to take most changes, but not all, from somewhere else, you
 
84
may wish to do a normal merge followed by a few reverse cherrypicks.
 
85
 
 
86
 
 
87
Merging uncommitted changes
 
88
---------------------------
 
89
 
 
90
If you have several branches and you accidentally start making changes in the
 
91
wrong one, here are the steps to take to correct this. Assuming you began
 
92
working in branch ``foo`` when you meant to work in branch ``bar``:
 
93
 
 
94
1. Change into branch ``bar``.
 
95
2. Run ``bzr merge --uncommitted foo``
 
96
3. Check the changes came across (``bzr diff``)
 
97
4. Change into branch ``foo``
 
98
5. Run ``bzr revert``.
 
99
 
 
100
.. TODO Selective file merging?
 
101
 
 
102
 
 
103
Rebasing
 
104
--------
 
105
 
 
106
Another option to normal merging is *rebasing*, i.e. making it look like
 
107
the current branch originated from a different point than it did.
 
108
Rebasing is supported in Bazaar by the ``rebase`` command provided by
 
109
the ``rebase`` plugin.
 
110
 
 
111
The ``rebase`` command takes the location of another branch on which
 
112
the branch in the current working directory will be rebased. If a branch
 
113
is not specified then the parent branch is used, and this is usually the
 
114
desired result.
 
115
 
 
116
The first step identifies the revisions that are in the current branch
 
117
that are not in the parent branch. The current branch is then set to be
 
118
at the same revision as the target branch, and each revision is replayed
 
119
on top of the branch. At the end of the process it will appear as though
 
120
your current branch was branched off the current last revision of the target.
 
121
 
 
122
Each revision that is replayed may cause conflicts in the tree. If this
 
123
happens the command will stop and allow you to fix them up. Resolve the
 
124
commits as you would for a ``merge``, and then run ``bzr resolve`` to
 
125
marked them as resolved. Once you have resolved all the conflicts, you
 
126
should run ``bzr rebase-continue`` to continue the rebase operation.
 
127
If conflicts are encountered and you decide not to continue,
 
128
you can run ``bzr rebase-abort``. You can also use ``rebase-todo`` to
 
129
show the list of commits still to be replayed.
 
130
 
 
131
Note: Some users coming from central VCS tools with poor merge tracking
 
132
like rebasing because it's similar to how they are use to working in older
 
133
tools, or because "perfectly clean" history seems important. Before rebasing
 
134
in Bazaar, think about whether a normal merge is a better choice. In
 
135
particular, rebasing a private branch before sharing it is OK but
 
136
rebasing after sharing a branch with someone else is **strongly** discouraged.