← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/integration.txt

  • Committer: Jelmer Vernooij
  • Date: 2011-03-13 21:30:33 UTC
  • mto: This revision was merged to the branch mainline in revision 5724.
  • Revision ID: jelmer@samba.org-20110313213033-ud9t11mm8e3idtti
Add test for per-file-timestamp zipfiles.

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``. This returns a context manager within which bzrlib
 
31
functions will work correctly. See the pydoc for ``bzrlib.initialize`` for
 
32
more information. In Python 2.4 the ``with`` keyword is not supported and
 
33
so you need to use the context manager manually::
 
34
 
 
35
  # This sets up your ~/.bzr.log, ui factory and so on and so forth. It is
 
36
  # not safe to use as a doctest.
 
37
  library_state = bzrlib.initialize()
 
38
  library_state.__enter__()
 
39
  try:
 
40
      pass
 
41
      # do stuff here
 
42
  finally:
 
43
      library_state.__exit__(None, None, None)
 
44
 
 
45
 
 
46
Running bzr commands
 
47
====================
 
48
 
 
49
To run command-line commands in-process::
 
50
 
 
51
  from bzrlib.commands import get_command
 
52
  
 
53
  cmd = get_command('version')
 
54
  cmd.run([])
 
55
  
 
56
This will send output through the current UIFactory; you can redirect this
 
57
elsewhere through the parameters to `bzrlib.initialize`.
 
58
 
7
59
 
8
60
Manipulating the Working Tree
9
61
=============================
16
68
 
17
69
 
18
70
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
 
71
itself, and its parent classes MutableTree and Tree - it's worth having a
20
72
look through these three files (workingtree.py, mutabletree.py and tree.py)
21
73
to see which methods are available.
22
74
 
23
75
Compare trees
24
 
===============
 
76
-------------
 
77
 
25
78
There are two methods for comparing trees: ``changes_from`` and
26
79
``iter_changes``.  ``iter_changes`` is more regular and precise, but it is
27
80
somewhat harder to work with.  See the API documentation for more details.
54
107
 
55
108
 
56
109
Adding Files
57
 
============
 
110
------------
58
111
 
59
112
If you want to add files the same way ``bzr add`` does, you can use
60
113
MutableTree.smart_add.  By default, this is recursive. Paths can either be
70
123
 
71
124
 
72
125
Removing Files
73
 
==============
 
126
--------------
74
127
 
75
128
You can remove multiple files at once.  The file paths need to be relative
76
129
to the workingtree::
85
138
 
86
139
 
87
140
Renaming a File
88
 
===============
 
141
---------------
89
142
 
90
143
You can rename one file to a different name using WorkingTree.rename_one.
91
144
You just provide the old and new names, eg::
94
147
 
95
148
 
96
149
Moving Files
97
 
============
 
150
------------
98
151
 
99
152
You can move multiple files from one directory into another using
100
153
WorkingTree.move::
107
160
 
108
161
 
109
162
Committing Changes
110
 
==================
 
163
------------------
111
164
 
112
165
To commit _all_ the changes to our working tree we can just call the
113
166
WorkingTree's commit method, giving it a commit message, eg::
187
240
 
188
241
 
189
242
Branching from an existing branch
190
 
=================================
 
243
---------------------------------
191
244
 
192
245
To branch you create a branch object representing the branch you are
193
246
branching from, and supply a path/url to the new branch location.
205
258
 
206
259
 
207
260
Pushing and pulling branches
208
 
============================
 
261
----------------------------
209
262
 
210
263
To push a branch you need to open the source and destination branches, then
211
264
just call push with the other branch as a parameter::