~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/developers/overview.txt

  • Committer: Vincent Ladeuil
  • Date: 2012-02-14 17:22:37 UTC
  • mfrom: (6466 +trunk)
  • mto: This revision was merged to the branch mainline in revision 6468.
  • Revision ID: v.ladeuil+lp@free.fr-20120214172237-7dv7er3n4uy8d5m4
Merge trunk

Show diffs side-by-side

added added

removed removed

Lines of Context:
31
31
 
32
32
:Revision IDs: The unique identifier of a single revision, such as
33
33
  ``pqm@pqm.ubuntu.com-20110201161347-ao76mv267gc1b5v2``
34
 
:File IDs: The unique identifier of a single file.  It is allocated when
35
 
  a user does ``bzr add`` and is unchanged by renames.
 
34
:File IDs: The unique identifier of a single file.
36
35
 
37
36
By convention, in the bzrlib API, parameters of methods that are expected
38
37
to be IDs (as opposed to keys, revision numbers, or some other handle)
39
38
will end in ``id``, e.g.  ``revid`` or ``file_id``.
40
39
 
 
40
Ids may be stored directly or they can be inferred from other
 
41
data. Native Bazaar formats store ids directly; foreign VCS
 
42
support usually generates them somehow. For example, the
 
43
Git commit with SHA ``fb235a3be6372e40ff7f7ebbcd7905a08cb04444``
 
44
is referred to with the revision ID
 
45
``git-v1:fb235a3be6372e40ff7f7ebbcd7905a08cb04444``. IDs are expected
 
46
to be persistent
 
47
 
 
48
File ids
 
49
--------
 
50
 
 
51
File ids are unique identifiers for files. There are three slightly different
 
52
categories of file ids.
 
53
 
 
54
Tree file ids
 
55
~~~~~~~~~~~~~
 
56
 
 
57
Tree file ids are used in the ``Tree`` API and can either be UTF-8 encoded
 
58
bytestrings or tuples of UTF-8 encoded bytestrings. Plain bytestrings
 
59
are considered to be the equivalent of a 1-tuple containing that
 
60
bytestring.
 
61
 
 
62
Tree file ids should be considered valid only for a specific tree context.
 
63
Note that this is a stricter interpretation than what the current bzr
 
64
format implementation provides - its file ids are persistent across runs
 
65
and across revisions.
 
66
 
 
67
For some formats (most notably bzr's own formats) it's possible for the
 
68
implementation to specify the file id to use. In other case the tree
 
69
mandates a specific file id.
 
70
 
 
71
Inventory file ids
 
72
~~~~~~~~~~~~~~~~~~
 
73
 
 
74
Inventories are specific to the bzr native format and are the main layer
 
75
below the ``Tree`` implementation of bzr. File ids in inventories can
 
76
only be UTF-8 encoded bytestrings. A single Tree object can be associated
 
77
with multiple inventories if there are nested trees.
 
78
 
 
79
Tree file ids for bzr formats are a tuple of inventory file ids for the file
 
80
in question. Each non-last item in the tuple refers to the tree
 
81
reference of an inner tree. The last item in the tuple refers to the
 
82
actual file. This means that lookups of file ids doesn't scale with
 
83
the number of nested trees.
 
84
 
 
85
Inventory file ids are only relevant for native Bazaar formats; foreign
 
86
formats don't use inventories.
 
87
 
 
88
Transform ids
 
89
~~~~~~~~~~~~~
 
90
 
 
91
Transform ids are used during tree transform operations (used by e.g. merge).
 
92
The same transform id is expected to be used for two instances of the
 
93
same file. At the moment transform ids are directly derived from file
 
94
ids, but in the future they could be based on other data too (e.g.
 
95
automatic rename detection or format-specific rules).
 
96
 
41
97
Keys
42
98
====
43
99
 
107
163
* `Developer guide to bzrlib transports <transports.html>`_ 
108
164
* API docs for ``bzrlib.transport.Transport``
109
165
 
 
166
Control directory
 
167
=================
 
168
 
 
169
Each control directory (such as ".bzr/") can contain zero or one
 
170
repositories, zero or one working trees and zero or more branches.
 
171
 
 
172
The ``BzrDir`` class is the ``ControlDir`` implementation that is
 
173
responsible for the ".bzr/" directory and its implementation. Plugins
 
174
that provide support for other version control systems can provide
 
175
other subclasses of ``ControlDir``.
 
176
 
110
177
Tree
111
178
====
112
179
 
121
188
Trees have an inventory and parents (an ordered list of zero or more
122
189
revision IDs).
123
190
 
 
191
The implementation of ``Tree`` for Bazaar's own formats is based around
 
192
``Inventory`` objects which describe the shape of the tree. Each tree has
 
193
at least one inventory associated with it, which is available as the
 
194
``root_inventory`` attribute on tree. The tree can have more inventories
 
195
associated with it if there are references to other trees in it. These
 
196
references are indicated with ``tree-reference`` inventory entry at the
 
197
point where the other tree is nested. The tree reference entry contains
 
198
sufficient information for looking up the inventory associated with the
 
199
nested tree. There can be multiple layers of nesting.
 
200
 
 
201
Not each ``Tree`` implementation will necessarily have an associated
 
202
``root_inventory``, as not all implementations of ``Tree`` are based
 
203
around inventories (most notably, implementations of foreign VCS file
 
204
formats).
124
205
 
125
206
WorkingTree
126
207
===========
141
222
Dependencies:
142
223
 
143
224
* a Branch
144
 
* an MutableInventory
145
225
* local access to the working tree
146
226
 
147
227