Migrating Valgrind to BitKeeper

Jeremy Fitzhardinge <jeremy@goop.org>

Valgrind has been using SourceForge's CVS repositories for some time now, but SF is becoming increasingly unreliable, and unavailable to most users.  Since one of the strengths of Valgrind's development has been the active testing and contribution of a large number of people, we need to maintain good availability of the development tree.  Also, CVS has a number of limitation which make it hard to work with.
I suggested, and Julian agrees, that we move to BitKeeper.  While it is a commercial product, there is a full-featured free version which has a fairly liberal license*.  BK has a lot of functional advantages over CVS, and BitMover (the company behind BitKeeper) provides free hosting at bkbits.net.
I have been maintaining an imported mirror of the Valgrind tree on bkbits.net, so the full development history of Valgrind is available to BK.

Setting up BitKeeper

  1. get a copy of BitKeeper from BitMover's website
  2. install it
  3. find a good place to put your repositories (I use ~/bk/valgrind)
  4. OK, now you have a working copy
  5. Now you can fetch a copy of the main Valgrind repository with: bk clone bk://valgrind.bkbits.net/valgrind. This is an anonymous pull, which does not allow you to push back to the server.
  6. Now might be a good time to browse Bitmover's documentation, especially the BK to CVS command comparison, CVS to BK translation and testdrive section.

Using BitKeeper

Getting write permission

If you connect anonymously to the BK server, you can download (pull) the sources, but you can't push your changes back.  If you're in this position, you can use bk send or bk export -tpatch to send a change set to someone who can check it in.

To get check-in permission, you need to send an ssh v1 public key to me (preferably as an attachment to prevent mangling), and I can install it.  Once it has been installed, you use a BK URL of the form: bk://valgrind@valgrind.bkbits.net/repo.

Getting help

bk help command will show the usage of a particular command.  bk helptool is the help browsing GUI, which links everything together and is searchable.

Editing Files

Simple: bk edit filename
Also, you can use bk mv from to to rename a file or directory.

Committing Files

The easiest way to check files in is with bk citool, which is a GUI for adding new files, checking in edited files, and grouping changes into changesets.

Unlike CVS, BitKeeper has the notion of a Change Set.  You can check in a single edited file with bk ci filename but this change is purely local.  In order to make it a real change, you need to make it part of a change set.  You can use bk commit to group a set of changes into a change set.  If you edit/ci/edit/ci a file several times before doing a bk commit, then you can put the multiple changes into several change sets, or just one change set - but you have to do it in order of oldest to newest.

Updating your local copy from the server

Use bk pull to pull other people's changes into your local copy.  If there has been a conflicting edit, you will need to use bk resolve to merge them.

Making your changes visible

Until you do this, all your changes are strictly local; in fact, you can use the full power of BK without a net connection.*
When you do want to make your changes, use bk push. This will complain if there have been remote changes which you have not yet merged.

Viewing revision history

Use bk revtool to view the history of either the whole repository or individual files.  By default, it will show the revision history of the whole repository, including merges to and from other repositories.

Creating work branches

If you're doing some reasonably complex change, you may find it easiest to create a local branch.  This is the same as initially cloning the repository - BK considers everyone's working copy to be a branch of the server's repository.  Therefore, from your ~/bk/valgrind directory, you can type bk clone valgrind working-copy.  This working copy has been set up so that valgrind is its parent repository.  This means that, by default, bk push/pull will be to/from your copy of valgrind.

Merging between branches

This is very easy. bk pull and push are the commands you use to do merging.  Unlike CVS, merging and repeated merging are simple operations.  You can push and pull between any two related repositories - they don't need to have a direct parent/child relationship, you can merge between any two in the same repository.

Undoing mistakes

bk unedit will remove edits to a file before you check it in
bk abort will throw away an unmerged, uncomplete bk pull
bk unpull will undo the last pull
bk get -eg file will make a modified file open for editing
bk cset -x changeno will generate a changeset to back out a previous changeset

NB: BitKeeper's Special Files

BitKeeper keeps metadata in several special files and directories, which you should be careful about: the BitKeeper directory, the ChangeSet file and the SCCS directory in each source directory. bk -r clean will remove all the unmodified controlled files, and bk -r get will fetch them all read-only.

Open Logging

The only license restriction on the free version of BitKeeper is that it logs all change comments to a public logging site, openlogging.org.  Since all of Valgrind's changes are public anyway, this is not a restriction at all.

Available Repositories

The most useful and interesting repositories are:
valgrind
This is the main development branch.
stable-2.0
This is the current stable release branch, which should only have "safe" changes made to it.
There are various other repositories which have special uses, are old gunk, or are people's personal hacking playpens which they want to make publically visible.  They are all visible here.

Nightly Snapshots

If you want current sources, but you don't want to use BitKeeper, you can get nightly snapshots and diffs from here.