/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/overview.txt

  • Committer: Jelmer Vernooij
  • Date: 2012-02-06 23:38:33 UTC
  • mfrom: (6463 +trunk)
  • mto: This revision was merged to the branch mainline in revision 6464.
  • Revision ID: jelmer@samba.org-20120206233833-w0nbclw7d1xj4twj
merge bzr.dev.

Show diffs side-by-side

added added

removed removed

Lines of Context:
4
4
 
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
 
people writing plugins.
 
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
15
 
9
16
If you have any questions, or if something seems to be incorrect, unclear
10
 
or missing, please talk to us in ``irc://irc.freenode.net/#bzr``, or write
11
 
to the Bazaar mailing list.  To propose a correction or addition to this
12
 
document, send a merge request or new text to the mailing list.
13
 
 
14
 
The current version of this document is available in the file
15
 
``doc/developers/overview.txt`` in the source tree, and available online
16
 
within the developer documentation, <http://doc.bazaar-vcs.org/developers/>.
17
 
 
18
 
 
19
 
Essential Domain Classes
20
 
########################
21
 
 
22
 
The core domain objects within the bazaar model are:
23
 
 
24
 
* Transport
25
 
 
26
 
* Branch
27
 
 
28
 
* Repository
29
 
 
30
 
* WorkingTree
31
 
 
32
 
Transports are explained below. See http://bazaar-vcs.org/Classes/
33
 
for an introduction to the other key classes.
 
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
 
22
############
 
23
 
 
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.
 
35
 
 
36
By convention, in the bzrlib API, parameters of methods that are expected
 
37
to be IDs (as opposed to keys, revision numbers, or some other handle)
 
38
will end in ``id``, e.g.  ``revid`` or ``file_id``.
 
39
 
 
40
Ids may be stored directly or they can be inferred from other
 
41
data. Native Bazaar formats store ids directly; foreign VCS
 
42
support usually generates them somehow. For example, the
 
43
Git commit with SHA ``fb235a3be6372e40ff7f7ebbcd7905a08cb04444``
 
44
is referred to with the revision ID
 
45
``git-v1:fb235a3be6372e40ff7f7ebbcd7905a08cb04444``. IDs are expected
 
46
to be persistent
 
47
 
 
48
File ids
 
49
--------
 
50
 
 
51
File ids are unique identifiers for files. There are three slightly different
 
52
categories of file ids.
 
53
 
 
54
Tree file ids
 
55
~~~~~~~~~~~~~
 
56
 
 
57
Tree file ids are used in the ``Tree`` API and can either be UTF-8 encoded
 
58
bytestrings or tuples of UTF-8 encoded bytestrings. Plain bytestrings
 
59
are considered to be the equivalent of a 1-tuple containing that
 
60
bytestring.
 
61
 
 
62
Tree file ids should be considered valid only for a specific tree context.
 
63
Note that this is a stricter interpretation than what the current bzr
 
64
format implementation provides - its file ids are persistent across runs
 
65
and across revisions.
 
66
 
 
67
For some formats (most notably bzr's own formats) it's possible for the
 
68
implementation to specify the file id to use. In other case the tree
 
69
mandates a specific file id.
 
70
 
 
71
Inventory file ids
 
72
~~~~~~~~~~~~~~~~~~
 
73
 
 
74
Inventories are specific to the bzr native format and are the main layer
 
75
below the ``Tree`` implementation of bzr. File ids in inventories can
 
76
only be UTF-8 encoded bytestrings. A single Tree object can be associated
 
77
with multiple inventories if there are nested trees.
 
78
 
 
79
Tree file ids for bzr formats are a tuple of inventory file ids for the file
 
80
in question. Each non-last item in the tuple refers to the tree
 
81
reference of an inner tree. The last item in the tuple refers to the
 
82
actual file. This means that lookups of file ids doesn't scale with
 
83
the number of nested trees.
 
84
 
 
85
Inventory file ids are only relevant for native Bazaar formats; foreign
 
86
formats don't use inventories.
 
87
 
 
88
Transform ids
 
89
~~~~~~~~~~~~~
 
90
 
 
91
Transform ids are used during tree transform operations (used by e.g. merge).
 
92
The same transform id is expected to be used for two instances of the
 
93
same file. At the moment transform ids are directly derived from file
 
94
ids, but in the future they could be based on other data too (e.g.
 
95
automatic rename detection or format-specific rules).
 
96
 
 
97
Keys
 
98
====
 
99
 
 
100
A composite of one or more ID elements.  E.g. a (file-id, revision-id)
 
101
pair is the key to the "texts" store, but a single element key of
 
102
(revision-id) is the key to the "revisions" store.
 
103
 
 
104
 
 
105
Core classes
 
106
############
34
107
 
35
108
Transport
36
 
#########
 
109
=========
37
110
 
38
111
The ``Transport`` layer handles access to local or remote directories.
39
112
Each Transport object acts as a logical connection to a particular
46
119
Python file I/O mechanisms.
47
120
 
48
121
Filenames vs URLs
49
 
=================
 
122
-----------------
50
123
 
51
124
Transports work in terms of URLs.  Take note that URLs are by definition
52
125
only ASCII - the decision of how to encode a Unicode string into a URL
82
155
elsewhere.  Information that Transports return, such as from ``list_dir``,
83
156
is also in the form of URL components.
84
157
 
 
158
More information
 
159
----------------
 
160
 
 
161
See also:
 
162
 
 
163
* `Developer guide to bzrlib transports <transports.html>`_ 
 
164
* API docs for ``bzrlib.transport.Transport``
 
165
 
 
166
Control directory
 
167
=================
 
168
 
 
169
Control directories are responsible for storing versioning data. Each
 
170
control directory (such as ".bzr/") can contain zero or one repositories,
 
171
zero or one working trees and zero or more branches.
 
172
 
 
173
The ``BzrDir`` class is the ``ControlDir`` implementation that is
 
174
responsible for the ".bzr/" directory and its implementation. Plugins
 
175
that provide support for other version control systems can provide
 
176
other subclasses of ``ControlDir``.
 
177
 
 
178
Tree
 
179
====
 
180
 
 
181
A representation of a directory of files (and other directories and
 
182
symlinks etc).  The most important kinds of Tree are:
 
183
 
 
184
:WorkingTree: the files on disk editable by the user
 
185
:RevisionTree: a tree as recorded at some point in the past
 
186
 
 
187
Trees can map file paths to file-ids and vice versa (although trees such
 
188
as WorkingTree may have unversioned files not described in that mapping).
 
189
Trees have an inventory and parents (an ordered list of zero or more
 
190
revision IDs).
 
191
 
 
192
The implementation of ``Tree`` for Bazaar's own formats is based around
 
193
``Inventory`` objects which describe the shape of the tree. Each tree has
 
194
at least one inventory associated with it, which is available as the
 
195
``root_inventory`` attribute on tree. The tree can have more inventories
 
196
associated with it if there are references to other trees in it. These
 
197
references are indicated with ``tree-reference`` inventory entry at the
 
198
point where the other tree is nested. The tree reference entry contains
 
199
sufficient information for looking up the inventory associated with the
 
200
nested tree. There can be multiple layers of nesting.
 
201
 
 
202
Not each ``Tree`` implementation will necessarily have an associated
 
203
``root_inventory``, as not all implementations of ``Tree`` are based
 
204
around inventories (most notably, implementations of foreign VCS file
 
205
formats).
 
206
 
 
207
WorkingTree
 
208
===========
 
209
 
 
210
A workingtree is a special type of Tree that's associated with a working
 
211
directory on disk, where the user can directly modify the files. 
 
212
 
 
213
Responsibilities:
 
214
 
 
215
* Maintaining a WorkingTree on disk at a file path.
 
216
* Maintaining the basis inventory (the inventory of the last commit done)
 
217
* Maintaining the working inventory.
 
218
* Maintaining the pending merges list.
 
219
* Maintaining the stat cache.
 
220
* Maintaining the last revision the working tree was updated to.
 
221
* Knows where its Branch is located.
 
222
 
 
223
Dependencies:
 
224
 
 
225
* a Branch
 
226
* local access to the working tree
 
227
 
 
228
 
 
229
Branch
 
230
======
 
231
 
 
232
A Branch is a key user concept - its a single line of history that one or
 
233
more people have been committing to. 
 
234
 
 
235
A Branch is responsible for:
 
236
 
 
237
* Holding user preferences that are set in a Branch.
 
238
* Holding the 'tip': the last revision to be committed to this Branch.
 
239
  (And the revno of that revision.)
 
240
* Knowing how to open the Repository that holds its history.
 
241
* Allowing write locks to be taken out to prevent concurrent alterations to the branch.
 
242
 
 
243
Depends on:
 
244
 
 
245
* URL access to its base directory.
 
246
* A Transport to access its files.
 
247
* A Repository to hold its history.
 
248
 
85
249
 
86
250
Repository
87
 
##########
 
251
==========
88
252
 
89
253
Repositories store committed history: file texts, revisions, inventories,
90
 
and graph relationships between them.
 
254
and graph relationships between them.  A repository holds a bag of
 
255
revision data that can be pointed to by various branches:
 
256
 
 
257
* Maintains storage of various history data at a URL:
 
258
  
 
259
  * Revisions (Must have a matching inventory)
 
260
  * Digital Signatures
 
261
  * Inventories for each Revision. (Must have all the file texts available).
 
262
  * File texts
 
263
 
 
264
* Synchronizes concurrent access to the repository by different
 
265
  processes.  (Most repository implementations use a physical mutex only
 
266
  for a short period, and effectively support multiple readers and
 
267
  writers.)
91
268
 
92
269
Stacked Repositories
93
 
====================
 
270
--------------------
94
271
 
95
272
A repository can be configured to refer to a list of "fallback"
96
273
repositories.  If a particular revision is not present in the original
116
293
server exposes the stacked-on URL and the client can open that.
117
294
 
118
295
 
 
296
Storage model
 
297
#############
 
298
 
 
299
This section describes the model for how bzr stores its data.  The
 
300
representation of that data on disk varies considerable depending on the
 
301
format of the repository (and to a lesser extent the format of the branch
 
302
and working tree), but ultimately the set of objects being represented is
 
303
the same.
 
304
 
 
305
Branch
 
306
======
 
307
 
 
308
A branch directly contains:
 
309
 
 
310
* the ID of the current revision that branch (a.k.a. the “tip”)
 
311
* some settings for that branch (the values in “branch.conf”)
 
312
* the set of tags for that branch (not supported in all formats)
 
313
 
 
314
A branch implicitly references:
 
315
 
 
316
* A repository.  The repository might be colocated in the same directory
 
317
  as the branch, or it might be somewhere else entirely.
 
318
 
 
319
 
 
320
Repository
 
321
==========
 
322
 
 
323
A repository contains:
 
324
 
 
325
* a revision store
 
326
* an inventory store
 
327
* a text store
 
328
* a signature store
 
329
 
 
330
A store is a key-value mapping.  This says nothing about the layout on
 
331
disk, just that conceptually there are distinct stores, each with a
 
332
separate namespace for the keys.  Internally the repository may serialize
 
333
stores in the same file, and/or e.g. apply compression algorithms that
 
334
combine records from separate stores in one block, etc.
 
335
 
 
336
You can consider the repository as a single key space, with keys that look
 
337
like *(store-name, ...)*.  For example, *('revisions',
 
338
revision-id)* or *('texts', revision-id, file-id)*.
 
339
 
 
340
Revision store
 
341
--------------
 
342
 
 
343
Stores revision objects.  The keys are GUIDs.  The value is a revision
 
344
object (the exact representation on disk depends on the repository
 
345
format).
 
346
 
 
347
As described in `Core Concepts`_ a revision describes a snapshot of the
 
348
tree of files and some metadata about them.
 
349
 
 
350
* metadata:
 
351
 
 
352
  * parent revisions (an ordered sequence of zero or more revision IDs)
 
353
  * commit message
 
354
  * author(s)
 
355
  * timestamp
 
356
  * (and all other revision properties)
 
357
 
 
358
* an inventory ID (that inventory describes the tree contents).  Is often
 
359
  the same as the revision ID, but doesn't have to be (e.g. if no files
 
360
  were changed between two revisions then both revisions will refer to
 
361
  the same inventory).
 
362
 
 
363
 
 
364
Inventory store
 
365
---------------
 
366
 
 
367
Stores inventory objects.  The keys are GUIDs.  (Footnote: there will
 
368
usually be a revision with the same key in the revision store, but there
 
369
are rare cases where this is not true.)
 
370
 
 
371
An inventory object contains:
 
372
 
 
373
* a set of inventory entries
 
374
 
 
375
An inventory entry has the following attributes
 
376
 
 
377
* a file-id (a GUID, or the special value TREE_ROOT for the root entry of
 
378
  inventories created by older versions of bzr)
 
379
* a revision-id, a GUID (generally corresponding to the ID of a
 
380
  revision).  The combination of (file-id, revision-id) is a key into the
 
381
  texts store.
 
382
* a kind: one of file, directory, symlink, tree-reference (tree-reference
 
383
  is only supported in unsupported developer formats)
 
384
* parent-id: the file-id of the directory that contains this entry (this
 
385
  value is unset for the root of the tree).
 
386
* name: the name of the file/directory/etc in that parent directory
 
387
* executable: a flag indicating if the executable bit is set for that
 
388
  file.
 
389
 
 
390
An inventory entry will have other attributes, depending on the kind:
 
391
 
 
392
* file:
 
393
 
 
394
  * SHA1
 
395
  * size
 
396
 
 
397
* directory
 
398
 
 
399
  * children
 
400
 
 
401
* symlink
 
402
 
 
403
  * symlink_target
 
404
 
 
405
* tree-reference
 
406
 
 
407
  * reference_revision
 
408
 
 
409
For some more details see `Inventories <inventory.html>`_.
 
410
 
 
411
 
 
412
Texts store
 
413
-----------
 
414
 
 
415
Stores the contents of individual versions of files.  The keys are pairs
 
416
of (file-id, revision-id), and the values are the full content (or
 
417
"text") of a version of a file.
 
418
 
 
419
For consistency/simplicity text records exist for all inventory entries,
 
420
but in general only entries with of kind "file" have interesting records.
 
421
 
 
422
 
 
423
Signature store
 
424
---------------
 
425
 
 
426
Stores cryptographic signatures of revision contents.  The keys match
 
427
those of the revision store.
 
428
 
 
429
.. _Core Concepts: http://doc.bazaar.canonical.com/latest/en/user-guide/core_concepts.html
 
430
 
119
431
..
120
432
   vim: ft=rst tw=74 ai