|
4416.4.1
by Neil Martinsen-Burrell
Fix 269477 Add documentation about diverged branches and refer to it when pushing fails |
1 |
Diverged Branches |
2 |
================= |
|
3 |
||
4 |
When Bazaar tries to push one branch onto another, it requires that the |
|
5 |
destination branch must be ready to receive the source branch. If this isn't |
|
6 |
the case, then we say that the branches have ``diverged``. Branches are |
|
7 |
considered diverged if the destination branch's most recent commit is one that |
|
8 |
has not been merged (directly or indirectly) by the source branch. To recover |
|
9 |
from diverged branches, one must merge the missing revisions into the source |
|
10 |
branch. |
|
11 |
||
12 |
This situation commonly arises when using a centralized workflow with local |
|
13 |
commits. If someone else has committed new work to the mainline since your |
|
14 |
last pull and you have local commits that have not yet been pushed to the |
|
15 |
mainline, then your local branch and the mainline have diverged. |
|
16 |
||
17 |
Discovering What Has Diverged |
|
18 |
----------------------------- |
|
19 |
||
20 |
The ``bzr missing`` command is used to find out what revisions are in another |
|
21 |
branch that are not present in the current branch, and vice-versa. It shows a |
|
22 |
summary of which extra revisions exist in each branch. If you want to see the |
|
23 |
precise effects of those revisions, you can use ``bzr diff --old=other_branch`` |
|
24 |
to show the differences between other_branch and your current branch. |
|
25 |
||
26 |
A Solution |
|
27 |
---------- |
|
28 |
||
29 |
The solution is to merge the revisions from the mainline into your local |
|
30 |
branch. To do so, use ``bzr merge`` to get the new revisions from the |
|
31 |
mainline. This merge may result in conflicts if the other developer's changes |
|
32 |
overlap with your changes. These conflicts should be resolved before |
|
33 |
continuing. After any conflicts have been resolved, or even if there were no |
|
34 |
conflicts, Bazaar requires that you explicitly commit these new revisions |
|
35 |
to your local branch. This requirement gives you an opportunity to test the |
|
36 |
resulting working tree for correctness, since the merged revisions could have |
|
37 |
made arbitrary changes. After testing, you should commit the merge using |
|
38 |
``bzr commit``. This clears up the diverged branches situation. Your local |
|
39 |
branch can now be pushed to the mainline. |