Fix bug in revid caching.
[jelmer/subvertpy.git] / mapping.txt
1 This document specifies mapping between Subversion and Bazaar semantics.
2
3 Revision: 3
4 Jelmer Vernooij <jelmer@samba.org>, June 2006.
5 Updated October 2006.
6 Updated December 2006.
7 Updated January 2007.
8 Updated February 2007.
9
10 ============
11 Branch paths
12 ============
13
14 It is hard to know, given a SVN URL, to figure out what branch a particular 
15 file is in. Other then the convention that branches are named 'trunk' and 
16 'branches/\*', there is no way to automatically find out what a branch is.
17 Finding out what a branch is and what is not is done by a BranchingScheme 
18 implementation. At the moment, the following branching schemes are available:
19
20 - NoBranchingScheme: The top-level directory in the repository is a branch.
21   (consequence of this is that there is only one branch total)
22
23 - TrunkBranchingScheme: There is a directory structure with 'trunk', 
24   'branches', and 'tags' directories as common in Subversion-based projects.
25   These directories can be nested (e.g. subproject1/trunk) inside the 
26   repository. The level of nesting is stored.
27
28 - ListBranchingScheme: There is a list of branches. This branching 
29   scheme is present in the code, but is never used automatically (yet).
30
31 The branching scheme can be explicitly specified or automatically guessed. 
32 The guessing algorithm currently works as follows and is based on paths 
33 relative to the repository root:
34
35 - Look for 'trunk', 'branches' or 'tags' inside the path - if found, 
36   create a TrunkBranchingScheme with the found level of nesting.
37
38 - Assume NoBranchingScheme
39
40 Branching scheme names can not contain colons.
41
42 ============
43 Revision ids
44 ============
45
46 An easy way to generate globally unique and reproducible revision ids is to 
47 simply combine the repositories UUID and commit revision number. 
48
49 However, this can lead to overlap in revision ids when a commit touches more 
50 then one branch (something that is possible in SVN). This can be fixed by 
51 including the branch path (trunk, branches/SAMBA_4_0, etc) in the 
52 revision-id. Example revision id:
53
54 ``svn-v3-trunk:0c0555d6-39d7-0310-84fc-f1cc0bd64818:trunk:14323``
55
56 The version number is used to distinguish between versions of the mapping 
57 between Bazaar and Subversion. The mapping will change when previously 
58 unsupported features are added to Bazaar (see below), or when a bug in bzr-svn 
59 is fixed that may affect the mappings.
60
61 Once branching schemes can be manually specified, also needs to contain 
62 branching scheme as it might influence the parents of the current revision (if 
63 a parent path is a branch according but not according to another).
64
65 Since '/' and whitespace are forbidden in revision ids, the branch paths
66 are all urlencoded. Example revision id for branches/foobranch:
67
68 ``svn-v3-trunk-1:0c0555d6-39d7-0310-84fc-f1cc0bd64818:branches%2Ffoobranch:14323``
69
70 It is also possible that the revision id for a particular revision is 
71 stored in a revision property. To guarantee that the meaning of a revision id 
72 does not change, this revision id is only valid within a specific version 
73 of the mappings.
74
75 To override the revision id this way, set the revision property:
76
77 bzr:revision-id-v%d (where %d is the current mapping version) 
78
79 to the revision id. This property should only be honored for the revision 
80 in which it was set, as subversion will not erase the property 
81 for subsequent commits.
82
83 A (path,revnum) tuple is valid if:
84 * path is valid according to the branching scheme
85 * either path,revnum or one of its children was touched in the particular 
86   revision
87
88 ========
89 File ids
90 ========
91
92 Subversion does not use file ids. It is not possible to know whether a file in 
93 revision X and a file in revision Y are the same without traversing over all 
94 the revisions between X and Y.
95
96 File ids use the following syntax:
97
98 ``<REVNO>@<UUID>:<BRANCHPATH>:<PATH>``
99
100 Since / is forbidden in file ids, all characters are urlencoded.
101
102 The same rules apply to the roots of branches. This means there is no 
103 predefined file id for tree roots.
104
105 Alternatively, these file ids can be mapped to more specific file ids. Such 
106 a map should be stored in the 'bzr:file-ids' property that is set on the 
107 branch path.
108
109 The bzr:file-ids property should contain a list of mappings. Entries are 
110 separated by newlines. The path in the branch and new file-id are separated 
111 by a tab.
112
113 Given, the path, the revision the mapping was added, the repository uuid 
114 and the path the property is set on the (the branch path), the original 
115 file id can be determined.  
116
117 Tabs, newlines and percent signs in path will be urlencoded.
118
119 Neither the original nor the target file id may occur more than once. 
120
121 The entries are sorted by revnum (highest revnum last). Within a specific 
122 revnum, the order is not specified.
123
124 File id mappings can only change if something about the metadata of a file changed: it 
125 is in no way related to the contents of that file.
126
127 If a file is being replaced by a copy of itself in an older revision it will 
128 receive a new file id.
129
130 If the file id generated is longer than 150 bytes, the following format will 
131 be used:
132
133 <REVNO>@<UUID>:<BRANCH>;<SHA1>
134
135 where <SHA1> is the sha1 of the file's path.
136
137 NEXT VERSION: Special rules are applied to make sure that renames are tracked.
138
139 ==========
140 Properties
141 ==========
142
143 SVN allows setting properties on versioned files and also interprets several 
144 of these properties. 
145
146 "svn:executable" is mapped to bzr's executable bit. 
147
148 "svn:ignore" is currently ignored.
149
150 "svn:mime-type" is currently ignored.
151
152 "svn:special" for symlinks is interpreted and mapped to symlinks in bzr.
153
154 "svk:merge" is understood and set where possible.
155
156 ====================
157 Ancestry Information
158 ====================
159
160 Ancestry in Subversion is linear. Most revisions have just one parent. Files 
161 can be copied, moved or merged from other branches, which can result in partial merges 
162 that bzr doesn't support at the moment.
163
164 Whenever a Bazaar commit to Subversion has more than one parent (merges two 
165 revisions), it will add a line to the 'bzr:merge' property set on the 
166 branch path. The format of these lines is:
167
168 ([\tPARENT-REV-ID]+)\n
169
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 
181 'bzr:merge' didn't, the diff in 'svk:merge' is also used to obtain the 
182 parents of a commit.
183
184 This means svk and bzr *should be* interoperable. However, there are no tests 
185 for this yet. 
186
187 ===================
188 Revision properties
189 ===================
190
191 Bazaar revision metadata is stored in a Subversion revision property 
192 ``bzr:revision-info``. The format of this property is the same as used 
193 by version 0.9 of the bundle format.
194
195 ==========
196 Signatures
197 ==========
198
199 NEXT VERSION: GPG Signatures for commits will be stored in the SVN revision property 'bzr:gpg-signature'. 
200
201 =========
202 Revisions
203 =========
204
205 Revision 1 was the original version of this document.
206
207 Revision 2 enforces UTF-8-valid characters for everything except file 
208 contents.
209
210 Revision 3 changed the file id format, changed the urlencoding to be 
211 uppercased, changed the separator between uuids and branch paths in the 
212 revision id from "-" to ":", added the branching scheme to the revision id 
213 and added the bzr:revision-id-vX property.
214
215 Revision 3 uses real file ids for the tree root rather than the hardcoded 
216 "TREE_ROOT" and adds the file id map.
217
218 =======
219 Authors
220 =======
221 Jelmer Vernooij <jelmer@samba.org>