~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/overview.txt

  • Committer: Jelmer Vernooij
  • Date: 2010-08-28 11:20:04 UTC
  • mto: This revision was merged to the branch mainline in revision 5418.
  • Revision ID: jelmer@samba.org-20100828112004-83vag2ktvihjlt40
Fix some test failures now that bzrlib.controldir.network_format_registry has moved.

Show diffs side-by-side

added added

removed removed

Lines of Context:
5
5
This document describes the key classes and concepts within Bazaar.  It is
6
6
intended to be useful to people working on the Bazaar codebase, or to
7
7
people writing plugins.  People writing plugins may also like to read the 
8
 
guide to `Integrating with Bazaar <integration.html>`_ for some specific recipes.
9
 
 
10
 
There's some overlap between this and the `Core Concepts`_ section of the
11
 
user guide, but this document is targetted to people interested in the
12
 
internals.  In particular the user guide doesn't go any deeper than
13
 
"revision", because regular users don't care about lower-level details
14
 
like inventories, but this guide does.
 
8
guide to `Integrating with Bazaar <integrating.html>`_ for some specific
 
9
recipes.
15
10
 
16
11
If you have any questions, or if something seems to be incorrect, unclear
17
 
or missing, please talk to us in ``irc://irc.freenode.net/#bzr``, write to
18
 
the Bazaar mailing list, or simply file a bug report.
19
 
 
20
 
 
21
 
IDs and keys
 
12
or missing, please talk to us in ``irc://irc.freenode.net/#bzr``, or write
 
13
to the Bazaar mailing list.  
 
14
 
 
15
 
 
16
Using bzrlib
22
17
############
23
18
 
24
 
IDs
25
 
===
26
 
 
27
 
All IDs are globally unique identifiers.  Inside bzrlib they are almost
28
 
always represented as UTF-8 encoded bytestrings (i.e. ``str`` objects).
29
 
 
30
 
The main two IDs are:
31
 
 
32
 
:Revision IDs: The unique identifier of a single revision, such as
33
 
  ``pqm@pqm.ubuntu.com-20110201161347-ao76mv267gc1b5v2``
34
 
:File IDs: The unique identifier of a single file.  It is allocated when
35
 
  a user does ``bzr add`` and is unchanged by renames.
36
 
 
37
 
By convention, in the bzrlib API, parameters of methods that are expected
38
 
to be IDs (as opposed to keys, revision numbers, or some other handle)
39
 
will end in ``id``, e.g.  ``revid`` or ``file_id``.
40
 
 
41
 
Keys
42
 
====
43
 
 
44
 
A composite of one or more ID elements.  E.g. a (file-id, revision-id)
45
 
pair is the key to the "texts" store, but a single element key of
46
 
(revision-id) is the key to the "revisions" store.
 
19
Within bzr
 
20
==========
 
21
 
 
22
When using bzrlib within the ``bzr`` program (for instance as a bzr
 
23
plugin), bzrlib's global state is already available for use.
 
24
 
 
25
From outside bzr
 
26
================
 
27
 
 
28
To use bzrlib outside of ``bzr`` some global state needs to be setup.
 
29
bzrlib needs ways to handle user input, passwords, a place to emit
 
30
progress bars, logging setup appropriately for your program. The easiest
 
31
way to set all this up in the same fashion ``bzr`` does is to call
 
32
``bzrlib.initialize``. This returns a context manager within which bzrlib
 
33
functions will work correctly. See the pydoc for ``bzrlib.initialize`` for
 
34
more information. In Python 2.4 the ``with`` keyword is not supported and
 
35
so you need to use the context manager manually::
 
36
 
 
37
  # This sets up your ~/.bzr.log, ui factory and so on and so forth. It is
 
38
  # not safe to use as a doctest.
 
39
  library_state = bzrlib.initialize()
 
40
  library_state.__enter__()
 
41
  try:
 
42
      pass
 
43
      # do stuff here
 
44
  finally:
 
45
      library_state.__exit__(None, None, None)
47
46
 
48
47
 
49
48
Core classes
99
98
elsewhere.  Information that Transports return, such as from ``list_dir``,
100
99
is also in the form of URL components.
101
100
 
102
 
More information
103
 
----------------
104
 
 
105
 
See also:
106
 
 
107
 
* `Developer guide to bzrlib transports <transports.html>`_ 
108
 
* API docs for ``bzrlib.transport.Transport``
109
 
 
110
 
Tree
111
 
====
112
 
 
113
 
A representation of a directory of files (and other directories and
114
 
symlinks etc).  The most important kinds of Tree are:
115
 
 
116
 
:WorkingTree: the files on disk editable by the user
117
 
:RevisionTree: a tree as recorded at some point in the past
118
 
 
119
 
Trees can map file paths to file-ids and vice versa (although trees such
120
 
as WorkingTree may have unversioned files not described in that mapping).
121
 
Trees have an inventory and parents (an ordered list of zero or more
122
 
revision IDs).
123
 
 
124
101
 
125
102
WorkingTree
126
103
===========
130
107
 
131
108
Responsibilities:
132
109
 
133
 
* Maintaining a WorkingTree on disk at a file path.
134
 
* Maintaining the basis inventory (the inventory of the last commit done)
135
 
* Maintaining the working inventory.
136
 
* Maintaining the pending merges list.
137
 
* Maintaining the stat cache.
138
 
* Maintaining the last revision the working tree was updated to.
139
 
* Knows where its Branch is located.
 
110
 * Maintaining a WorkingTree on disk at a file path.
 
111
 * Maintaining the basis inventory (the inventory of the last commit done)
 
112
 * Maintaining the working inventory.
 
113
 * Maintaining the pending merges list.
 
114
 * Maintaining the stat cache.
 
115
 * Maintaining the last revision the working tree was updated to.
 
116
 * Knows where its Branch is located.
140
117
 
141
118
Dependencies:
142
119
 
143
 
* a Branch
144
 
* an MutableInventory
145
 
* local access to the working tree
146
 
 
 
120
 * a Branch
 
121
 * an MutableInventory
 
122
 * local access to the working tree
147
123
 
148
124
Branch
149
125
======
153
129
 
154
130
A Branch is responsible for:
155
131
 
156
 
* Holding user preferences that are set in a Branch.
157
 
* Holding the 'tip': the last revision to be committed to this Branch.
158
 
  (And the revno of that revision.)
159
 
* Knowing how to open the Repository that holds its history.
160
 
* Allowing write locks to be taken out to prevent concurrent alterations to the branch.
 
132
 * Holding user preferences that are set in a Branch.
 
133
 * Holding the 'tip': the last revision to be committed to this Branch. (And the revno of that revision.)
 
134
 * Knowing how to open the Repository that holds its history.
 
135
 * Allowing write locks to be taken out to prevent concurrent alterations to the branch.
161
136
 
162
137
Depends on:
163
 
 
164
 
* URL access to its base directory.
165
 
* A Transport to access its files.
166
 
* A Repository to hold its history.
167
 
 
 
138
 * URL access to its base directory.
 
139
 * A Transport to access its files.
 
140
 * A Repository to hold its history.
168
141
 
169
142
Repository
170
143
==========
173
146
and graph relationships between them.  A repository holds a bag of
174
147
revision data that can be pointed to by various branches:
175
148
 
176
 
* Maintains storage of various history data at a URL:
177
 
  
178
 
  * Revisions (Must have a matching inventory)
179
 
  * Digital Signatures
180
 
  * Inventories for each Revision. (Must have all the file texts available).
181
 
  * File texts
182
 
 
183
 
* Synchronizes concurrent access to the repository by different
184
 
  processes.  (Most repository implementations use a physical mutex only
185
 
  for a short period, and effectively support multiple readers and
186
 
  writers.)
 
149
 * Maintains storage of various history data at a URL:
 
150
 
 
151
   * Revisions (Must have a matching inventory)
 
152
   * Digital Signatures
 
153
   * Inventories for each Revision. (Must have all the file texts available).
 
154
   * File texts
 
155
 
 
156
 * Synchronizes concurrent access to the repository by different
 
157
   processes.  (Most repository implementations use a physical 
 
158
   mutex only for a short period, and effectively support multiple readers
 
159
   and writers.)
187
160
 
188
161
Stacked Repositories
189
162
--------------------
212
185
server exposes the stacked-on URL and the client can open that.
213
186
 
214
187
 
215
 
Storage model
216
 
#############
217
 
 
218
 
This section describes the model for how bzr stores its data.  The
219
 
representation of that data on disk varies considerable depending on the
220
 
format of the repository (and to a lesser extent the format of the branch
221
 
and working tree), but ultimately the set of objects being represented is
222
 
the same.
223
 
 
224
 
Branch
225
 
======
226
 
 
227
 
A branch directly contains:
228
 
 
229
 
* the ID of the current revision that branch (a.k.a. the “tip”)
230
 
* some settings for that branch (the values in “branch.conf”)
231
 
* the set of tags for that branch (not supported in all formats)
232
 
 
233
 
A branch implicitly references:
234
 
 
235
 
* A repository.  The repository might be colocated in the same directory
236
 
  as the branch, or it might be somewhere else entirely.
237
 
 
238
 
 
239
 
Repository
240
 
==========
241
 
 
242
 
A repository contains:
243
 
 
244
 
* a revision store
245
 
* an inventory store
246
 
* a text store
247
 
* a signature store
248
 
 
249
 
A store is a key-value mapping.  This says nothing about the layout on
250
 
disk, just that conceptually there are distinct stores, each with a
251
 
separate namespace for the keys.  Internally the repository may serialize
252
 
stores in the same file, and/or e.g. apply compression algorithms that
253
 
combine records from separate stores in one block, etc.
254
 
 
255
 
You can consider the repository as a single key space, with keys that look
256
 
like *(store-name, ...)*.  For example, *('revisions',
257
 
revision-id)* or *('texts', revision-id, file-id)*.
258
 
 
259
 
Revision store
260
 
--------------
261
 
 
262
 
Stores revision objects.  The keys are GUIDs.  The value is a revision
263
 
object (the exact representation on disk depends on the repository
264
 
format).
265
 
 
266
 
As described in `Core Concepts`_ a revision describes a snapshot of the
267
 
tree of files and some metadata about them.
268
 
 
269
 
* metadata:
270
 
 
271
 
  * parent revisions (an ordered sequence of zero or more revision IDs)
272
 
  * commit message
273
 
  * author(s)
274
 
  * timestamp
275
 
  * (and all other revision properties)
276
 
 
277
 
* an inventory ID (that inventory describes the tree contents).  Is often
278
 
  the same as the revision ID, but doesn't have to be (e.g. if no files
279
 
  were changed between two revisions then both revisions will refer to
280
 
  the same inventory).
281
 
 
282
 
 
283
 
Inventory store
284
 
---------------
285
 
 
286
 
Stores inventory objects.  The keys are GUIDs.  (Footnote: there will
287
 
usually be a revision with the same key in the revision store, but there
288
 
are rare cases where this is not true.)
289
 
 
290
 
An inventory object contains:
291
 
 
292
 
* a set of inventory entries
293
 
 
294
 
An inventory entry has the following attributes
295
 
 
296
 
* a file-id (a GUID, or the special value TREE_ROOT for the root entry of
297
 
  inventories created by older versions of bzr)
298
 
* a revision-id, a GUID (generally corresponding to the ID of a
299
 
  revision).  The combination of (file-id, revision-id) is a key into the
300
 
  texts store.
301
 
* a kind: one of file, directory, symlink, tree-reference (tree-reference
302
 
  is only supported in unsupported developer formats)
303
 
* parent-id: the file-id of the directory that contains this entry (this
304
 
  value is unset for the root of the tree).
305
 
* name: the name of the file/directory/etc in that parent directory
306
 
* executable: a flag indicating if the executable bit is set for that
307
 
  file.
308
 
 
309
 
An inventory entry will have other attributes, depending on the kind:
310
 
 
311
 
* file:
312
 
 
313
 
  * SHA1
314
 
  * size
315
 
 
316
 
* directory
317
 
 
318
 
  * children
319
 
 
320
 
* symlink
321
 
 
322
 
  * symlink_target
323
 
 
324
 
* tree-reference
325
 
 
326
 
  * reference_revision
327
 
 
328
 
For some more details see `Inventories <inventories.html>`_.
329
 
 
330
 
 
331
 
Texts store
332
 
-----------
333
 
 
334
 
Stores the contents of individual versions of files.  The keys are pairs
335
 
of (file-id, revision-id), and the values are the full content (or
336
 
"text") of a version of a file.
337
 
 
338
 
For consistency/simplicity text records exist for all inventory entries,
339
 
but in general only entries with of kind "file" have interesting records.
340
 
 
341
 
 
342
 
Signature store
343
 
---------------
344
 
 
345
 
Stores cryptographic signatures of revision contents.  The keys match
346
 
those of the revision store.
347
 
 
348
 
.. _Core Concepts: http://doc.bazaar.canonical.com/latest/en/user-guide/core_concepts.html
349
 
 
350
188
..
351
189
   vim: ft=rst tw=74 ai