← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

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

Rather use assertRaises in test_changes_from_with_require_versioned

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/user-guide/sending_changes.txt
1
 
Sending changes
2
 
===============
3
 
 
4
 
Motivation
5
 
----------
6
 
 
7
 
In many distributed development scenarios, it isn't always feasible for
8
 
developers to share task branches by advertising their URLs.
9
 
For example, a developer working on a laptop might take it home overnight
10
 
so his/her task branches could well be inaccessible when a gatekeeper
11
 
in another timezone wants to review or merge it.
12
 
 
13
 
Bazaar provides a neat feature to assist here: *merge directives*.
14
 
 
15
 
Understanding merge directives
16
 
------------------------------
17
 
 
18
 
You can think of a merge directive as a "mini branch" - just the
19
 
new growth on a branch since it was created. It's a software
20
 
patch showing what's new but with added intelligence: metadata
21
 
like interim commits, renames and digital signatures.
22
 
 
23
 
Another useful metaphor is a packet cake: a merge directive has a recipe
24
 
together with the ingredients you need bundled inside it.
25
 
To stretch the metaphor, the ingredients are all the metadata on the
26
 
changes made to the branch; the recipe is instructions on how those
27
 
changes ought to be merged, i.e. information for the ``merge`` command
28
 
to use in selecting common ancestors.
29
 
 
30
 
Regardless of how you think of them, merge directives are neat.
31
 
They are easy to create, suitable for mailing around as attachments
32
 
and can be processed much like branches can on the receiving end.
33
 
 
34
 
Creating a merge directive
35
 
--------------------------
36
 
 
37
 
To create a merge directive, use the ``send`` command. For example,
38
 
this command creates a merge directive and saves it into the
39
 
nominated output file::
40
 
 
41
 
  cd X-fix-123
42
 
  bzr send -o ../fix-123.patch
43
 
 
44
 
That file can then be emailed to a reviewer, together with an
45
 
explanation of how and why you fixed the problem the way you did, say.
46
 
 
47
 
Emailing merge directives is such a common thing that the ``send`` command
48
 
without options will create a merge directive, fire up your email
49
 
tool and attach it, ready for you to add the explanatory text bit.
50
 
See the online help for ``send`` and
51
 
`Configuration Settings <../user-reference/bzr_man.html#configuration-settings>`_
52
 
in the User Reference for further details on how to configure this.
53
 
 
54
 
Applying a merge directive
55
 
--------------------------
56
 
 
57
 
Merge directives can be applied in much the same way as branches: by
58
 
using the ``merge`` and ``pull`` commands.
59
 
 
60
 
They can also be useful when communicating with upstream projects
61
 
that don't use Bazaar. In particular, the preview of the overall
62
 
change in a merge directive looks like a vanilla software patch, so
63
 
they can be applied using ``patch -p0`` for example.