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