/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: Breezy landing bot
  • Author(s): Colin Watson
  • Date: 2020-11-16 21:47:08 UTC
  • mfrom: (7521.1.1 remove-lp-workaround)
  • Revision ID: breezy.the.bot@gmail.com-20201116214708-jos209mgxi41oy15
Remove breezy.git workaround for bazaar.launchpad.net.

Merged from https://code.launchpad.net/~cjwatson/brz/remove-lp-workaround/+merge/393710

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/integration.txt
1
1
=======================
2
 
Integrating with Bazaar
 
2
Integrating with Breezy
3
3
=======================
4
4
 
5
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
 
6
Breezy and some recipes for typical tasks.  It is intended to be useful to
7
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
 
8
integrates with brz.  If you want to know about a topic that's not covered
9
9
here, just ask us.
10
10
 
11
11
 
12
12
 
13
13
 
14
 
Starting with bzrlib
 
14
Starting with breezy
15
15
====================
16
16
 
17
 
Within bzr
 
17
Within brz
18
18
----------
19
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.
 
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
22
 
23
 
From outside bzr
 
23
From outside brz
24
24
----------------
25
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
 
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
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``. 
 
29
way to set all this up in the same fashion ``brz`` does is to call
 
30
``breezy.initialize``.
31
31
 
32
 
This returns a context manager within which bzrlib functions will work
33
 
correctly. See the pydoc for ``bzrlib.initialize`` for more information. 
 
32
This returns a context manager within which breezy functions will work
 
33
correctly. See the pydoc for ``breezy.initialize`` for more information.
34
34
(You can get away without entering the context manager, because the setup
35
35
work happens directly from ``initialize``.)
36
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
 
37
 
 
38
Running brz commands
52
39
====================
53
40
 
54
41
To run command-line commands in-process::
55
42
 
56
 
  from bzrlib.commands import get_command
57
 
  
 
43
  from breezy.commands import get_command
 
44
 
58
45
  cmd = get_command('version')
59
46
  cmd.run([])
60
 
  
 
47
 
61
48
This will send output through the current UIFactory; you can redirect this
62
 
elsewhere through the parameters to `bzrlib.initialize`.
 
49
elsewhere through the parameters to `breezy.initialize`.
63
50
 
64
51
 
65
52
Manipulating the Working Tree
66
53
=============================
67
 
Most objects in Bazaar are in files, named after the class they contain.
 
54
Most objects in Breezy are in files, named after the class they contain.
68
55
To manipulate the Working Tree we need a valid WorkingTree object, which
69
56
is loaded from the workingtree.py file, eg::
70
57
 
71
 
  from bzrlib import workingtree
72
 
  wt = workingtree.WorkingTree.open('/home/jebw/bzrtest')
 
58
  from breezy import workingtree
 
59
  wt = workingtree.WorkingTree.open('/home/jebw/brztest')
73
60
 
74
61
 
75
62
This gives us a WorkingTree object, which has various methods spread over
86
73
 
87
74
``changes_from`` creates a Delta object showing changes::
88
75
 
89
 
  from bzrlib import delta
 
76
  from breezy import delta
90
77
  changes = wt.changes_from(wt.basis_tree())
91
78
 
92
79
This gives us a Delta object, which has several lists of files for each type of
114
101
Adding Files
115
102
------------
116
103
 
117
 
If you want to add files the same way ``bzr add`` does, you can use
 
104
If you want to add files the same way ``brz add`` does, you can use
118
105
MutableTree.smart_add.  By default, this is recursive. Paths can either be
119
106
absolute or relative to the workingtree::
120
107
 
121
108
  wt.smart_add(['dir1/filea.txt', 'fileb.txt',
122
 
                '/home/jebw/bzrtesttree/filec.txt'])
 
109
                '/home/jebw/brztesttree/filec.txt'])
123
110
 
124
111
 
125
112
For more precise control over which files to add, use MutableTree.add::
126
113
 
127
 
  wt.add(['dir1/filea.txt', 'fileb.txt', '/home/jebw/bzrtesttree/filec.txt'])
 
114
  wt.add(['dir1/filea.txt', 'fileb.txt', '/home/jebw/brztesttree/filec.txt'])
128
115
 
129
116
 
130
117
Removing Files
186
173
Generating a log is, in itself, simple.  Grab a branch (see below) and pass
187
174
it to show_log together with a log formatter, eg::
188
175
 
189
 
  from bzrlib import log
190
 
  from bzrlib import branch
 
176
  from breezy import log
 
177
  from breezy import branch
191
178
 
192
179
  b = branch.Branch.open('/path/to/bazaar/branch')
193
180
  lf = log.LongLogFormatter(to_file=sys.stdout)
194
181
  log.show_log(b, lf)
195
182
 
196
183
 
197
 
Three log formatters are included with bzrlib: LongLogFormatter,
 
184
Three log formatters are included with breezy: LongLogFormatter,
198
185
ShortLogFormatter and LineLogFormatter.  These provide long, short and
199
186
single-line log output formats. It's also possible to write your own in
200
187
very little code.
239
226
 
240
227
To work with a branch you need a branch object, created from your branch::
241
228
 
242
 
  from bzrlib import branch
 
229
  from breezy import branch
243
230
 
244
 
  b = branch.Branch.open('/home/jebw/bzrtest')
 
231
  b = branch.Branch.open('/home/jebw/brztest')
245
232
 
246
233
 
247
234
Branching from an existing branch
249
236
 
250
237
To branch you create a branch object representing the branch you are
251
238
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 Bazaar
 
239
The following code clones the brz trunk branch (the latest copy of the Breezy
253
240
source code) - be warned it has to download 60meg so takes a while to run
254
241
with no feedback::
255
242
 
256
 
  from bzrlib import branch
257
 
 
258
 
  b = branch.Branch.open('http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev')
259
 
  nb = b.bzrdir.sprout('/tmp/newBzrBranch').open_branch()
260
 
 
261
 
 
262
 
This provides no feedback, since Bazaar automatically uses the 'silent' UI.
 
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.
263
250
 
264
251
 
265
252
Pushing and pulling branches
268
255
To push a branch you need to open the source and destination branches, then
269
256
just call push with the other branch as a parameter::
270
257
 
271
 
  from bzrlib import branch
 
258
  from breezy import branch
272
259
 
273
260
  b1 = branch.Branch.open('file:///home/user/mybranch')
274
 
  b2 = branch.Branch.open('http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev')
 
261
  b2 = branch.Branch.open('bzr+ssh://bazaar.launchpad.net/+branch/brz/')
275
262
  b1.push(b2)
276
263
 
277
264
 
292
279
 
293
280
This performs a Lightweight checkout from an existing Branch::
294
281
 
295
 
  from bzrlib import bzrdir
 
282
  from breezy import bzrdir
296
283
 
297
284
  accelerator_tree, source = bzrdir.BzrDir.open_tree_or_branch('http:URL')
298
 
  source.create_checkout('/tmp/newBzrCheckout', None, True, accelerator_tree)
 
285
  source.create_checkout('/tmp/newBrzCheckout', None, True, accelerator_tree)
299
286
 
300
287
 
301
288
To make a heavyweight checkout, change the last line to::
302
289
 
303
 
  source.create_checkout('/tmp/newBzrCheckout', None, False, accelerator_tree
 
290
  source.create_checkout('/tmp/newBrzCheckout', None, False, accelerator_tree
304
291
 
305
292
 
306
293
History Operations