Bazaar Data Migration Guide

Overview

Introduction

This guide provides general advice and suggested procedures for migrating projects from other version control systems into Bazaar. Keeping in mind that different tools store different metadata, data conversion is often less than perfect. In most cases though, the really important stuff - who changed what when - will migrate successfully.

This section introduces some general themes to keep in mind when doing a data migration. It is recommended reading regardless of the source tool. Subsequent sections discuss the specifics of doing a conversion for various tools. Central VCS tools are covered first, then distributed VCS ones. Roughly speaking, tools are presented in age order within each group. If you find migrating to Bazaar directly unsuccessful, try migrating to a more recent tool first and migrating to Bazaar as a second step.

The high level process

There are 2 classes of migration tools available:

• Single-step source-to-Bazaar conversion.
• Conversion via 2 steps:
  1. Export from source tool to a ‘dump’ file.
  2. Import of the dump file into Bazaar.

While the first class of tool is great for small projects, the second approach has numerous advantages:

• A de-facto standard has emerged (“fast-import”) for the dump file format so developers closely familiar with each major tool are building matching importers and exporters. As a consequence, the combination of fast-exporter + fast-importer is often more reliable now than using dedicated source-to-target tools.
• For large projects, you may need to run the conversion more than once until you’re happy with the results. Extracting data from many source tools can take a long time so it’s useful to do that just the once and to repeat the import step multiple times if required.
• After exporting but before importing, you may wish to transform the dump file in certain ways. For example, your current repository might have large binary files that made sense to put under version control years ago (DLLs, installer executables, etc.), but you’d prefer to remove them from your new repository going forward.

For these reasons, this guide recommends the 2-step approach when it is available. The general recipe is:

bzr fast-export-from-xxx source-repository project.fi
bzr fast-import project.fi project.bzr

The fast-export-from-xxx and fast-import commands are provided by the bzr-fastimport plugin, version 0.9 or later. If not included in the installer or package management system for your operating system, it can be downloaded from Launchpad, https://launchpad.net/bzr-fastimport.

Note

The various fast-export-from-xxx commands still call the native xxx-fast-export tools under the covers. The wrapper commands are provided so that casual users don’t need to learn the myriad of options available and can proceed knowing that the native tools will be called in the recommended way. You are welcome to use the native xxx-fast-export tools directly if you prefer.

Making the most of the opportunity

As explained earlier, migrating metadata from one tool to another is an ideal time to clean up that metadata if you wish to do so. The bzr-fastimport plugin provides a special command for doing exactly that, fast-import-filter. This command takes a fast-import dump file as input and generates one as output, filtering the data according to various options.

See fast-import-filter for more details on using this command.

Central VCS tools

• CVS
• Visual SourceSafe
• ClearCase
• Perforce
• Subversion

Distributed VCS tools

• BitKeeper
• GNU Arch
• Darcs
• Monotone
• Git
• Mercurial

Command reference