← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/admin-guide/migration.txt

Merge the 0.17 fixes back into bzr.dev

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/admin-guide/migration.txt
1
 
Migration
2
 
=========
3
 
 
4
 
Migrating between version control systems can be a complicated process, and
5
 
Bazaar has extensive documentation on the process at 
6
 
http://doc.bazaar-vcs.org/migration/en and we won't attempt to repeat that
7
 
here.  We will try to give a few motivating examples for conversion from
8
 
Mercurial and Subversion.
9
 
 
10
 
Fast Import
11
 
-----------
12
 
 
13
 
In many projects wishing to use Bazaar, there is pre-existing history for the
14
 
codebase that should be taken into consideration.  Bazaar leverages an
15
 
interchange format originally developed for Git called `fast-import` to
16
 
provide migration strategies for many other version control systems.  To
17
 
work with fast-import files, Bazaar needs the `fastimport`_ plugin.  This can
18
 
be installed as with any Bazaar plugin.
19
 
 
20
 
.. _fastimport: http://launchpad.net/bzr-fastimport
21
 
 
22
 
The way that fast-import can be used for migration is to export the existing
23
 
history into a fast-import file, then use the ``bzr fast-import`` command.
24
 
The `fastimport` plugin includes exporters for Subversion, CVS, Git, Mercurial
25
 
and darcs, accessible as the ``fast-export-from-XXX`` commands.  Note that
26
 
``fast-import`` should not be used in a branch with existing history.
27
 
 
28
 
Assuming that ProjectX was first developed in Mercurial before switching to
29
 
Bazaar, and that the Mercurial repository is in ``/srv/hg/projectx``, the
30
 
following commands will import that history into a newly created ``trunk``
31
 
branch.  (Recall that in `Further Configuration
32
 
<simple-setups.html#further-configuration>`_ we created the
33
 
``/srv/bzr/projectx`` directory as a shared repository.)
34
 
 
35
 
::
36
 
 
37
 
  $ cd /srv/bzr/projectx
38
 
  $ bzr fast-export-from-hg ../../hg/projectx projectx.fi
39
 
  $ bzr init trunk
40
 
  $ bzr fast-import projectx.fi trunk
41
 
 
42
 
Subversion Conversion
43
 
---------------------
44
 
 
45
 
As the most common centralized version control system, migration from
46
 
Subversion is particularly important for any *new* version control system.
47
 
Bazaar's `svn`_ plugin provides tools for interaction with Subversion
48
 
projects.  In fact, Bazaar can be used transparently with projects stored in
49
 
Subversion, but that is beyond the scope of this document.  (See
50
 
http://doc.bazaar-vcs.org/en/migration/foreign/bzr-on-svn-projects.html for
51
 
more on that subject.)  What is relevant here is the ``svn-import`` command
52
 
provided by that plugin.  This can import an entire subversion repository
53
 
including tags and branches, particularly if they are stored in Subversion's
54
 
recommended directory structure: ``/tags/``, ``/branches/`` and ``/trunk/``.
55
 
 
56
 
This command has flexible ways to specify what paths within the Subversion
57
 
repository contain branches and which contain tags.  For example, the
58
 
recommended layout for Subversion projects (called ``trunk`` by the svn
59
 
plugin) could be specified in ``~/.bazaar/subversion.conf`` as
60
 
 
61
 
::
62
 
 
63
 
  [203ae883-c723-44c9-aabd-cb56e4f81c9a]
64
 
  branches = branches/*
65
 
  tags = tags/*
66
 
 
67
 
This allows substantially complicated Subversion repositories to be converted
68
 
into a set of separate Bazaar branches.  After installing the svn plugin, see
69
 
``bzr help svn-import`` and ``bzr help svn-layout``.
70
 
 
71
 
.. _svn: http://launchpad.net/bzr-svn
72
 
 
73
 
.. TODO: Legacy VCS to bzr sync.  Tailor?  Incremental conversions?