← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/overview.txt

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2010-03-11 13:47:06 UTC
  • mfrom: (5051.3.16 use-branch-open)
  • Revision ID: pqm@pqm.ubuntu.com-20100311134706-kaerqhx3lf7xn6rh
(Jelmer) Pass colocated branch names further down the call stack.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/developers/overview.txt
 
1
=============================
 
2
Bazaar Architectural Overview
 
3
=============================
 
4
 
 
5
This document describes the key classes and concepts within Bazaar.  It is
 
6
intended to be useful to people working on the Bazaar codebase, or to
 
7
people writing plugins.
 
8
 
 
9
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.
 
34
 
 
35
Transport
 
36
#########
 
37
 
 
38
The ``Transport`` layer handles access to local or remote directories.
 
39
Each Transport object acts as a logical connection to a particular
 
40
directory, and it allows various operations on files within it.  You can
 
41
*clone* a transport to get a new Transport connected to a subdirectory or
 
42
parent directory.
 
43
 
 
44
Transports are not used for access to the working tree.  At present
 
45
working trees are always local and they are accessed through the regular
 
46
Python file I/O mechanisms.
 
47
 
 
48
Filenames vs URLs
 
49
=================
 
50
 
 
51
Transports work in terms of URLs.  Take note that URLs are by definition
 
52
only ASCII - the decision of how to encode a Unicode string into a URL
 
53
must be taken at a higher level, typically in the Store.  (Note that
 
54
Stores also escape filenames which cannot be safely stored on all
 
55
filesystems, but this is a different level.)
 
56
 
 
57
The main reason for this is that it's not possible to safely roundtrip a
 
58
URL into Unicode and then back into the same URL.  The URL standard
 
59
gives a way to represent non-ASCII bytes in ASCII (as %-escapes), but
 
60
doesn't say how those bytes represent non-ASCII characters.  (They're not
 
61
guaranteed to be UTF-8 -- that is common but doesn't happen everywhere.)
 
62
 
 
63
For example, if the user enters the URL ``http://example/%e0``, there's no
 
64
way to tell whether that character represents "latin small letter a with
 
65
grave" in iso-8859-1, or "latin small letter r with acute" in iso-8859-2,
 
66
or malformed UTF-8.  So we can't convert the URL to Unicode reliably.
 
67
 
 
68
Equally problematic is if we're given a URL-like string containing
 
69
(unescaped) non-ASCII characters (such as the accented a).  We can't be
 
70
sure how to convert that to a valid (i.e. ASCII-only) URL, because we
 
71
don't know what encoding the server expects for those characters.
 
72
(Although it is not totally reliable, we might still accept these and
 
73
assume that they should be put into UTF-8.)
 
74
 
 
75
A similar edge case is that the URL ``http://foo/sweet%2Fsour`` contains
 
76
one directory component whose name is "sweet/sour".  The escaped slash is
 
77
not a directory separator, but if we try to convert the URL to a regular
 
78
Unicode path, this information will be lost.
 
79
 
 
80
This implies that Transports must natively deal with URLs.  For simplicity
 
81
they *only* deal with URLs; conversion of other strings to URLs is done
 
82
elsewhere.  Information that Transports return, such as from ``list_dir``,
 
83
is also in the form of URL components.
 
84
 
 
85
 
 
86
Repository
 
87
##########
 
88
 
 
89
Repositories store committed history: file texts, revisions, inventories,
 
90
and graph relationships between them.
 
91
 
 
92
Stacked Repositories
 
93
====================
 
94
 
 
95
A repository can be configured to refer to a list of "fallback"
 
96
repositories.  If a particular revision is not present in the original
 
97
repository, it refers the query to the fallbacks.
 
98
 
 
99
Compression deltas don't span physical repository boundaries.  So the
 
100
first commit to a new, empty repository with fallback repositories will
 
101
store a full text of the inventory, and of every new file text.
 
102
 
 
103
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.
 
107
Therefore, to permanently change the fallback repository stored on disk,
 
108
you must use ``Branch.set_stacked_on_url``.
 
109
 
 
110
Changing away from an existing stacked-on URL will copy across any
 
111
necessary history so that the repository remains usable.
 
112
 
 
113
A repository opened from an HPSS server is never stacked on the server
 
114
side, because this could cause complexity or security problems with the
 
115
server acting as a proxy for the client.  Instead, the branch on the
 
116
server exposes the stacked-on URL and the client can open that.
 
117
 
 
118
 
 
119
..
 
120
   vim: ft=rst tw=74 ai