← 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

Major code cleanup.

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.canonical.com/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.canonical.com/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?