836
by Jelmer Vernooij
Fix syntax, add ToC. |
1 |
Bazaar Subversion Mapping Specification |
2 |
======================================= |
|
784.1.1
by Jelmer Vernooij
documentation fixes |
3 |
|
103
by Jelmer Vernooij
Update docs. |
4 |
This document specifies mapping between Subversion and Bazaar semantics. |
5 |
||
658
by Jelmer Vernooij
Update mapping specs wrt revisions properties. |
6 |
Revision: 4 |
787
by Jelmer Vernooij
Fix formatting. |
7 |
|
602
by Jelmer Vernooij
Add another test, update docs. |
8 |
Written by Jelmer Vernooij <jelmer@samba.org> |
103
by Jelmer Vernooij
Update docs. |
9 |
|
836
by Jelmer Vernooij
Fix syntax, add ToC. |
10 |
.. contents:: |
11 |
||
402.1.49
by Jelmer Vernooij
Convert mapping text to LaTeX. |
12 |
Branch paths |
836
by Jelmer Vernooij
Fix syntax, add ToC. |
13 |
------------ |
103
by Jelmer Vernooij
Update docs. |
14 |
|
15 |
It is hard to know, given a SVN URL, to figure out what branch a particular |
|
16 |
file is in. Other then the convention that branches are named 'trunk' and |
|
402.1.49
by Jelmer Vernooij
Convert mapping text to LaTeX. |
17 |
'branches/\*', there is no way to automatically find out what a branch is. |
103
by Jelmer Vernooij
Update docs. |
18 |
Finding out what a branch is and what is not is done by a BranchingScheme |
19 |
implementation. At the moment, the following branching schemes are available: |
|
20 |
||
402.1.49
by Jelmer Vernooij
Convert mapping text to LaTeX. |
21 |
- NoBranchingScheme: The top-level directory in the repository is a branch. |
22 |
(consequence of this is that there is only one branch total) |
|
23 |
||
24 |
- TrunkBranchingScheme: There is a directory structure with 'trunk', |
|
25 |
'branches', and 'tags' directories as common in Subversion-based projects. |
|
26 |
These directories can be nested (e.g. subproject1/trunk) inside the |
|
27 |
repository. The level of nesting is stored. |
|
28 |
||
29 |
- ListBranchingScheme: There is a list of branches. This branching |
|
30 |
scheme is present in the code, but is never used automatically (yet). |
|
103
by Jelmer Vernooij
Update docs. |
31 |
|
787
by Jelmer Vernooij
Fix formatting. |
32 |
- SingleBranchingScheme: There is a single branch (path of that branch is also part of the scheme name). |
516
by Jelmer Vernooij
Update mapping for singlebranchingscheme. |
33 |
|
103
by Jelmer Vernooij
Update docs. |
34 |
The branching scheme can be explicitly specified or automatically guessed. |
35 |
||
402.1.49
by Jelmer Vernooij
Convert mapping text to LaTeX. |
36 |
Revision ids |
836
by Jelmer Vernooij
Fix syntax, add ToC. |
37 |
------------ |
103
by Jelmer Vernooij
Update docs. |
38 |
|
39 |
An easy way to generate globally unique and reproducible revision ids is to |
|
40 |
simply combine the repositories UUID and commit revision number. |
|
41 |
||
42 |
However, this can lead to overlap in revision ids when a commit touches more |
|
43 |
then one branch (something that is possible in SVN). This can be fixed by |
|
787
by Jelmer Vernooij
Fix formatting. |
44 |
including the branch path (``trunk``, ``branches/SAMBA_4_0``, etc) in the |
103
by Jelmer Vernooij
Update docs. |
45 |
revision-id. Example revision id: |
46 |
||
516
by Jelmer Vernooij
Update mapping for singlebranchingscheme. |
47 |
``svn-v3-trunk0:0c0555d6-39d7-0310-84fc-f1cc0bd64818:trunk:14323`` |
103
by Jelmer Vernooij
Update docs. |
48 |
|
49 |
The version number is used to distinguish between versions of the mapping |
|
50 |
between Bazaar and Subversion. The mapping will change when previously |
|
51 |
unsupported features are added to Bazaar (see below), or when a bug in bzr-svn |
|
52 |
is fixed that may affect the mappings. |
|
53 |
||
144
by Jelmer Vernooij
Update details on tracking ancestry. |
54 |
Once branching schemes can be manually specified, also needs to contain |
55 |
branching scheme as it might influence the parents of the current revision (if |
|
56 |
a parent path is a branch according but not according to another). |
|
103
by Jelmer Vernooij
Update docs. |
57 |
|
389.1.1
by Jelmer Vernooij
Add specification for version 3 |
58 |
Since '/' and whitespace are forbidden in revision ids, the branch paths |
59 |
are all urlencoded. Example revision id for branches/foobranch: |
|
177
by Jelmer Vernooij
Add notes on urlencoding. |
60 |
|
454
by Jelmer Vernooij
Merge documentation improvements. |
61 |
``svn-v3-trunk-1:0c0555d6-39d7-0310-84fc-f1cc0bd64818:branches%2Ffoobranch:14323`` |
177
by Jelmer Vernooij
Add notes on urlencoding. |
62 |
|
421.1.1
by Jelmer Vernooij
Initial work on push and support for setting revision id during commit. |
63 |
It is also possible that the revision id for a particular revision is |
64 |
stored in a revision property. To guarantee that the meaning of a revision id |
|
65 |
does not change, this revision id is only valid within a specific version |
|
66 |
of the mappings. |
|
67 |
||
658
by Jelmer Vernooij
Update mapping specs wrt revisions properties. |
68 |
To override the revision id this way, set the branch path file property: |
421.1.1
by Jelmer Vernooij
Initial work on push and support for setting revision id during commit. |
69 |
|
787
by Jelmer Vernooij
Fix formatting. |
70 |
``bzr:revision-id-v%d:%s`` (where %d is the current mapping version and %s is |
71 |
the name of the branching scheme in use) |
|
421.1.1
by Jelmer Vernooij
Initial work on push and support for setting revision id during commit. |
72 |
|
658
by Jelmer Vernooij
Update mapping specs wrt revisions properties. |
73 |
to the bzr revision number following by a space and the revision id. This |
481
by Jelmer Vernooij
Store bzr revnum in revision-id-vX property, should make revid-to-revno lookups a lot cheaper (and not scale by the size of history). |
74 |
property should only be honored for the revision in which it was set, as |
75 |
subversion will not erase the property for subsequent commits. |
|
421.1.1
by Jelmer Vernooij
Initial work on push and support for setting revision id during commit. |
76 |
|
451
by Jelmer Vernooij
Clarify what is considered a revision and what isn't. |
77 |
A (path,revnum) tuple is valid if: |
787
by Jelmer Vernooij
Fix formatting. |
78 |
|
79 |
- path is valid according to the branching scheme |
|
80 |
- either path, revnum or one of its children was touched in the particular |
|
451
by Jelmer Vernooij
Clarify what is considered a revision and what isn't. |
81 |
revision |
82 |
||
658
by Jelmer Vernooij
Update mapping specs wrt revisions properties. |
83 |
If possible, the Subversion revision property ``bzr:revision-id`` should be |
84 |
set to the revision id. The revision property ``bzr:root`` should be set to |
|
85 |
the root path of the revision and revision property ``bzr:scheme`` should be |
|
86 |
set to the name of the branching scheme. |
|
87 |
||
402.1.49
by Jelmer Vernooij
Convert mapping text to LaTeX. |
88 |
File ids |
836
by Jelmer Vernooij
Fix syntax, add ToC. |
89 |
-------- |
103
by Jelmer Vernooij
Update docs. |
90 |
|
91 |
Subversion does not use file ids. It is not possible to know whether a file in |
|
92 |
revision X and a file in revision Y are the same without traversing over all |
|
93 |
the revisions between X and Y. |
|
94 |
||
236.1.13
by Jelmer Vernooij
Make testsuite pass with unique root ids. |
95 |
File ids use the following syntax: |
96 |
||
454
by Jelmer Vernooij
Merge documentation improvements. |
97 |
``<REVNO>@<UUID>:<BRANCHPATH>:<PATH>`` |
236.1.13
by Jelmer Vernooij
Make testsuite pass with unique root ids. |
98 |
|
389.1.5
by Jelmer Vernooij
Fix some of the file id tests |
99 |
Since / is forbidden in file ids, all characters are urlencoded. |
103
by Jelmer Vernooij
Update docs. |
100 |
|
236.1.13
by Jelmer Vernooij
Make testsuite pass with unique root ids. |
101 |
The same rules apply to the roots of branches. This means there is no |
102 |
predefined file id for tree roots. |
|
103 |
||
236.1.15
by Jelmer Vernooij
Add notes about file id mappings. |
104 |
Alternatively, these file ids can be mapped to more specific file ids. Such |
658
by Jelmer Vernooij
Update mapping specs wrt revisions properties. |
105 |
a map should be stored in the 'bzr:file-ids' file property that is set on the |
106 |
branch path and, if possible, as revision property ``bzr:file-ids``. |
|
236.1.15
by Jelmer Vernooij
Add notes about file id mappings. |
107 |
|
108 |
The bzr:file-ids property should contain a list of mappings. Entries are |
|
236.1.16
by Jelmer Vernooij
Start storing file id mappings. |
109 |
separated by newlines. The path in the branch and new file-id are separated |
110 |
by a tab. |
|
111 |
||
112 |
Given, the path, the revision the mapping was added, the repository uuid |
|
113 |
and the path the property is set on the (the branch path), the original |
|
114 |
file id can be determined. |
|
115 |
||
116 |
Tabs, newlines and percent signs in path will be urlencoded. |
|
236.1.15
by Jelmer Vernooij
Add notes about file id mappings. |
117 |
|
118 |
Neither the original nor the target file id may occur more than once. |
|
119 |
||
120 |
The entries are sorted by revnum (highest revnum last). Within a specific |
|
121 |
revnum, the order is not specified. |
|
122 |
||
602
by Jelmer Vernooij
Add another test, update docs. |
123 |
File id mappings can only change if something about the metadata of a file |
124 |
changed: it is in no way related to the contents of that file. |
|
296
by Jelmer Vernooij
Add more tests demonstrating weird behaviour in the subversion libraries. |
125 |
|
126 |
If a file is being replaced by a copy of itself in an older revision it will |
|
127 |
receive a new file id. |
|
128 |
||
334
by Jelmer Vernooij
Reduce threshold for switching to checksums. |
129 |
If the file id generated is longer than 150 bytes, the following format will |
332.1.1
by Jelmer Vernooij
Use checksums for the path in case the file id is too long (fixes #77453). |
130 |
be used: |
131 |
||
389.1.5
by Jelmer Vernooij
Fix some of the file id tests |
132 |
<REVNO>@<UUID>:<BRANCH>;<SHA1> |
332.1.1
by Jelmer Vernooij
Use checksums for the path in case the file id is too long (fixes #77453). |
133 |
|
389.1.5
by Jelmer Vernooij
Fix some of the file id tests |
134 |
where <SHA1> is the sha1 of the file's path. |
332.1.1
by Jelmer Vernooij
Use checksums for the path in case the file id is too long (fixes #77453). |
135 |
|
144
by Jelmer Vernooij
Update details on tracking ancestry. |
136 |
NEXT VERSION: Special rules are applied to make sure that renames are tracked. |
103
by Jelmer Vernooij
Update docs. |
137 |
|
402.1.49
by Jelmer Vernooij
Convert mapping text to LaTeX. |
138 |
Properties |
836
by Jelmer Vernooij
Fix syntax, add ToC. |
139 |
---------- |
103
by Jelmer Vernooij
Update docs. |
140 |
|
141 |
SVN allows setting properties on versioned files and also interprets several |
|
142 |
of these properties. |
|
143 |
||
144 |
"svn:executable" is mapped to bzr's executable bit. |
|
145 |
||
144
by Jelmer Vernooij
Update details on tracking ancestry. |
146 |
"svn:ignore" is currently ignored. |
147 |
||
148 |
"svn:mime-type" is currently ignored. |
|
149 |
||
150 |
"svn:special" for symlinks is interpreted and mapped to symlinks in bzr. |
|
177
by Jelmer Vernooij
Add notes on urlencoding. |
151 |
|
152 |
"svk:merge" is understood and set where possible. |
|
144
by Jelmer Vernooij
Update details on tracking ancestry. |
153 |
|
402.1.49
by Jelmer Vernooij
Convert mapping text to LaTeX. |
154 |
Ancestry Information |
836
by Jelmer Vernooij
Fix syntax, add ToC. |
155 |
-------------------- |
103
by Jelmer Vernooij
Update docs. |
156 |
|
144
by Jelmer Vernooij
Update details on tracking ancestry. |
157 |
Ancestry in Subversion is linear. Most revisions have just one parent. Files |
658
by Jelmer Vernooij
Update mapping specs wrt revisions properties. |
158 |
can be copied, moved or merged from other branches, which can result in partial |
159 |
merges that bzr doesn't support at the moment. |
|
103
by Jelmer Vernooij
Update docs. |
160 |
|
144
by Jelmer Vernooij
Update details on tracking ancestry. |
161 |
Whenever a Bazaar commit to Subversion has more than one parent (merges two |
602
by Jelmer Vernooij
Add another test, update docs. |
162 |
revisions), it will add a line to the 'bzr:ancestry:vX-SCHEME' property set on |
163 |
the branch path. The format of these lines is: |
|
144
by Jelmer Vernooij
Update details on tracking ancestry. |
164 |
|
165 |
([\tPARENT-REV-ID]+)\n |
|
166 |
||
658
by Jelmer Vernooij
Update mapping specs wrt revisions properties. |
167 |
If possible, the list of merges will also be stored in the Subversion revision |
168 |
property ``bzr:merges``. |
|
169 |
||
144
by Jelmer Vernooij
Update details on tracking ancestry. |
170 |
This property should be considered add-only. This way, it is |
171 |
possible to know the parents of a revision when running checkout or |
|
172 |
diff, because the Subversion API will mark the property as modified. The |
|
173 |
parents can be obtained by simply looking at the last line. |
|
174 |
||
175 |
Other operations (outside of checkouts) can obtain the revision |
|
176 |
parents by simply running diff on the property between the current and the |
|
177 |
previous revision of the branch path. |
|
178 |
||
179 |
Bazaar will also set 'svk:merge' if one of the merges is originally from a |
|
180 |
Subversion branch and not on the mainline. If 'svk:merge' is changed and |
|
578
by Jelmer Vernooij
Rename bzr:merge -> bzr:ancestry:v3-SCHEME. |
181 |
'bzr:ancestry:...' didn't, the diff in 'svk:merge' is also used to obtain the |
144
by Jelmer Vernooij
Update details on tracking ancestry. |
182 |
parents of a commit. |
183 |
||
402.1.49
by Jelmer Vernooij
Convert mapping text to LaTeX. |
184 |
This means svk and bzr *should be* interoperable. However, there are no tests |
144
by Jelmer Vernooij
Update details on tracking ancestry. |
185 |
for this yet. |
103
by Jelmer Vernooij
Update docs. |
186 |
|
402.1.49
by Jelmer Vernooij
Convert mapping text to LaTeX. |
187 |
Revision properties |
836
by Jelmer Vernooij
Fix syntax, add ToC. |
188 |
------------------- |
229
by Jelmer Vernooij
Add note about revprops |
189 |
|
658
by Jelmer Vernooij
Update mapping specs wrt revisions properties. |
190 |
If possible, the Bazaar revision metadata should be stored in Subversion |
191 |
revision properties. The names of the revision properties are: |
|
192 |
||
193 |
- committer: ``bzr:committer`` |
|
194 |
- timestamp: ``svn:original-date`` |
|
195 |
||
196 |
All custom revision properties are prefixed by ``bzr:revprop:`` |
|
197 |
||
198 |
Bazaar revision metadata is also stored in a Subversion revision property |
|
421.1.21
by Jelmer Vernooij
Reduce the number of properties used. |
199 |
``bzr:revision-info``. The format of this property is the same as used |
200 |
by version 0.9 of the bundle format. |
|
229
by Jelmer Vernooij
Add note about revprops |
201 |
|
658
by Jelmer Vernooij
Update mapping specs wrt revisions properties. |
202 |
|
402.1.49
by Jelmer Vernooij
Convert mapping text to LaTeX. |
203 |
Signatures |
836
by Jelmer Vernooij
Fix syntax, add ToC. |
204 |
---------- |
103
by Jelmer Vernooij
Update docs. |
205 |
|
602
by Jelmer Vernooij
Add another test, update docs. |
206 |
NEXT VERSION: GPG Signatures for commits will be stored in the SVN revision |
207 |
property 'bzr:gpg-signature'. |
|
227
by Jelmer Vernooij
Update mapping document for v2 |
208 |
|
402.1.49
by Jelmer Vernooij
Convert mapping text to LaTeX. |
209 |
Revisions |
836
by Jelmer Vernooij
Fix syntax, add ToC. |
210 |
--------- |
227
by Jelmer Vernooij
Update mapping document for v2 |
211 |
|
212 |
Revision 1 was the original version of this document. |
|
213 |
||
236.1.15
by Jelmer Vernooij
Add notes about file id mappings. |
214 |
Revision 2 enforces UTF-8-valid characters for everything except file |
227
by Jelmer Vernooij
Update mapping document for v2 |
215 |
contents. |
236.1.15
by Jelmer Vernooij
Add notes about file id mappings. |
216 |
|
389.1.1
by Jelmer Vernooij
Add specification for version 3 |
217 |
Revision 3 changed the file id format, changed the urlencoding to be |
218 |
uppercased, changed the separator between uuids and branch paths in the |
|
421.1.1
by Jelmer Vernooij
Initial work on push and support for setting revision id during commit. |
219 |
revision id from "-" to ":", added the branching scheme to the revision id |
489
by Jelmer Vernooij
Support custom branching schemes and make the branching scheme name part of the |
220 |
and added the bzr:revision-id-vX:YY property. |
236.1.30
by Jelmer Vernooij
merge upstream changes. |
221 |
|
236.1.15
by Jelmer Vernooij
Add notes about file id mappings. |
222 |
Revision 3 uses real file ids for the tree root rather than the hardcoded |
223 |
"TREE_ROOT" and adds the file id map. |
|
454
by Jelmer Vernooij
Merge documentation improvements. |
224 |
|
658
by Jelmer Vernooij
Update mapping specs wrt revisions properties. |
225 |
Revision 4 adds revision properties in addition to file properties. |
847
by Jelmer Vernooij
Improve ReST formatting. |
226 |
|
227 |
.. |
|
228 |
vim: ft=rest |