Warner's Useful Mercurial Work Flow

I've been asked by several people to document my current Mercurial setup and work flow. While some people love git, others find it tedious and cumbersome to deal with. If you love git, use git. If not, consider this work flow. If you wish to turn this page into a handbook chapter, please contact the author and remove the folksy, chatty style.

This works well on new development pushed into head. It works less well when I have to MFC. To do that, I still follow the handbook using raw svn directly. I'd love to find a way to not have to do this where mergeinfo is correctly done, but so far I got nothing.

Ideally, this section would be “Install the devel/mercurial port” and then I'd move on. However, this port doesn't have the subversion upstream support baked into it. I use hgsubversion. While there is a FreeBSD port, as of this writing (June 5, 2014), it was too old (1.6.1) to support pulling from the FreeBSD repo due to FreeBSD's repo layout. So this section is a little longer…

Install the following ports. While one might be able to do clever things with linking svn to svnlite, I've had mixed results trying that and have always reverted to the actual svn port, since the SWIG bindings work a lot better than the command line bindings, and SWIG works a lot better with the full subversion port. While all this might not be strictly necessary, it is what I know works.

• devel/mercurial
• devel/subversion
• devel/py-subversion

I put this under $HOME/src like so after installing the above ports:

cd $HOME/src
hg clone http://bitbucket.org/durin42/hgsubversion

The author knows that the following checkout works for him. There are plenty of newer revisions that might also work. Caveat Emptor.

% hg sum
parent: 1146:4cdb0e95604f tip
 svncommands: call util.dump instead of manually writing file
branch: default
commit: (clean)
update: (current)
mq:     (empty queue)

You need to enable the mq (mercurial queues) and hgsubversion extentions in your $HOME/.hgrc file:

[ui]
verbose=true
username="Warner Losh <imp@freebsd.org>"

[extensions]
mq=
hgsubversion=~/src/hgsubversion/hgsubversion

Note, I also set my username to my FreeBSD email address, and turn on verbose. While I normally like commands to be silent, I find that verbose tells me just enough about what's going on to know something has happened. But this may be because its verbosity is similar to cvs and svn's default settings and I've used those tools for a decade and a half…

Create a patch queue repo on freefall. I place mine under my public_html directory so anybody can pull from it, but I'm also careful about what I work on to make sure that it is all public (even if it all isn't going into FreeBSD or needs a lot of love before I commit it to FreeBSD). I store it on freefall in case my local machine's hard drive goes to the great storage hunting grounds… Also, it is a convenient pivot point to allow development on multiple machines…

local% slogin freefall.freebsd.org
freefall% cd public_html
freefall% mkdir public-patch-queue
freefall% cd public-patch=-queue
freefall% hg init
freefall% logout
local%

While this works equally well on ports as src, all my examples are on src. I've used this technique for the tiny number of ports commits I've done, as well as a hundred or two commits to the repo. It works well for a single commit, or when you have a dozen small chunks that are closely related that you'd like to push upstream at the same time to allow for easy bisection in case there's an issue.

When pulling the FreeBSD tree, you get to decide how much of a conversion you want to do. hgsubversion converts the FreeBSD history into local hg history. I've never wanted/needed much locally (since I use svnweb for much of it), so I tell hgsubversion to start with the tip. You can substitute your own version, or omit it entirely for all the mainline history if you want. It does seem to slow down the creation process to do this, however. Since I've not done it, I don't know how much it slows down the repo actions, but my experience with hg on other projects suggests the slowdown will be minimal.

% cd FreeBSD
% hg clone --startrev HEAD svn+ssh://svn.freebsd.org/base/head
% cd head

This section contains (or will contain) a bunch of examples of things I do all the time.