mapping.txt

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