This page describes ways to handle tracking an upstream project, that doesn't use Bazaar for its version control.
Overall, what you want to do is get ahold of a Bazaar branch, which has the exact contents of Upstream and then create a new working branch for yourself. You keep the Upstream branch up-to-date, and your changes in a separate branch. There are several ways to get a pristine upstream branch.
Your basic filesystem layout then looks like:
project/ upstream/ <upstream project files> my-branch/ <shares some history with upstream, but also has your own commits>
Then as you are working, you might need to update the upstream/ files, and use bzr merge to bring them into your working branch. In general, you should not be doing a bzr commit in upstream. As it is meant to be a pristine source of upstream's project.
Upstream uses Bazaar
Probably you wouldn't be here if this was the case, but it is reasonable to mention. It might be that upstream already maintains a Bazaar copy, even if their primary version control is something else. It doesn't hurt to ask around.
If you have an upstream Bazaar branch, then all you need is cd upstream; bzr pull to get the latest version of upstream, and see if you need to merge anything into your work.
Before you try to create your own upstream branch, you should search Launchpad to see if they have already converted your upstream project into a Bazaar branch. Launchpad supports converting from many different source systems for you, and keeping that source up-to-date with the latest changes.
Just register the project in Launchpad, and set the 'Trunk' series as being upstream. For more information, start here: http://help.launchpad.net/Code
Some plugins have been written that provide native support to Bazaar for non Bazaar systems. Specifically look at BzrForeignBranches and see if your upstream format is supported. If it is, read the details of the plugin more closely and you can get the benefits of using Bazaar, without having to manually convert upstream.
Converting and keeping history
Tailor is a tool which supports converting between many different RCS systems and preserving history. It also supports updating an existing conversion. It has some limitations (like only being able to convert the HEAD branch for CVS). But when setup properly, it will let you have a Bazaar branch, which mirrors all of the upstream history.
See the Tailor documentation for how to setup a conversion and keep it up-to-date.
CVSPSImport is a tool that converts directly from cvs to bzr. It is able to convert all branches, and should be much faster at converting.
Converting and ignoring history
A lot of these methods require quite a bit of setup, just to make a couple small changes. So one other possibility is to just create a new Bazaar branch of the current upstream sources. We will use CVS as the example source, but pretty much anything will work. This is the only time that you should be making commits in the upstream branch. And you should only be making commits that are pristine upstream changes.
Get a fresh checkout of upstream:
$ cvs -d:upstream:repository co project upstream
Create a new bzr branch in the same directory
$ cd upstream $ bzr init
Ignore the control files. We don't want to version those.
$ bzr ignore CVS
Add the rest of the files, and commit the project.
$ bzr add $ bzr commit -m "Initial upstream import"
Now create your own branch of this:
$ cd .. $ bzr branch upstream my-working-branch
Now you have a place to do your work.
From time to time, you will want to get any new changes from upstream, and integrate that into your changes.
$ cd upstream $ cvs update -dP $ bzr commit -m "Update from upstream" $ cd ../my-working-branch $ bzr merge ../upstream # review the changes, fix any conflicts $ bzr commit -m "[merge] from upstream"
At this point, there will be times when you want to know what changes you have versus upstream. The cleanest format is:
$ cd my-working-branch $ bzr diff -r ancestor:../upstream
This will generate the difference between your branch, and the common ancestor in upstream. That way you won't accidentally show the reverse differences for new changes in upstream, that you haven't merged yet.
For another view on this subject, see here: hacking-a-project-with-bzr
The above setup is inefficient on disk space when branching many copies of upstream. See SharedRepositoryTutorial for how to avoid storing duplicate revisions.
First, you create a shared repository
$ bzr init-repo --trees foobar-repo
The next step is to check out upstream FooBar from CVS, into a directory in the shared repository.
$ cd foobar-repo $ cvs checkout foobar foobar-upstream
Next, the CVS working copy needs to become a bzr branch such that revisions go into the shared repository. Also, the files need to be added and committed.
$ bzr init foobar-upstream $ cd foobar-upstream $ bzr add $ bzr commit -m"Initial checkin of upstream CVS"
And now branching is easy. Make sure you are in the foobar-repo directory, and branching is cheap:
$ bzr branch foobar-upstream foobar-beta-feature