/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: John Arbash Meinel
  • Date: 2009-07-08 14:28:04 UTC
  • mto: This revision was merged to the branch mainline in revision 4521.
  • Revision ID: john@arbash-meinel.com-20090708142804-i9rkpi9dmnu7v3x1
https://launchpad.net/bugs/396838
Fix bug #396838, Update LRUCache to maintain invariant even
if a cleanup function raises an exception.

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 <integrating.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
 
Core classes
17
 
############
 
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.
18
41
 
19
42
Transport
20
 
=========
 
43
#########
21
44
 
22
45
The ``Transport`` layer handles access to local or remote directories.
23
46
Each Transport object acts as a logical connection to a particular
30
53
Python file I/O mechanisms.
31
54
 
32
55
Filenames vs URLs
33
 
-----------------
 
56
=================
34
57
 
35
58
Transports work in terms of URLs.  Take note that URLs are by definition
36
59
only ASCII - the decision of how to encode a Unicode string into a URL
67
90
is also in the form of URL components.
68
91
 
69
92
 
70
 
WorkingTree
71
 
===========
72
 
 
73
 
A workingtree is a special type of Tree that's associated with a working
74
 
directory on disk, where the user can directly modify the files. 
75
 
 
76
 
Responsibilities:
77
 
 
78
 
 * Maintaining a WorkingTree on disk at a file path.
79
 
 * Maintaining the basis inventory (the inventory of the last commit done)
80
 
 * Maintaining the working inventory.
81
 
 * Maintaining the pending merges list.
82
 
 * Maintaining the stat cache.
83
 
 * Maintaining the last revision the working tree was updated to.
84
 
 * Knows where its Branch is located.
85
 
 
86
 
Dependencies:
87
 
 
88
 
 * a Branch
89
 
 * an MutableInventory
90
 
 * local access to the working tree
91
 
 
92
 
Branch
93
 
======
94
 
 
95
 
A Branch is a key user concept - its a single line of history that one or
96
 
more people have been committing to. 
97
 
 
98
 
A Branch is responsible for:
99
 
 
100
 
 * Holding user preferences that are set in a Branch.
101
 
 * Holding the 'tip': the last revision to be committed to this Branch. (And the revno of that revision.)
102
 
 * Knowing how to open the Repository that holds its history.
103
 
 * Allowing write locks to be taken out to prevent concurrent alterations to the branch.
104
 
 
105
 
Depends on:
106
 
 * URL access to its base directory.
107
 
 * A Transport to access its files.
108
 
 * A Repository to hold its history.
109
 
 
110
93
Repository
111
 
==========
 
94
##########
112
95
 
113
96
Repositories store committed history: file texts, revisions, inventories,
114
 
and graph relationships between them.  A repository holds a bag of
115
 
revision data that can be pointed to by various branches:
116
 
 
117
 
 * Maintains storage of various history data at a URL:
118
 
   * Revisions (Must have a matching inventory)
119
 
   * Digital Signatures
120
 
   * Inventories for each Revision. (Must have all the file texts available).
121
 
   * File texts
122
 
 
123
 
 * Synchronizes concurrent access to the repository by different
124
 
   processes.  (Most repository implementations use a physical 
125
 
   mutex only for a short period, and effectively support multiple readers
126
 
   and writers.)
 
97
and graph relationships between them.
127
98
 
128
99
Stacked Repositories
129
 
--------------------
 
100
====================
130
101
 
131
102
A repository can be configured to refer to a list of "fallback"
132
103
repositories.  If a particular revision is not present in the original
137
108
store a full text of the inventory, and of every new file text.
138
109
 
139
110
At runtime, repository stacking is actually configured by the branch, not
140
 
the repository.  So doing ``a_bzrdir.open_repository()``
141
 
gets you just the single physical repository, while
142
 
``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. 
143
114
Therefore, to permanently change the fallback repository stored on disk,
144
 
you must use ``Branch.set_stacked_on_url``.
 
115
you must use ``Branch.set_stacked_on_url``.  
145
116
 
146
117
Changing away from an existing stacked-on URL will copy across any
147
118
necessary history so that the repository remains usable.