Using mercurial for local FreeBSD development

For a long time The FreeBSD project used CVS as its version control system almost exclusively. Recently a number of more sophisticated version control systems were developed, and it's becoming quite common that the developer uses something other than CVS for local development work. It was shown over years that using CVS for big long-term work on FreeBSD source code, especially when it should be constantly synced with the main FreeBSD repo, can become a major pain. That's why, in part, the FreeBSD projects provides access to a Perforce repo to work on FreeBSD related projects.

This tiny tutorial shows how one can configure and use Mercurial to do his local development work in FreeBSD repo, while keeping in sync with the main development tree.

Checking out the source code

One of the most handy ways to obtain the FreeBSD source code is to use CVSup. This program uses sophisticated algorithms to efficiently transfer a large number of file over network. These also were specifically optimizes to use with CVS, so it tries to transfer deltas, not entire files, whenever possible.

You can find more information about CVSup in the FreeBSD Handbook.

For example, I use the following supfile to keep in sync with the FreeBSD repo.

In this configuration all source files will be placed under /work/src/mercurial/. I use separate Mercurial repos for different FreeBSD branches, though you can probably use native Hg branches for this. I discovered that keeping different repositories works better for me as it's much lesser error probability and doesn't impact the speed much (if it does it at all).

Creating Mercurial repository

After obtaining the source you have to initialize Hg repository for the first time. It's very simple, luckily enough. Just enter into the each of repository folders, e.g. /work/src/mercurial/fbsd-src-HEAD from the above, and type the following commands:

Performing local development work on the repositories

This is what we have done all the previous steps for.

Mercurial is the true distributed VCS and encourages the use of separate repository for the every project you work on. In fact, the repository clone operation is very fast and cheap - Mercurial uses copy-on-write technology to avoid unnecessary copies.

For example if you're going to do some work on the Project1 for the FreeBSD HEAD you start by creating the corresponding repository:

% hg clone /path/to/repo/fbsd-src-HEAD fbsd-HEAD-project1

After that you can safely use fbsd-HEAD-project1 for all project1-related development work, commit changes, rollback them, view the history. Refer to the Hg documentation to learn more about Mercurial and it's abilities.

In case if you need to merge with the recent HEAD after some time, you can easily do that:

You can do that whenever you want without any consequences. Mercurial keeps the history of merges, so you won't receive suspicious conflicts. Furthermore, after the merge operation Hg will integrate all the history from the merged tree into your tree, so you'll be able to easily check the difference between your tree and the main tree. Suppose, for example, after some development you've received the following: