/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: Martin Pool
  • Date: 2011-05-20 14:46:02 UTC
  • mto: This revision was merged to the branch mainline in revision 5923.
  • Revision ID: mbp@canonical.com-20110520144602-bqli0t6dj01gl0pv
Various pyflakes import fixes.

Some modules were used for subclassing or at module load time, so there is no
point loading them lazily.

Some were not imported when they should be.

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.
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::