← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/integration.txt

  • Committer: Andrew Bennetts
  • Date: 2009-03-04 07:10:07 UTC
  • mto: (4086.1.2 hpss-integration)
  • mto: This revision was merged to the branch mainline in revision 4087.
  • Revision ID: andrew.bennetts@canonical.com-20090304071007-8iqoi1m44ypmzg2a
Rough prototype of allowing a SearchResult to be passed to fetch, and using that to improve network conversations.

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