← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/overview.txt

  • Committer: Martin Pool
  • Date: 2009-07-10 06:46:10 UTC
  • mto: (4525.1.1 integration)
  • mto: This revision was merged to the branch mainline in revision 4526.
  • Revision ID: mbp@sourcefrog.net-20090710064610-sqviksbqp5i34sw2
Rename to per_interrepository

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/overview.txt
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.  People writing plugins may also like to read the 
8
 
guide to `Integrating with Bazaar <integration.html>`_ for some specific
9
 
recipes.
 
7
people writing plugins.
10
8
 
11
9
If you have any questions, or if something seems to be incorrect, unclear
12
10
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
17
 
############
18
 
 
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)
46
 
 
47
 
 
48
 
Core classes
49
 
############
 
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 from 
 
16
<http://doc.bazaar-vcs.org/bzr.dev/>.
 
17
 
 
18
See also:
 
19
 
 
20
 * `Bazaar Developer Documentation Catalog <index.html>`_.
 
21
 * `Bazaar Developer Guide <../en/developer-guide/HACKING.html>`_
 
22
   (particularly the *Coding Style Guidelines* section.)
 
23
 
 
24
.. contents::
 
25
 
 
26
Essential Domain Classes
 
27
########################
 
28
 
 
29
The core domain objects within the bazaar model are:
 
30
 
 
31
* Transport
 
32
 
 
33
* Branch
 
34
 
 
35
* Repository
 
36
 
 
37
* WorkingTree
 
38
 
 
39
Transports are explained below. See http://bazaar-vcs.org/Classes/
 
40
for an introduction to the other key classes.
50
41
 
51
42
Transport
52
 
=========
 
43
#########
53
44
 
54
45
The ``Transport`` layer handles access to local or remote directories.
55
46
Each Transport object acts as a logical connection to a particular
62
53
Python file I/O mechanisms.
63
54
 
64
55
Filenames vs URLs
65
 
-----------------
 
56
=================
66
57
 
67
58
Transports work in terms of URLs.  Take note that URLs are by definition
68
59
only ASCII - the decision of how to encode a Unicode string into a URL
99
90
is also in the form of URL components.
100
91
 
101
92
 
102
 
WorkingTree
103
 
===========
104
 
 
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. 
107
 
 
108
 
Responsibilities:
109
 
 
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.
117
 
 
118
 
Dependencies:
119
 
 
120
 
 * a Branch
121
 
 * an MutableInventory
122
 
 * local access to the working tree
123
 
 
124
 
Branch
125
 
======
126
 
 
127
 
A Branch is a key user concept - its a single line of history that one or
128
 
more people have been committing to. 
129
 
 
130
 
A Branch is responsible for:
131
 
 
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.
136
 
 
137
 
Depends on:
138
 
 * URL access to its base directory.
139
 
 * A Transport to access its files.
140
 
 * A Repository to hold its history.
141
 
 
142
93
Repository
143
 
==========
 
94
##########
144
95
 
145
96
Repositories store committed history: file texts, revisions, inventories,
146
 
and graph relationships between them.  A repository holds a bag of
147
 
revision data that can be pointed to by various branches:
148
 
 
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.)
 
97
and graph relationships between them.
160
98
 
161
99
Stacked Repositories
162
 
--------------------
 
100
====================
163
101
 
164
102
A repository can be configured to refer to a list of "fallback"
165
103
repositories.  If a particular revision is not present in the original
170
108
store a full text of the inventory, and of every new file text.
171
109
 
172
110
At runtime, repository stacking is actually configured by the branch, not
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.
 
111
the repository.  So doing ``a_bzrdir.open_repository()`` 
 
112
gets you just the single physical repository, while 
 
113
``a_bzrdir.open_branch().repository`` gets one configured with a stacking. 
176
114
Therefore, to permanently change the fallback repository stored on disk,
177
 
you must use ``Branch.set_stacked_on_url``.
 
115
you must use ``Branch.set_stacked_on_url``.  
178
116
 
179
117
Changing away from an existing stacked-on URL will copy across any
180
118
necessary history so that the repository remains usable.