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
9
11
If you have any questions, or if something seems to be incorrect, unclear
10
12
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.
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/>.
19
Essential Domain Classes
20
########################
22
The core domain objects within the bazaar model are:
32
Transports are explained below. See http://bazaar-vcs.org/Classes/
33
for an introduction to the other key classes.
13
to the Bazaar mailing list.
22
When using bzrlib within the ``bzr`` program (for instance as a bzr
23
plugin), bzrlib's global state is already available for use.
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::
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__()
45
library_state.__exit__(None, None, None)
38
54
The ``Transport`` layer handles access to local or remote directories.
39
55
Each Transport object acts as a logical connection to a particular
83
99
is also in the form of URL components.
105
A workingtree is a special type of Tree that's associated with a working
106
directory on disk, where the user can directly modify the files.
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.
121
* an MutableInventory
122
* local access to the working tree
127
A Branch is a key user concept - its a single line of history that one or
128
more people have been committing to.
130
A Branch is responsible for:
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.
138
* URL access to its base directory.
139
* A Transport to access its files.
140
* A Repository to hold its history.
89
145
Repositories store committed history: file texts, revisions, inventories,
90
and graph relationships between them.
146
and graph relationships between them. A repository holds a bag of
147
revision data that can be pointed to by various branches:
149
* Maintains storage of various history data at a URL:
151
* Revisions (Must have a matching inventory)
153
* Inventories for each Revision. (Must have all the file texts available).
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
92
161
Stacked Repositories
95
164
A repository can be configured to refer to a list of "fallback"
96
165
repositories. If a particular revision is not present in the original
101
170
store a full text of the inventory, and of every new file text.
103
172
At runtime, repository stacking is actually configured by the branch, not
104
the repository. So doing ``a_bzrdir.open_repository()``
105
gets you just the single physical repository, while
106
``a_bzrdir.open_branch().repository`` gets one configured with a stacking.
173
the repository. So doing ``a_bzrdir.open_repository()``
174
gets you just the single physical repository, while
175
``a_bzrdir.open_branch().repository`` gets one configured with a stacking.
107
176
Therefore, to permanently change the fallback repository stored on disk,
108
you must use ``Branch.set_stacked_on_url``.
177
you must use ``Branch.set_stacked_on_url``.
110
179
Changing away from an existing stacked-on URL will copy across any
111
180
necessary history so that the repository remains usable.
added
removed
doc/developers/overview.txt
