/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: Jelmer Vernooij
  • Date: 2017-07-23 22:06:41 UTC
  • mfrom: (6738 trunk)
  • mto: This revision was merged to the branch mainline in revision 6739.
  • Revision ID: jelmer@jelmer.uk-20170723220641-69eczax9bmv8d6kk
Merge trunk, address review comments.

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