/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: John Ferlito
  • Date: 2009-09-02 04:31:45 UTC
  • mto: (4665.7.1 serve-init)
  • mto: This revision was merged to the branch mainline in revision 4913.
  • Revision ID: johnf@inodes.org-20090902043145-gxdsfw03ilcwbyn5
Add a debian init script for bzr --serve

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 brz.  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 brz
18
 
----------
19
 
 
20
 
When using breezy within the ``brz`` program (for instance as a brz
21
 
plugin), breezy's global state is already available for use.
22
 
 
23
 
From outside brz
24
 
----------------
25
 
 
26
 
To use breezy outside of ``brz`` 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 ``brz`` 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
 
 
38
 
Running brz commands
39
 
====================
40
 
 
41
 
To run command-line commands in-process::
42
 
 
43
 
  from breezy.commands import get_command
44
 
 
45
 
  cmd = get_command('version')
46
 
  cmd.run([])
47
 
 
48
 
This will send output through the current UIFactory; you can redirect this
49
 
elsewhere through the parameters to `breezy.initialize`.
50
 
 
 
5
This page should hopefully become a quick guide to integrating other
 
6
(Python-based) software with Bazaar.
51
7
 
52
8
Manipulating the Working Tree
53
9
=============================
54
 
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.
55
11
To manipulate the Working Tree we need a valid WorkingTree object, which
56
12
is loaded from the workingtree.py file, eg::
57
13
 
58
 
  from breezy import workingtree
59
 
  wt = workingtree.WorkingTree.open('/home/jebw/brztest')
 
14
  from bzrlib import workingtree
 
15
  wt = workingtree.WorkingTree.open('/home/jebw/bzrtest')
60
16
 
61
17
 
62
18
This gives us a WorkingTree object, which has various methods spread over
63
 
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
64
20
look through these three files (workingtree.py, mutabletree.py and tree.py)
65
21
to see which methods are available.
66
22
 
67
23
Compare trees
68
 
-------------
69
 
 
 
24
===============
70
25
There are two methods for comparing trees: ``changes_from`` and
71
26
``iter_changes``.  ``iter_changes`` is more regular and precise, but it is
72
27
somewhat harder to work with.  See the API documentation for more details.
73
28
 
74
29
``changes_from`` creates a Delta object showing changes::
75
30
 
76
 
  from breezy import delta
 
31
  from bzrlib import delta
77
32
  changes = wt.changes_from(wt.basis_tree())
78
33
 
79
34
This gives us a Delta object, which has several lists of files for each type of
99
54
 
100
55
 
101
56
Adding Files
102
 
------------
 
57
============
103
58
 
104
 
If you want to add files the same way ``brz add`` does, you can use
 
59
If you want to add files the same way ``bzr add`` does, you can use
105
60
MutableTree.smart_add.  By default, this is recursive. Paths can either be
106
61
absolute or relative to the workingtree::
107
62
 
108
63
  wt.smart_add(['dir1/filea.txt', 'fileb.txt',
109
 
                '/home/jebw/brztesttree/filec.txt'])
 
64
                '/home/jebw/bzrtesttree/filec.txt'])
110
65
 
111
66
 
112
67
For more precise control over which files to add, use MutableTree.add::
113
68
 
114
 
  wt.add(['dir1/filea.txt', 'fileb.txt', '/home/jebw/brztesttree/filec.txt'])
 
69
  wt.add(['dir1/filea.txt', 'fileb.txt', '/home/jebw/bzrtesttree/filec.txt'])
115
70
 
116
71
 
117
72
Removing Files
118
 
--------------
 
73
==============
119
74
 
120
75
You can remove multiple files at once.  The file paths need to be relative
121
76
to the workingtree::
130
85
 
131
86
 
132
87
Renaming a File
133
 
---------------
 
88
===============
134
89
 
135
90
You can rename one file to a different name using WorkingTree.rename_one.
136
91
You just provide the old and new names, eg::
139
94
 
140
95
 
141
96
Moving Files
142
 
------------
 
97
============
143
98
 
144
99
You can move multiple files from one directory into another using
145
100
WorkingTree.move::
152
107
 
153
108
 
154
109
Committing Changes
155
 
------------------
 
110
==================
156
111
 
157
112
To commit _all_ the changes to our working tree we can just call the
158
113
WorkingTree's commit method, giving it a commit message, eg::
173
128
Generating a log is, in itself, simple.  Grab a branch (see below) and pass
174
129
it to show_log together with a log formatter, eg::
175
130
 
176
 
  from breezy import log
177
 
  from breezy import branch
 
131
  from bzrlib import log
 
132
  from bzrlib import branch
178
133
 
179
134
  b = branch.Branch.open('/path/to/bazaar/branch')
180
135
  lf = log.LongLogFormatter(to_file=sys.stdout)
181
136
  log.show_log(b, lf)
182
137
 
183
138
 
184
 
Three log formatters are included with breezy: LongLogFormatter,
 
139
Three log formatters are included with bzrlib: LongLogFormatter,
185
140
ShortLogFormatter and LineLogFormatter.  These provide long, short and
186
141
single-line log output formats. It's also possible to write your own in
187
142
very little code.
226
181
 
227
182
To work with a branch you need a branch object, created from your branch::
228
183
 
229
 
  from breezy import branch
 
184
  from bzrlib import branch
230
185
 
231
 
  b = branch.Branch.open('/home/jebw/brztest')
 
186
  b = branch.Branch.open('/home/jebw/bzrtest')
232
187
 
233
188
 
234
189
Branching from an existing branch
235
 
---------------------------------
 
190
=================================
236
191
 
237
192
To branch you create a branch object representing the branch you are
238
193
branching from, and supply a path/url to the new branch location.
239
 
The following code clones the brz trunk branch (the latest copy of the Breezy
 
194
The following code clones the bzr.dev branch (the latest copy of the Bazaar
240
195
source code) - be warned it has to download 60meg so takes a while to run
241
196
with no feedback::
242
197
 
243
 
  from breezy import branch
244
 
 
245
 
  b = branch.Branch.open('bzr+ssh://bazaar.launchpad.net/+branch/brz/')
246
 
  nb = b.controldir.sprout('/tmp/newBrzBzranch').open_branch()
247
 
 
248
 
 
249
 
This provides no feedback, since Breezy automatically uses the 'silent' UI.
 
198
  from bzrlib import branch
 
199
 
 
200
  b = branch.Branch.open('http://bazaar-vcs.org/bzr/bzr.dev')
 
201
  nb = b.bzrdir.sprout('/tmp/newBzrBranch').open_branch()
 
202
 
 
203
 
 
204
This provides no feedback, since Bazaar automatically uses the 'silent' UI.
250
205
 
251
206
 
252
207
Pushing and pulling branches
253
 
----------------------------
 
208
============================
254
209
 
255
210
To push a branch you need to open the source and destination branches, then
256
211
just call push with the other branch as a parameter::
257
212
 
258
 
  from breezy import branch
 
213
  from bzrlib import branch
259
214
 
260
215
  b1 = branch.Branch.open('file:///home/user/mybranch')
261
 
  b2 = branch.Branch.open('bzr+ssh://bazaar.launchpad.net/+branch/brz/')
 
216
  b2 = branch.Branch.open('http://bazaar-vcs.org/bzr/bzr.dev')
262
217
  b1.push(b2)
263
218
 
264
219
 
279
234
 
280
235
This performs a Lightweight checkout from an existing Branch::
281
236
 
282
 
  from breezy import bzrdir
 
237
  from bzrlib import bzrdir
283
238
 
284
239
  accelerator_tree, source = bzrdir.BzrDir.open_tree_or_branch('http:URL')
285
 
  source.create_checkout('/tmp/newBrzCheckout', None, True, accelerator_tree)
 
240
  source.create_checkout('/tmp/newBzrCheckout', None, True, accelerator_tree)
286
241
 
287
242
 
288
243
To make a heavyweight checkout, change the last line to::
289
244
 
290
 
  source.create_checkout('/tmp/newBrzCheckout', None, False, accelerator_tree
291
 
 
292
 
 
 
245
  source.create_checkout('/tmp/newBzrCheckout', None, False, accelerator_tree
 
246
 
 
247
==================
293
248
History Operations
294
249
==================
295
250
 
296
251
Finding the last revision number or id
297
 
--------------------------------------
 
252
======================================
298
253
 
299
254
To get the last revision number and id of a branch use::
300
255
 
308
263
 
309
264
 
310
265
Getting the list of revision ids that make up a branch
311
 
------------------------------------------------------
 
266
======================================================
312
267
 
313
268
IMPORTANT: This should be avoided wherever possible, as it scales with the
314
269
length of history::
322
277
 
323
278
 
324
279
Getting a Revision object from a revision id
325
 
--------------------------------------------
 
280
============================================
326
281
 
327
282
The Revision object has attributes like "message" to get the information
328
283
about the revision::
332
287
 
333
288
 
334
289
Accessing the files from a revision
335
 
-----------------------------------
 
290
===================================
336
291
 
337
292
To get the file contents and tree shape for a specific revision you need
338
293
a RevisionTree. These are supplied by the repository for a specific