← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/integration.txt

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2010-09-01 08:02:42 UTC
  • mfrom: (5390.3.3 faster-revert-593560)
  • Revision ID: pqm@pqm.ubuntu.com-20100901080242-esg62ody4frwmy66
(spiv) Avoid repeatedly calling self.target.all_file_ids() in
 InterTree.iter_changes. (Andrew Bennetts)

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 page should hopefully become a quick guide to integrating other
6
 
(Python-based) software with Bazaar.
 
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
Before doing anything else with bzrlib, you should run `bzrlib.initialize`
 
18
which sets up some global state.  
 
19
 
 
20
 
 
21
Running bzr commands
 
22
====================
 
23
 
 
24
To run command-line commands in-process::
 
25
 
 
26
  from bzrlib.commands import get_command
 
27
  
 
28
  cmd = get_command('version')
 
29
  cmd.run([])
 
30
  
 
31
This will send output through the current UIFactory; you can redirect this
 
32
elsewhere through the parameters to `bzrlib.initialize`.
 
33
 
7
34
 
8
35
Manipulating the Working Tree
9
36
=============================
21
48
to see which methods are available.
22
49
 
23
50
Compare trees
24
 
===============
 
51
-------------
 
52
 
25
53
There are two methods for comparing trees: ``changes_from`` and
26
54
``iter_changes``.  ``iter_changes`` is more regular and precise, but it is
27
55
somewhat harder to work with.  See the API documentation for more details.
54
82
 
55
83
 
56
84
Adding Files
57
 
============
 
85
------------
58
86
 
59
87
If you want to add files the same way ``bzr add`` does, you can use
60
88
MutableTree.smart_add.  By default, this is recursive. Paths can either be
70
98
 
71
99
 
72
100
Removing Files
73
 
==============
 
101
--------------
74
102
 
75
103
You can remove multiple files at once.  The file paths need to be relative
76
104
to the workingtree::
85
113
 
86
114
 
87
115
Renaming a File
88
 
===============
 
116
---------------
89
117
 
90
118
You can rename one file to a different name using WorkingTree.rename_one.
91
119
You just provide the old and new names, eg::
94
122
 
95
123
 
96
124
Moving Files
97
 
============
 
125
------------
98
126
 
99
127
You can move multiple files from one directory into another using
100
128
WorkingTree.move::
107
135
 
108
136
 
109
137
Committing Changes
110
 
==================
 
138
------------------
111
139
 
112
140
To commit _all_ the changes to our working tree we can just call the
113
141
WorkingTree's commit method, giving it a commit message, eg::
187
215
 
188
216
 
189
217
Branching from an existing branch
190
 
=================================
 
218
---------------------------------
191
219
 
192
220
To branch you create a branch object representing the branch you are
193
221
branching from, and supply a path/url to the new branch location.
197
225
 
198
226
  from bzrlib import branch
199
227
 
200
 
  b = branch.Branch.open('http://bazaar-vcs.org/bzr/bzr.dev')
 
228
  b = branch.Branch.open('http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev')
201
229
  nb = b.bzrdir.sprout('/tmp/newBzrBranch').open_branch()
202
230
 
203
231
 
205
233
 
206
234
 
207
235
Pushing and pulling branches
208
 
============================
 
236
----------------------------
209
237
 
210
238
To push a branch you need to open the source and destination branches, then
211
239
just call push with the other branch as a parameter::
213
241
  from bzrlib import branch
214
242
 
215
243
  b1 = branch.Branch.open('file:///home/user/mybranch')
216
 
  b2 = branch.Branch.open('http://bazaar-vcs.org/bzr/bzr.dev')
 
244
  b2 = branch.Branch.open('http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev')
217
245
  b1.push(b2)
218
246
 
219
247
 
244
272
 
245
273
  source.create_checkout('/tmp/newBzrCheckout', None, False, accelerator_tree
246
274
 
247
 
==================
 
275
 
248
276
History Operations
249
277
==================
250
278
 
251
279
Finding the last revision number or id
252
 
======================================
 
280
--------------------------------------
253
281
 
254
282
To get the last revision number and id of a branch use::
255
283
 
263
291
 
264
292
 
265
293
Getting the list of revision ids that make up a branch
266
 
======================================================
 
294
------------------------------------------------------
267
295
 
268
296
IMPORTANT: This should be avoided wherever possible, as it scales with the
269
297
length of history::
277
305
 
278
306
 
279
307
Getting a Revision object from a revision id
280
 
============================================
 
308
--------------------------------------------
281
309
 
282
310
The Revision object has attributes like "message" to get the information
283
311
about the revision::
287
315
 
288
316
 
289
317
Accessing the files from a revision
290
 
===================================
 
318
-----------------------------------
291
319
 
292
320
To get the file contents and tree shape for a specific revision you need
293
321
a RevisionTree. These are supplied by the repository for a specific