/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to doc/developers/integration.txt

  • Committer: Robert Collins
  • Date: 2010-05-06 11:08:10 UTC
  • mto: This revision was merged to the branch mainline in revision 5223.
  • Revision ID: robertc@robertcollins.net-20100506110810-h3j07fh5gmw54s25
Cleaner matcher matching revised unlocking protocol.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/integration.txt
1
1
=======================
2
 
Integrating with Breezy
 
2
Integrating with Bazaar
3
3
=======================
4
4
 
5
 
This document provides some general observations on integrating with
6
 
Breezy and some recipes for typical tasks.  It is intended to be useful to
7
 
someone developing either a plugin or some other piece of software that
8
 
integrates with bzr.  If you want to know about a topic that's not covered
9
 
here, just ask us.
10
 
 
11
 
 
12
 
 
13
 
 
14
 
Starting with breezy
15
 
====================
16
 
 
17
 
Within bzr
18
 
----------
19
 
 
20
 
When using breezy within the ``bzr`` program (for instance as a bzr
21
 
plugin), breezy's global state is already available for use.
22
 
 
23
 
From outside bzr
24
 
----------------
25
 
 
26
 
To use breezy outside of ``bzr`` some global state needs to be setup.
27
 
breezy needs ways to handle user input, passwords, a place to emit
28
 
progress bars, logging setup appropriately for your program. The easiest
29
 
way to set all this up in the same fashion ``bzr`` does is to call
30
 
``breezy.initialize``. 
31
 
 
32
 
This returns a context manager within which breezy functions will work
33
 
correctly. See the pydoc for ``breezy.initialize`` for more information. 
34
 
(You can get away without entering the context manager, because the setup
35
 
work happens directly from ``initialize``.)
36
 
 
37
 
In Python 2.4 the ``with`` keyword is not supported and
38
 
so you need to use the context manager manually::
39
 
 
40
 
  # This sets up your ~/.bzr.log, ui factory and so on and so forth. It is
41
 
  # not safe to use as a doctest.
42
 
  library_state = breezy.initialize()
43
 
  library_state.__enter__()
44
 
  try:
45
 
      pass
46
 
      # do stuff here
47
 
  finally:
48
 
      library_state.__exit__(None, None, None)
49
 
 
50
 
 
51
 
Running bzr commands
52
 
====================
53
 
 
54
 
To run command-line commands in-process::
55
 
 
56
 
  from breezy.commands import get_command
57
 
  
58
 
  cmd = get_command('version')
59
 
  cmd.run([])
60
 
  
61
 
This will send output through the current UIFactory; you can redirect this
62
 
elsewhere through the parameters to `breezy.initialize`.
63
 
 
 
5
This page should hopefully become a quick guide to integrating other
 
6
(Python-based) software with Bazaar.
64
7
 
65
8
Manipulating the Working Tree
66
9
=============================
67
 
Most objects in Breezy are in files, named after the class they contain.
 
10
Most objects in Bazaar are in files, named after the class they contain.
68
11
To manipulate the Working Tree we need a valid WorkingTree object, which
69
12
is loaded from the workingtree.py file, eg::
70
13
 
71
 
  from breezy import workingtree
 
14
  from bzrlib import workingtree
72
15
  wt = workingtree.WorkingTree.open('/home/jebw/bzrtest')
73
16
 
74
17
 
75
18
This gives us a WorkingTree object, which has various methods spread over
76
 
itself, and its parent classes MutableTree and Tree - it's worth having a
 
19
itself, and its parent classes MutableTree and Tree - its worth having a
77
20
look through these three files (workingtree.py, mutabletree.py and tree.py)
78
21
to see which methods are available.
79
22
 
80
23
Compare trees
81
 
-------------
82
 
 
 
24
===============
83
25
There are two methods for comparing trees: ``changes_from`` and
84
26
``iter_changes``.  ``iter_changes`` is more regular and precise, but it is
85
27
somewhat harder to work with.  See the API documentation for more details.
86
28
 
87
29
``changes_from`` creates a Delta object showing changes::
88
30
 
89
 
  from breezy import delta
 
31
  from bzrlib import delta
90
32
  changes = wt.changes_from(wt.basis_tree())
91
33
 
92
34
This gives us a Delta object, which has several lists of files for each type of
112
54
 
113
55
 
114
56
Adding Files
115
 
------------
 
57
============
116
58
 
117
59
If you want to add files the same way ``bzr add`` does, you can use
118
60
MutableTree.smart_add.  By default, this is recursive. Paths can either be
128
70
 
129
71
 
130
72
Removing Files
131
 
--------------
 
73
==============
132
74
 
133
75
You can remove multiple files at once.  The file paths need to be relative
134
76
to the workingtree::
143
85
 
144
86
 
145
87
Renaming a File
146
 
---------------
 
88
===============
147
89
 
148
90
You can rename one file to a different name using WorkingTree.rename_one.
149
91
You just provide the old and new names, eg::
152
94
 
153
95
 
154
96
Moving Files
155
 
------------
 
97
============
156
98
 
157
99
You can move multiple files from one directory into another using
158
100
WorkingTree.move::
165
107
 
166
108
 
167
109
Committing Changes
168
 
------------------
 
110
==================
169
111
 
170
112
To commit _all_ the changes to our working tree we can just call the
171
113
WorkingTree's commit method, giving it a commit message, eg::
186
128
Generating a log is, in itself, simple.  Grab a branch (see below) and pass
187
129
it to show_log together with a log formatter, eg::
188
130
 
189
 
  from breezy import log
190
 
  from breezy import branch
 
131
  from bzrlib import log
 
132
  from bzrlib import branch
191
133
 
192
134
  b = branch.Branch.open('/path/to/bazaar/branch')
193
135
  lf = log.LongLogFormatter(to_file=sys.stdout)
194
136
  log.show_log(b, lf)
195
137
 
196
138
 
197
 
Three log formatters are included with breezy: LongLogFormatter,
 
139
Three log formatters are included with bzrlib: LongLogFormatter,
198
140
ShortLogFormatter and LineLogFormatter.  These provide long, short and
199
141
single-line log output formats. It's also possible to write your own in
200
142
very little code.
239
181
 
240
182
To work with a branch you need a branch object, created from your branch::
241
183
 
242
 
  from breezy import branch
 
184
  from bzrlib import branch
243
185
 
244
186
  b = branch.Branch.open('/home/jebw/bzrtest')
245
187
 
246
188
 
247
189
Branching from an existing branch
248
 
---------------------------------
 
190
=================================
249
191
 
250
192
To branch you create a branch object representing the branch you are
251
193
branching from, and supply a path/url to the new branch location.
252
 
The following code clones the bzr.dev branch (the latest copy of the Breezy
 
194
The following code clones the bzr.dev branch (the latest copy of the Bazaar
253
195
source code) - be warned it has to download 60meg so takes a while to run
254
196
with no feedback::
255
197
 
256
 
  from breezy import branch
 
198
  from bzrlib import branch
257
199
 
258
200
  b = branch.Branch.open('http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev')
259
 
  nb = b.controldir.sprout('/tmp/newBzrBranch').open_branch()
260
 
 
261
 
 
262
 
This provides no feedback, since Breezy automatically uses the 'silent' UI.
 
201
  nb = b.bzrdir.sprout('/tmp/newBzrBranch').open_branch()
 
202
 
 
203
 
 
204
This provides no feedback, since Bazaar automatically uses the 'silent' UI.
263
205
 
264
206
 
265
207
Pushing and pulling branches
266
 
----------------------------
 
208
============================
267
209
 
268
210
To push a branch you need to open the source and destination branches, then
269
211
just call push with the other branch as a parameter::
270
212
 
271
 
  from breezy import branch
 
213
  from bzrlib import branch
272
214
 
273
215
  b1 = branch.Branch.open('file:///home/user/mybranch')
274
216
  b2 = branch.Branch.open('http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev')
292
234
 
293
235
This performs a Lightweight checkout from an existing Branch::
294
236
 
295
 
  from breezy import bzrdir
 
237
  from bzrlib import bzrdir
296
238
 
297
239
  accelerator_tree, source = bzrdir.BzrDir.open_tree_or_branch('http:URL')
298
240
  source.create_checkout('/tmp/newBzrCheckout', None, True, accelerator_tree)