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 == Branch paths ==
  11
  12 It is hard to know, given a SVN URL, to figure out what branch a particular
  13 file is in. Other then the convention that branches are named 'trunk' and
  14 'branches/*', there is no way to automatically find out what a branch is.
  15 Finding out what a branch is and what is not is done by a BranchingScheme
  16 implementation. At the moment, the following branching schemes are available:
  17
  18  * NoBranchingScheme: The top-level directory in the repository is a branch.
  19                     (consequence of this is that there is only one branch total)
  20
  21  * TrunkBranchingScheme: There is a directory structure with 'trunk',
  22    'branches', and 'tags' directories as common in Subversion-based projects.
  23    These directories can be nested (e.g. subproject1/trunk) inside the
  24    repository. The level of nesting is stored.
  25
  26  * ListBranchingScheme: There is a list of branches. This branching
  27    scheme is present in the code, but is never used automatically (yet).
  28
  29 The branching scheme can be explicitly specified or automatically guessed.
  30 The guessing algorithm currently works as follows and is based on paths
  31 relative to the repository root:
  32
  33  * Look for 'trunk', 'branches' or 'tags' inside the path - if found,
  34    create a TrunkBranchingScheme with the found level of nesting.
  35
  36  * Assume NoBranchingScheme
  37
  38 Branching scheme names can not contain colons.
  39
  40 == Revision ids ==
  41
  42 An easy way to generate globally unique and reproducible revision ids is to
  43 simply combine the repositories UUID and commit revision number.
  44
  45 However, this can lead to overlap in revision ids when a commit touches more
  46 then one branch (something that is possible in SVN). This can be fixed by
  47 including the branch path (trunk, branches/SAMBA_4_0, etc) in the
  48 revision-id. Example revision id:
  49
  50 {{{
  51 svn-v3-trunk:0c0555d6-39d7-0310-84fc-f1cc0bd64818:trunk:14323
  52 }}}
  53
  54 The version number is used to distinguish between versions of the mapping
  55 between Bazaar and Subversion. The mapping will change when previously
  56 unsupported features are added to Bazaar (see below), or when a bug in bzr-svn
  57 is fixed that may affect the mappings.
  58
  59 Once branching schemes can be manually specified, also needs to contain
  60 branching scheme as it might influence the parents of the current revision (if
  61 a parent path is a branch according but not according to another).
  62
  63 Since '/' and whitespace are forbidden in revision ids, the branch paths
  64 are all urlencoded. Example revision id for branches/foobranch:
  65
  66 {{{
  67 svn-v3-trunk-1:0c0555d6-39d7-0310-84fc-f1cc0bd64818:branches%2Ffoobranch:14323
  68 }}}
  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 == File ids ==
  89
  90 Subversion does not use file ids. It is not possible to know whether a file in
  91 revision X and a file in revision Y are the same without traversing over all
  92 the revisions between X and Y.
  93
  94 File ids use the following syntax:
  95
  96 <REVNO>@<UUID>:<BRANCHPATH>:<PATH>
  97
  98 Since / is forbidden in file ids, all characters are urlencoded.
  99
 100 The same rules apply to the roots of branches. This means there is no
 101 predefined file id for tree roots.
 102
 103 Alternatively, these file ids can be mapped to more specific file ids. Such
 104 a map should be stored in the `bzr:file-ids' property that is set on the
 105 branch path.
 106
 107 The bzr:file-ids property should contain a list of mappings. Entries are
 108 separated by newlines. The path in the branch and new file-id are separated
 109 by a tab.
 110
 111 Given, the path, the revision the mapping was added, the repository uuid
 112 and the path the property is set on the (the branch path), the original
 113 file id can be determined.
 114
 115 Tabs, newlines and percent signs in path will be urlencoded.
 116
 117 Neither the original nor the target file id may occur more than once.
 118
 119 The entries are sorted by revnum (highest revnum last). Within a specific
 120 revnum, the order is not specified.
 121
 122 File id mappings can only change if something about the metadata of a file changed: it
 123 is in no way related to the contents of that file.
 124
 125 If a file is being replaced by a copy of itself in an older revision it will
 126 receive a new file id.
 127
 128 If the file id generated is longer than 150 bytes, the following format will
 129 be used:
 130
 131 <REVNO>@<UUID>:<BRANCH>;<SHA1>
 132
 133 where <SHA1> is the sha1 of the file's path.
 134
 135 NEXT VERSION: Special rules are applied to make sure that renames are tracked.
 136
 137 == Properties ==
 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 == Ancestry Information ==
 153
 154 Ancestry in Subversion is linear. Most revisions have just one parent. Files
 155 can be copied, moved or merged from other branches, which can result in partial merges
 156 that bzr doesn't support at the moment.
 157
 158 Whenever a Bazaar commit to Subversion has more than one parent (merges two
 159 revisions), it will add a line to the 'bzr:merge' property set on the
 160 branch path. The format of these lines is:
 161
 162 ([\tPARENT-REV-ID]+)\n
 163
 164 This property should be considered add-only. This way, it is
 165 possible to know the parents of a revision when running checkout or
 166 diff, because the Subversion API will mark the property as modified. The
 167 parents can be obtained by simply looking at the last line.
 168
 169 Other operations (outside of checkouts) can obtain the revision
 170 parents by simply running diff on the property between the current and the
 171 previous revision of the branch path.
 172
 173 Bazaar will also set 'svk:merge' if one of the merges is originally from a
 174 Subversion branch and not on the mainline. If 'svk:merge' is changed and
 175 'bzr:merge' didn't, the diff in 'svk:merge' is also used to obtain the
 176 parents of a commit.
 177
 178 This means svk and bzr _should be_ interoperable. However, there are no tests
 179 for this yet.
 180
 181 == Revision properties ==
 182
 183 Bazaar revision properties are stored in the file properties of the
 184 branch path in Subversion. Their names are prefixed with "bzr:revprop:"
 185
 186 == Signatures ==
 187
 188 NEXT VERSION: GPG Signatures for commits will be stored in the SVN revision property 'bzr:gpg-signature'.
 189
 190 = Revisions =
 191
 192 Revision 1 was the original version of this document.
 193
 194 Revision 2 enforces UTF-8-valid characters for everything except file
 195 contents.
 196
 197 Revision 3 changed the file id format, changed the urlencoding to be
 198 uppercased, changed the separator between uuids and branch paths in the
 199 revision id from "-" to ":", added the branching scheme to the revision id
 200 and added the bzr:revision-id-vX property.
 201
 202 Revision 3 uses real file ids for the tree root rather than the hardcoded
 203 "TREE_ROOT" and adds the file id map.