← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

  • Committer: Aaron Bentley
  • Date: 2005-07-26 14:06:11 UTC
  • mto: (1092.1.41) (1185.3.4) (974.1.47)
  • mto: This revision was merged to the branch mainline in revision 982.
  • Revision ID: abentley@panoramicfeedback.com-20050726140611-403e366f3c79c1f1
Fixed python invocation

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/merging_changes.txt
1
 
Merging changes
2
 
===============
3
 
 
4
 
Parallel development
5
 
--------------------
6
 
 
7
 
Once someone has their own branch of a project, they can make
8
 
and commit changes in parallel to any development proceeding
9
 
on the original branch. Pretty soon though, these independent
10
 
lines of development will need to be combined again. This
11
 
process is known as *merging*.
12
 
 
13
 
The merge command
14
 
-----------------
15
 
 
16
 
To incorporate changes from another branch, use the ``merge`` command.
17
 
Its syntax is::
18
 
 
19
 
  bzr merge [URL]
20
 
 
21
 
If no URL is given, a default is used, initially the branch this branch
22
 
originated from.
23
 
For example, if Bill made a branch from Mary's work, he can merge her
24
 
subsequent changes by simply typing this::
25
 
 
26
 
  bzr merge
27
 
 
28
 
On the other hand, Mary might want to merge into her branch the work Bill
29
 
has done in his. In this case, she needs to explicitly give the URL the
30
 
first time, e.g.::
31
 
 
32
 
  bzr merge bzr+ssh://mary@bill-laptop/cool-repo/cool-trunk
33
 
 
34
 
This sets the default merge branch if one is not already set.  Use
35
 
``--no-remember`` to avoid setting it. To change the default after it is set,
36
 
use the ``--remember`` option.
37
 
 
38
 
How does merging work?
39
 
----------------------
40
 
 
41
 
A variety of algorithms exist for merging changes. Bazaar's
42
 
default algorithm is a variation of *3-way merging* which
43
 
works as follows. Given an ancestor A and two branches B and C,
44
 
the following table provides the rules used.
45
 
 
46
 
  === === === ====== =================
47
 
   A   B   C  Result Comment
48
 
  === === === ====== =================
49
 
   x   x   x  x      unchanged
50
 
   x   x   y  y      line from C
51
 
   x   y   x  y      line from B
52
 
   x   y   z  ?      conflict
53
 
  === === === ====== =================
54
 
 
55
 
Note that some merges can only be completed with the assistance
56
 
of a human. Details on how to resolve these are given in
57
 
`Resolving conflicts <resolving_conflicts.html>`_.
58
 
 
59
 
Recording a merge
60
 
-----------------
61
 
 
62
 
After any conflicts are resolved, the merge needs to be committed.
63
 
For example::
64
 
 
65
 
  bzr commit -m "Merged Mary's changes"
66
 
 
67
 
Even if there are no conflicts, an explicit commit is still required.
68
 
Unlike some other tools, this is considered a feature in Bazaar.
69
 
A clean merge is not necessarily a good merge so making the commit
70
 
a separate explicit step allows you to run your test suite first to
71
 
verify all is good. If problems are found, you should correct them
72
 
before committing the merge or throw the merge away using ``revert``.
73
 
 
74
 
Merge tracking
75
 
--------------
76
 
 
77
 
One of the most important features of Bazaar is distributed,
78
 
high quality *merge tracking*.
79
 
In other words, Bazaar remembers what has been merged already and
80
 
uses that information to intelligently choose the best ancestor for
81
 
a merge, minimizing the number and size of conflicts.
82
 
 
83
 
If you are a refugee from many other VCS tools, it can be really
84
 
hard to "unlearn" the *please-let-me-avoid-merging-at-any-cost* habit.
85
 
Bazaar lets you safely merge as often as you like with other people.
86
 
By working in a peer-to-peer manner when it makes sense to do so, you
87
 
also avoid using a central branch as an "integration swamp", keeping
88
 
its quality higher. When the change you're collaborating on is
89
 
truly ready for wider sharing, that's the time to merge and commit
90
 
it to a central branch, not before.
91
 
 
92
 
Merging that Just Works truly can change how developers work together.