mapping.txt

   1 This document specifies mapping between Subversion and Bazaar semantics.
   2
   3 Revision: 1
   4 Jelmer Vernooij <jelmer@samba.org>, June 2006.
   5
   6 == Branch paths ==
   7
   8 It is hard to know, given a SVN URL, to figure out what branch a particular
   9 file is in. Other then the convention that branches are named 'trunk' and
  10 'branches/*', there is no way to automatically find out what a branch is.
  11 Finding out what a branch is and what is not is done by a BranchingScheme
  12 implementation. At the moment, the following branching schemes are available:
  13
  14  * NoBranchingScheme: The top-level directory in the repository is a branch.
  15                     (consequence of this is that there is only one branch total)
  16
  17  * TrunkBranchingScheme: There is a directory structure with 'trunk',
  18    'branches', and 'tags' directories as common in Subversion-based projects.
  19    These directories can be nested (e.g. subproject1/trunk) inside the
  20    repository. The level of nesting is stored.
  21
  22  * ListBranchingScheme: There is a list of branches. This branching
  23    scheme is present in the code, but is never used automatically (yet).
  24
  25 The branching scheme can be explicitly specified or automatically guessed.
  26 The guessing algorithm currently works as follows and is based on paths
  27 relative to the repository root:
  28
  29  * Look for 'trunk', 'branches' or 'tags' inside the path - if found,
  30    create a TrunkBranchingScheme with the found level of nesting.
  31
  32  * Assume NoBranchingScheme
  33
  34 NEXT VERSION: Allow specifying the branching scheme in ~/.bazaar/locations.conf.
  35
  36 == Revision ids ==
  37
  38 An easy way to generate globally unique and reproducible revision ids is to
  39 simply combine the repositories UUID and commit revision number.
  40
  41 However, this can lead to overlap in revision ids when a commit touches more
  42 then one branch (something that is possible in SVN). This can be fixed by
  43 including the branch path (trunk, branches/SAMBA_4_0, etc) in the
  44 revision-id. Example revision id:
  45
  46 {{{
  47 svn-v1:14323@0c0555d6-39d7-0310-84fc-f1cc0bd64818-trunk
  48 }}}
  49
  50 The version number is used to distinguish between versions of the mapping
  51 between Bazaar and Subversion. The mapping will change when previously
  52 unsupported features are added to Bazaar (see below), or when a bug in bzr-svn
  53 is fixed that may affect the mappings.
  54
  55 Once branching schemes can be manually specified, also needs to contain
  56 branching scheme as it might influence the parents of the current revision (if
  57 a parent path is a branch according but not according to another).
  58
  59 Since '/' and whitespaces are forbidden in revision ids, the '/', '-', '%'
  60 and whitespace characters are all urlencoded. Example revision id for
  61 branches/foobranch:
  62
  63 {{{
  64 svn-v1:14323@0c0555d6-39d7-0310-84fc-f1cc0bd64818-branches%2ffoobranch
  65 }}}
  66
  67 == File ids ==
  68
  69 Subversion does not use file ids. It is not possible to know whether a file in
  70 revision X and a file in revision Y are the same without traversing over all
  71 the revisions between X and Y.
  72
  73 Fileids are generated by concatenating a revision id and the path of the file
  74 from the revision it was added or was copied from another file.
  75
  76 Since / is forbidden in revision ids, the '/', '-', '%' and all whitespace
  77 characters are urlencoded.
  78
  79 NEXT VERSION: Special rules are applied to make sure that renames are tracked.
  80
  81 == Properties ==
  82
  83 SVN allows setting properties on versioned files and also interprets several
  84 of these properties.
  85
  86 "svn:executable" is mapped to bzr's executable bit.
  87
  88 "svn:ignore" is currently ignored.
  89
  90 "svn:mime-type" is currently ignored.
  91
  92 "svn:special" for symlinks is interpreted and mapped to symlinks in bzr.
  93
  94 "svk:merge" is understood and set where possible.
  95
  96 == Ancestry Information ==
  97
  98 Ancestry in Subversion is linear. Most revisions have just one parent. Files
  99 can be copied, moved or merged from other branches, which can result in partial merges
 100 that bzr doesn't support at the moment.
 101
 102 Whenever a Bazaar commit to Subversion has more than one parent (merges two
 103 revisions), it will add a line to the 'bzr:merge' property set on the
 104 branch path. The format of these lines is:
 105
 106 ([\tPARENT-REV-ID]+)\n
 107
 108 This property should be considered add-only. This way, it is
 109 possible to know the parents of a revision when running checkout or
 110 diff, because the Subversion API will mark the property as modified. The
 111 parents can be obtained by simply looking at the last line.
 112
 113 Other operations (outside of checkouts) can obtain the revision
 114 parents by simply running diff on the property between the current and the
 115 previous revision of the branch path.
 116
 117 Bazaar will also set 'svk:merge' if one of the merges is originally from a
 118 Subversion branch and not on the mainline. If 'svk:merge' is changed and
 119 'bzr:merge' didn't, the diff in 'svk:merge' is also used to obtain the
 120 parents of a commit.
 121
 122 This means svk and bzr _should be_ interoperable. However, there are no tests
 123 for this yet.
 124
 125 == Signatures ==
 126
 127 NEXT VERSION: GPG Signatures for commits will be stored in the SVN revision property 'bzr:gpg-signature'.