3
3
=============================
5
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.
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 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
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
12
document, send a merge request or new text to the mailing list.
14
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/>.
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.)
19
26
Essential Domain Classes
20
27
########################
38
45
The ``Transport`` layer handles access to local or remote directories.
39
Each Transport object acts as a logical connection to a particular
46
Each Transport object acts like a logical connection to a particular
40
47
directory, and it allows various operations on files within it. You can
41
48
*clone* a transport to get a new Transport connected to a subdirectory or
44
51
Transports are not used for access to the working tree. At present
45
52
working trees are always local and they are accessed through the regular
46
Python file I/O mechanisms.
53
Python file io mechanisms.
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.)
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.)
57
64
The main reason for this is that it's not possible to safely roundtrip a
58
65
URL into Unicode and then back into the same URL. The URL standard
60
67
doesn't say how those bytes represent non-ASCII characters. (They're not
61
68
guaranteed to be UTF-8 -- that is common but doesn't happen everywhere.)
63
For example, if the user enters the URL ``http://example/%e0``, there's no
70
For example if the user enters the url ``http://example/%e0`` there's no
64
71
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.
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.)
75
A similar edge case is that the URL ``http://foo/sweet%2Fsour`` contains
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
76
82
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.
83
not a directory separator. If we try to convert URLs to regular Unicode
84
paths this information will be lost.
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.
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.
92
98
Stacked Repositories
93
99
====================
95
A repository can be configured to refer to a list of "fallback"
101
Repositories can be configured to refer to a list of "fallback"
96
102
repositories. If a particular revision is not present in the original
97
103
repository, it refers the query to the fallbacks.
99
105
Compression deltas don't span physical repository boundaries. So the
100
first commit to a new, empty repository with fallback repositories will
106
first commit to a new empty repository with fallback repositories will
101
107
store a full text of the inventory, and of every new file text.
103
109
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``.
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``.
110
Changing away from an existing stacked-on URL will copy across any
116
Changing away from an existing stacked on url will copy across any
111
117
necessary history so that the repository remains usable.
113
A repository opened from an HPSS server is never stacked on the server
119
A repository opened from an hpss server is never stacked on the server
114
120
side, because this could cause complexity or security problems with the
115
121
server acting as a proxy for the client. Instead, the branch on the
116
122
server exposes the stacked-on URL and the client can open that.
added
removed
doc/developers/overview.txt
