← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/integration.txt

  • Committer: Aaron Bentley
  • Date: 2008-08-29 18:35:50 UTC
  • mto: This revision was merged to the branch mainline in revision 3678.
  • Revision ID: aaron@aaronbentley.com-20080829183550-8ia9bn0nsfr4ykl2
Update NEWS

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/integration.txt
2
2
Integrating with Bazaar
3
3
=======================
4
4
 
5
 
This document provides some general observations on integrating with
6
 
Bazaar 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 bzrlib
15
 
====================
16
 
 
17
 
Within bzr
18
 
----------
19
 
 
20
 
When using bzrlib within the ``bzr`` program (for instance as a bzr
21
 
plugin), bzrlib's global state is already available for use.
22
 
 
23
 
From outside bzr
24
 
----------------
25
 
 
26
 
To use bzrlib outside of ``bzr`` some global state needs to be setup.
27
 
bzrlib 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
 
``bzrlib.initialize``. 
31
 
 
32
 
This returns a context manager within which bzrlib functions will work
33
 
correctly. See the pydoc for ``bzrlib.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 = bzrlib.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 bzrlib.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 `bzrlib.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
=============================
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.
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::
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.
255
197
 
256
198
  from bzrlib import branch
257
199
 
258
 
  b = branch.Branch.open('http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev')
 
200
  b = branch.Branch.open('http://bazaar-vcs.org/bzr/bzr.dev')
259
201
  nb = b.bzrdir.sprout('/tmp/newBzrBranch').open_branch()
260
202
 
261
203
 
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::
271
213
  from bzrlib import branch
272
214
 
273
215
  b1 = branch.Branch.open('file:///home/user/mybranch')
274
 
  b2 = branch.Branch.open('http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev')
 
216
  b2 = branch.Branch.open('http://bazaar-vcs.org/bzr/bzr.dev')
275
217
  b1.push(b2)
276
218
 
277
219
 
302
244
 
303
245
  source.create_checkout('/tmp/newBzrCheckout', None, False, accelerator_tree
304
246
 
305
 
 
 
247
==================
306
248
History Operations
307
249
==================
308
250
 
309
251
Finding the last revision number or id
310
 
--------------------------------------
 
252
======================================
311
253
 
312
254
To get the last revision number and id of a branch use::
313
255
 
321
263
 
322
264
 
323
265
Getting the list of revision ids that make up a branch
324
 
------------------------------------------------------
 
266
======================================================
325
267
 
326
268
IMPORTANT: This should be avoided wherever possible, as it scales with the
327
269
length of history::
335
277
 
336
278
 
337
279
Getting a Revision object from a revision id
338
 
--------------------------------------------
 
280
============================================
339
281
 
340
282
The Revision object has attributes like "message" to get the information
341
283
about the revision::
345
287
 
346
288
 
347
289
Accessing the files from a revision
348
 
-----------------------------------
 
290
===================================
349
291
 
350
292
To get the file contents and tree shape for a specific revision you need
351
293
a RevisionTree. These are supplied by the repository for a specific