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