/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: 2020-04-05 19:11:34 UTC
  • mto: (7490.7.16 work)
  • mto: This revision was merged to the branch mainline in revision 7501.
  • Revision ID: jelmer@jelmer.uk-20200405191134-0aebh8ikiwygxma5
Populate the .gitignore file.

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 brz.  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 brz
 
18
----------
 
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.
 
22
 
 
23
From outside brz
 
24
----------------
 
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
 
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``.
 
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
 
 
38
Running brz commands
 
39
====================
 
40
 
 
41
To run command-line commands in-process::
 
42
 
 
43
  from breezy.commands import get_command
 
44
 
 
45
  cmd = get_command('version')
 
46
  cmd.run([])
 
47
 
 
48
This will send output through the current UIFactory; you can redirect this
 
49
elsewhere through the parameters to `breezy.initialize`.
 
50
 
7
51
 
8
52
Manipulating the Working Tree
9
53
=============================
10
 
Most objects in Bazaar are in files, named after the class they contain.
 
54
Most objects in Breezy are in files, named after the class they contain.
11
55
To manipulate the Working Tree we need a valid WorkingTree object, which
12
56
is loaded from the workingtree.py file, eg::
13
57
 
14
 
  from bzrlib import workingtree
15
 
  wt = workingtree.WorkingTree.open('/home/jebw/bzrtest')
 
58
  from breezy import workingtree
 
59
  wt = workingtree.WorkingTree.open('/home/jebw/brztest')
16
60
 
17
61
 
18
62
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
 
63
itself, and its parent classes MutableTree and Tree - it's worth having a
20
64
look through these three files (workingtree.py, mutabletree.py and tree.py)
21
65
to see which methods are available.
22
66
 
23
67
Compare trees
24
 
===============
 
68
-------------
 
69
 
25
70
There are two methods for comparing trees: ``changes_from`` and
26
71
``iter_changes``.  ``iter_changes`` is more regular and precise, but it is
27
72
somewhat harder to work with.  See the API documentation for more details.
28
73
 
29
74
``changes_from`` creates a Delta object showing changes::
30
75
 
31
 
  from bzrlib import delta
 
76
  from breezy import delta
32
77
  changes = wt.changes_from(wt.basis_tree())
33
78
 
34
79
This gives us a Delta object, which has several lists of files for each type of
54
99
 
55
100
 
56
101
Adding Files
57
 
============
 
102
------------
58
103
 
59
 
If you want to add files the same way ``bzr add`` does, you can use
 
104
If you want to add files the same way ``brz add`` does, you can use
60
105
MutableTree.smart_add.  By default, this is recursive. Paths can either be
61
106
absolute or relative to the workingtree::
62
107
 
63
108
  wt.smart_add(['dir1/filea.txt', 'fileb.txt',
64
 
                '/home/jebw/bzrtesttree/filec.txt'])
 
109
                '/home/jebw/brztesttree/filec.txt'])
65
110
 
66
111
 
67
112
For more precise control over which files to add, use MutableTree.add::
68
113
 
69
 
  wt.add(['dir1/filea.txt', 'fileb.txt', '/home/jebw/bzrtesttree/filec.txt'])
 
114
  wt.add(['dir1/filea.txt', 'fileb.txt', '/home/jebw/brztesttree/filec.txt'])
70
115
 
71
116
 
72
117
Removing Files
73
 
==============
 
118
--------------
74
119
 
75
120
You can remove multiple files at once.  The file paths need to be relative
76
121
to the workingtree::
85
130
 
86
131
 
87
132
Renaming a File
88
 
===============
 
133
---------------
89
134
 
90
135
You can rename one file to a different name using WorkingTree.rename_one.
91
136
You just provide the old and new names, eg::
94
139
 
95
140
 
96
141
Moving Files
97
 
============
 
142
------------
98
143
 
99
144
You can move multiple files from one directory into another using
100
145
WorkingTree.move::
107
152
 
108
153
 
109
154
Committing Changes
110
 
==================
 
155
------------------
111
156
 
112
157
To commit _all_ the changes to our working tree we can just call the
113
158
WorkingTree's commit method, giving it a commit message, eg::
128
173
Generating a log is, in itself, simple.  Grab a branch (see below) and pass
129
174
it to show_log together with a log formatter, eg::
130
175
 
131
 
  from bzrlib import log
132
 
  from bzrlib import branch
 
176
  from breezy import log
 
177
  from breezy import branch
133
178
 
134
179
  b = branch.Branch.open('/path/to/bazaar/branch')
135
180
  lf = log.LongLogFormatter(to_file=sys.stdout)
136
181
  log.show_log(b, lf)
137
182
 
138
183
 
139
 
Three log formatters are included with bzrlib: LongLogFormatter,
 
184
Three log formatters are included with breezy: LongLogFormatter,
140
185
ShortLogFormatter and LineLogFormatter.  These provide long, short and
141
186
single-line log output formats. It's also possible to write your own in
142
187
very little code.
181
226
 
182
227
To work with a branch you need a branch object, created from your branch::
183
228
 
184
 
  from bzrlib import branch
 
229
  from breezy import branch
185
230
 
186
 
  b = branch.Branch.open('/home/jebw/bzrtest')
 
231
  b = branch.Branch.open('/home/jebw/brztest')
187
232
 
188
233
 
189
234
Branching from an existing branch
190
 
=================================
 
235
---------------------------------
191
236
 
192
237
To branch you create a branch object representing the branch you are
193
238
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
 
239
The following code clones the brz trunk branch (the latest copy of the Breezy
195
240
source code) - be warned it has to download 60meg so takes a while to run
196
241
with no feedback::
197
242
 
198
 
  from bzrlib import branch
199
 
 
200
 
  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.
 
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.
205
250
 
206
251
 
207
252
Pushing and pulling branches
208
 
============================
 
253
----------------------------
209
254
 
210
255
To push a branch you need to open the source and destination branches, then
211
256
just call push with the other branch as a parameter::
212
257
 
213
 
  from bzrlib import branch
 
258
  from breezy import branch
214
259
 
215
260
  b1 = branch.Branch.open('file:///home/user/mybranch')
216
 
  b2 = branch.Branch.open('http://bazaar.launchpad.net/~bzr-pqm/bzr/bzr.dev')
 
261
  b2 = branch.Branch.open('bzr+ssh://bazaar.launchpad.net/+branch/brz/')
217
262
  b1.push(b2)
218
263
 
219
264
 
234
279
 
235
280
This performs a Lightweight checkout from an existing Branch::
236
281
 
237
 
  from bzrlib import bzrdir
 
282
  from breezy import bzrdir
238
283
 
239
284
  accelerator_tree, source = bzrdir.BzrDir.open_tree_or_branch('http:URL')
240
 
  source.create_checkout('/tmp/newBzrCheckout', None, True, accelerator_tree)
 
285
  source.create_checkout('/tmp/newBrzCheckout', None, True, accelerator_tree)
241
286
 
242
287
 
243
288
To make a heavyweight checkout, change the last line to::
244
289
 
245
 
  source.create_checkout('/tmp/newBzrCheckout', None, False, accelerator_tree
 
290
  source.create_checkout('/tmp/newBrzCheckout', None, False, accelerator_tree
246
291
 
247
292
 
248
293
History Operations