/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: 2019-02-04 01:01:24 UTC
  • mto: This revision was merged to the branch mainline in revision 7268.
  • Revision ID: jelmer@jelmer.uk-20190204010124-ni0i4qc6f5tnbvux
Fix source tests.

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
 
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
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 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 breezy
 
15
====================
 
16
 
 
17
Within bzr
 
18
----------
 
19
 
 
20
When using breezy within the ``bzr`` program (for instance as a bzr
 
21
plugin), breezy's global state is already available for use.
 
22
 
 
23
From outside bzr
 
24
----------------
 
25
 
 
26
To use breezy outside of ``bzr`` 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 ``bzr`` 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
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 = breezy.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
 
52
====================
 
53
 
 
54
To run command-line commands in-process::
 
55
 
 
56
  from breezy.commands import get_command
 
57
  
 
58
  cmd = get_command('version')
 
59
  cmd.run([])
 
60
  
 
61
This will send output through the current UIFactory; you can redirect this
 
62
elsewhere through the parameters to `breezy.initialize`.
 
63
 
7
64
 
8
65
Manipulating the Working Tree
9
66
=============================
10
 
Most objects in Bazaar are in files, named after the class they contain.
 
67
Most objects in Breezy are in files, named after the class they contain.
11
68
To manipulate the Working Tree we need a valid WorkingTree object, which
12
69
is loaded from the workingtree.py file, eg::
13
70
 
14
 
  from bzrlib import workingtree
 
71
  from breezy import workingtree
15
72
  wt = workingtree.WorkingTree.open('/home/jebw/bzrtest')
16
73
 
17
74
 
18
75
This gives us a WorkingTree object, which has various methods spread over
19
 
itself, and its parent classes MutableTree and Tree - its worth having a
 
76
itself, and its parent classes MutableTree and Tree - it's worth having a
20
77
look through these three files (workingtree.py, mutabletree.py and tree.py)
21
78
to see which methods are available.
22
79
 
23
80
Compare trees
24
 
===============
 
81
-------------
 
82
 
25
83
There are two methods for comparing trees: ``changes_from`` and
26
84
``iter_changes``.  ``iter_changes`` is more regular and precise, but it is
27
85
somewhat harder to work with.  See the API documentation for more details.
28
86
 
29
87
``changes_from`` creates a Delta object showing changes::
30
88
 
31
 
  from bzrlib import delta
 
89
  from breezy import delta
32
90
  changes = wt.changes_from(wt.basis_tree())
33
91
 
34
92
This gives us a Delta object, which has several lists of files for each type of
54
112
 
55
113
 
56
114
Adding Files
57
 
============
 
115
------------
58
116
 
59
117
If you want to add files the same way ``bzr add`` does, you can use
60
118
MutableTree.smart_add.  By default, this is recursive. Paths can either be
70
128
 
71
129
 
72
130
Removing Files
73
 
==============
 
131
--------------
74
132
 
75
133
You can remove multiple files at once.  The file paths need to be relative
76
134
to the workingtree::
85
143
 
86
144
 
87
145
Renaming a File
88
 
===============
 
146
---------------
89
147
 
90
148
You can rename one file to a different name using WorkingTree.rename_one.
91
149
You just provide the old and new names, eg::
94
152
 
95
153
 
96
154
Moving Files
97
 
============
 
155
------------
98
156
 
99
157
You can move multiple files from one directory into another using
100
158
WorkingTree.move::
107
165
 
108
166
 
109
167
Committing Changes
110
 
==================
 
168
------------------
111
169
 
112
170
To commit _all_ the changes to our working tree we can just call the
113
171
WorkingTree's commit method, giving it a commit message, eg::
128
186
Generating a log is, in itself, simple.  Grab a branch (see below) and pass
129
187
it to show_log together with a log formatter, eg::
130
188
 
131
 
  from bzrlib import log
132
 
  from bzrlib import branch
 
189
  from breezy import log
 
190
  from breezy import branch
133
191
 
134
192
  b = branch.Branch.open('/path/to/bazaar/branch')
135
193
  lf = log.LongLogFormatter(to_file=sys.stdout)
136
194
  log.show_log(b, lf)
137
195
 
138
196
 
139
 
Three log formatters are included with bzrlib: LongLogFormatter,
 
197
Three log formatters are included with breezy: LongLogFormatter,
140
198
ShortLogFormatter and LineLogFormatter.  These provide long, short and
141
199
single-line log output formats. It's also possible to write your own in
142
200
very little code.
181
239
 
182
240
To work with a branch you need a branch object, created from your branch::
183
241
 
184
 
  from bzrlib import branch
 
242
  from breezy import branch
185
243
 
186
244
  b = branch.Branch.open('/home/jebw/bzrtest')
187
245
 
188
246
 
189
247
Branching from an existing branch
190
 
=================================
 
248
---------------------------------
191
249
 
192
250
To branch you create a branch object representing the branch you are
193
251
branching from, and supply a path/url to the new branch location.
194
 
The following code clones the bzr.dev branch (the latest copy of the Bazaar
 
252
The following code clones the bzr.dev branch (the latest copy of the Breezy
195
253
source code) - be warned it has to download 60meg so takes a while to run
196
254
with no feedback::
197
255
 
198
 
  from bzrlib import branch
 
256
  from breezy import branch
199
257
 
200
258
  b = branch.Branch.open('http://bazaar.launchpad.net/~bzr-pqm/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.
 
259
  nb = b.controldir.sprout('/tmp/newBzrBranch').open_branch()
 
260
 
 
261
 
 
262
This provides no feedback, since Breezy automatically uses the 'silent' UI.
205
263
 
206
264
 
207
265
Pushing and pulling branches
208
 
============================
 
266
----------------------------
209
267
 
210
268
To push a branch you need to open the source and destination branches, then
211
269
just call push with the other branch as a parameter::
212
270
 
213
 
  from bzrlib import branch
 
271
  from breezy import branch
214
272
 
215
273
  b1 = branch.Branch.open('file:///home/user/mybranch')
216
274
  b2 = branch.Branch.open('http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev')
234
292
 
235
293
This performs a Lightweight checkout from an existing Branch::
236
294
 
237
 
  from bzrlib import bzrdir
 
295
  from breezy import bzrdir
238
296
 
239
297
  accelerator_tree, source = bzrdir.BzrDir.open_tree_or_branch('http:URL')
240
298
  source.create_checkout('/tmp/newBzrCheckout', None, True, accelerator_tree)