3
3
=============================
5
5
This document describes the key classes and concepts within Bazaar. It is
6
intended to be useful to be useful to people working on the Bazaar
7
codebase, or to people writing plugins.
9
If you have any questions or something seems to be incorrect, unclear or
10
missing, please talk to us in ``irc://irc.freenode.net/#bzr``, or write to
11
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.
14
The current version of this document is available in the file
15
``doc/developers/overview.txt`` in the source tree, and from
16
<http://doc.bazaar-vcs.org/bzr.dev/>.
20
* `Bazaar Developer Documentation Catalog <../../developers/index.html>`_.
21
* `Bazaar Developer Guide <../../en/developer-guide/HACKING.html>`_
22
(particularly the *Coding Style Guidelines* section.)
26
Essential Domain Classes
27
########################
29
The core domain objects within the bazaar model are:
39
Transports are explained below. See http://bazaar-vcs.org/Classes/
40
for an introduction to the other key classes.
6
intended to be useful to people working on the Bazaar codebase, or to
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.
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.
16
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.
27
All IDs are globally unique identifiers. Inside bzrlib they are almost
28
always represented as UTF-8 encoded bytestrings (i.e. ``str`` objects).
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.
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``.
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.
45
55
The ``Transport`` layer handles access to local or remote directories.
46
Each Transport object acts like a logical connection to a particular
56
Each Transport object acts as a logical connection to a particular
47
57
directory, and it allows various operations on files within it. You can
48
58
*clone* a transport to get a new Transport connected to a subdirectory or
51
61
Transports are not used for access to the working tree. At present
52
62
working trees are always local and they are accessed through the regular
53
Python file io mechanisms.
63
Python file I/O mechanisms.
58
Transports work in URLs. Take note that URLs are by definition only
59
ASCII - the decision of how to encode a Unicode string into a URL must be
60
taken at a higher level, typically in the Store. (Note that Stores also
61
escape filenames which cannot be safely stored on all filesystems, but
62
this is a different level.)
68
Transports work in terms of URLs. Take note that URLs are by definition
69
only ASCII - the decision of how to encode a Unicode string into a URL
70
must be taken at a higher level, typically in the Store. (Note that
71
Stores also escape filenames which cannot be safely stored on all
72
filesystems, but this is a different level.)
64
74
The main reason for this is that it's not possible to safely roundtrip a
65
75
URL into Unicode and then back into the same URL. The URL standard
67
77
doesn't say how those bytes represent non-ASCII characters. (They're not
68
78
guaranteed to be UTF-8 -- that is common but doesn't happen everywhere.)
70
For example if the user enters the url ``http://example/%e0`` there's no
80
For example, if the user enters the URL ``http://example/%e0``, there's no
71
81
way to tell whether that character represents "latin small letter a with
72
grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2
73
or malformed UTF-8. So we can't convert their URL to Unicode reliably.
75
Equally problematic if we're given a url-like string containing non-ascii
76
characters (such as the accented a) we can't be sure how to convert that
77
to the correct URL, because we don't know what encoding the server expects
78
for those characters. (Although this is not totally reliable we might still
79
accept these and assume they should be put into UTF-8.)
81
A similar edge case is that the url ``http://foo/sweet%2Fsour`` contains
82
grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2,
83
or malformed UTF-8. So we can't convert the URL to Unicode reliably.
85
Equally problematic is if we're given a URL-like string containing
86
(unescaped) non-ASCII characters (such as the accented a). We can't be
87
sure how to convert that to a valid (i.e. ASCII-only) URL, because we
88
don't know what encoding the server expects for those characters.
89
(Although it is not totally reliable, we might still accept these and
90
assume that they should be put into UTF-8.)
92
A similar edge case is that the URL ``http://foo/sweet%2Fsour`` contains
82
93
one directory component whose name is "sweet/sour". The escaped slash is
83
not a directory separator. If we try to convert URLs to regular Unicode
84
paths this information will be lost.
86
This implies that Transports must natively deal with URLs; for simplicity
87
they *only* deal with URLs and conversion of other strings to URLs is done
88
elsewhere. Information they return, such as from ``list_dir``, is also in
89
the form of URL components.
94
not a directory separator, but if we try to convert the URL to a regular
95
Unicode path, this information will be lost.
97
This implies that Transports must natively deal with URLs. For simplicity
98
they *only* deal with URLs; conversion of other strings to URLs is done
99
elsewhere. Information that Transports return, such as from ``list_dir``,
100
is also in the form of URL components.
107
* `Developer guide to bzrlib transports <transports.html>`_
108
* API docs for ``bzrlib.transport.Transport``
113
A representation of a directory of files (and other directories and
114
symlinks etc). The most important kinds of Tree are:
116
:WorkingTree: the files on disk editable by the user
117
:RevisionTree: a tree as recorded at some point in the past
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
128
A workingtree is a special type of Tree that's associated with a working
129
directory on disk, where the user can directly modify the files.
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.
144
* an MutableInventory
145
* local access to the working tree
151
A Branch is a key user concept - its a single line of history that one or
152
more people have been committing to.
154
A Branch is responsible for:
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.
164
* URL access to its base directory.
165
* A Transport to access its files.
166
* A Repository to hold its history.
95
172
Repositories store committed history: file texts, revisions, inventories,
96
and graph relationships between them.
173
and graph relationships between them. A repository holds a bag of
174
revision data that can be pointed to by various branches:
176
* Maintains storage of various history data at a URL:
178
* Revisions (Must have a matching inventory)
180
* Inventories for each Revision. (Must have all the file texts available).
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
98
188
Stacked Repositories
101
Repositories can be configured to refer to a list of "fallback"
191
A repository can be configured to refer to a list of "fallback"
102
192
repositories. If a particular revision is not present in the original
103
193
repository, it refers the query to the fallbacks.
105
195
Compression deltas don't span physical repository boundaries. So the
106
first commit to a new empty repository with fallback repositories will
196
first commit to a new, empty repository with fallback repositories will
107
197
store a full text of the inventory, and of every new file text.
109
199
At runtime, repository stacking is actually configured by the branch, not
110
the repository. So doing ``a_bzrdir.open_repository()``
111
gets you just the single physical repository, while
112
``a_bzrdir.open_branch().repository`` gets one configured with a stacking.
113
Therefore to permanently change the fallback repository stored on disk,
114
you must use ``Branch.set_stacked_on_url``.
200
the repository. So doing ``a_bzrdir.open_repository()``
201
gets you just the single physical repository, while
202
``a_bzrdir.open_branch().repository`` gets one configured with a stacking.
203
Therefore, to permanently change the fallback repository stored on disk,
204
you must use ``Branch.set_stacked_on_url``.
116
Changing away from an existing stacked on url will copy across any
206
Changing away from an existing stacked-on URL will copy across any
117
207
necessary history so that the repository remains usable.
119
A repository opened from an hpss server is never stacked on the server
209
A repository opened from an HPSS server is never stacked on the server
120
210
side, because this could cause complexity or security problems with the
121
211
server acting as a proxy for the client. Instead, the branch on the
122
212
server exposes the stacked-on URL and the client can open that.
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
227
A branch directly contains:
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)
233
A branch implicitly references:
235
* A repository. The repository might be colocated in the same directory
236
as the branch, or it might be somewhere else entirely.
242
A repository contains:
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.
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)*.
262
Stores revision objects. The keys are GUIDs. The value is a revision
263
object (the exact representation on disk depends on the repository
266
As described in `Core Concepts`_ a revision describes a snapshot of the
267
tree of files and some metadata about them.
271
* parent revisions (an ordered sequence of zero or more revision IDs)
275
* (and all other revision properties)
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
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.)
290
An inventory object contains:
292
* a set of inventory entries
294
An inventory entry has the following attributes
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
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
309
An inventory entry will have other attributes, depending on the kind:
328
For some more details see `Inventories <inventory.html>`_.
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.
338
For consistency/simplicity text records exist for all inventory entries,
339
but in general only entries with of kind "file" have interesting records.
345
Stores cryptographic signatures of revision contents. The keys match
346
those of the revision store.
348
.. _Core Concepts: http://doc.bazaar.canonical.com/latest/en/user-guide/core_concepts.html
126
351
vim: ft=rst tw=74 ai
added
removed
doc/developers/overview.txt
