← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/integration.txt

  • Committer: Tarmac
  • Author(s): Vincent Ladeuil
  • Date: 2017-01-30 14:42:05 UTC
  • mfrom: (6620.1.1 trunk)
  • Revision ID: tarmac-20170130144205-r8fh2xpmiuxyozpv
Merge  2.7 into trunk including fix for bug #1657238 [r=vila]

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 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
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
Within bzr
 
18
----------
 
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.
 
22
 
 
23
From outside bzr
 
24
----------------
 
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
 
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``. 
 
31
 
 
32
This returns a context manager within which bzrlib functions will work
 
33
correctly. See the pydoc for ``bzrlib.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 = 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
 
52
====================
 
53
 
 
54
To run command-line commands in-process::
 
55
 
 
56
  from bzrlib.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 `bzrlib.initialize`.
 
63
 
7
64
 
8
65
Manipulating the Working Tree
9
66
=============================
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.
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::
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.
197
255
 
198
256
  from bzrlib import branch
199
257
 
200
 
  b = branch.Branch.open('http://bazaar-vcs.org/bzr/bzr.dev')
 
258
  b = branch.Branch.open('http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev')
201
259
  nb = b.bzrdir.sprout('/tmp/newBzrBranch').open_branch()
202
260
 
203
261
 
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::
213
271
  from bzrlib import branch
214
272
 
215
273
  b1 = branch.Branch.open('file:///home/user/mybranch')
216
 
  b2 = branch.Branch.open('http://bazaar-vcs.org/bzr/bzr.dev')
 
274
  b2 = branch.Branch.open('http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev')
217
275
  b1.push(b2)
218
276
 
219
277
 
244
302
 
245
303
  source.create_checkout('/tmp/newBzrCheckout', None, False, accelerator_tree
246
304
 
247
 
==================
 
305
 
248
306
History Operations
249
307
==================
250
308
 
251
309
Finding the last revision number or id
252
 
======================================
 
310
--------------------------------------
253
311
 
254
312
To get the last revision number and id of a branch use::
255
313
 
263
321
 
264
322
 
265
323
Getting the list of revision ids that make up a branch
266
 
======================================================
 
324
------------------------------------------------------
267
325
 
268
326
IMPORTANT: This should be avoided wherever possible, as it scales with the
269
327
length of history::
277
335
 
278
336
 
279
337
Getting a Revision object from a revision id
280
 
============================================
 
338
--------------------------------------------
281
339
 
282
340
The Revision object has attributes like "message" to get the information
283
341
about the revision::
287
345
 
288
346
 
289
347
Accessing the files from a revision
290
 
===================================
 
348
-----------------------------------
291
349
 
292
350
To get the file contents and tree shape for a specific revision you need
293
351
a RevisionTree. These are supplied by the repository for a specific