The FreeBSD project is in the process of switching its version-control system to git. Having passed through RCS, CVS and SVN, the project is now ending up with the same tools as (most) everyone else.

FreeBSD has three main repositories: src (the source code of the operating system itself and its supporting tools and the whole base userland), doc (all the documentation, handbooks, guides, etc) and ports (the descriptions of how to build third-party software like KDE Frameworks). These have histories going back 28 years, although some of the ancient code has bogus metadata based on multiple conversions thoughout history:

Author: svn2git <>
Date:   Mon Nov 1 00:00:00 1993 -0800

    Release FreeBSD 1.0

The move to git has been ongoing for over three years now: building up tools, finding the weird moments in history that the tools choke on, preparing documentation, .. well, to start with evaluating whether this is the right tool for version control. That wasn’t a given a few years ago and you can still scratch your head about some of it.

Now, KDE switched to git years (five? seven?) ago. It went through all the same steps. I remember being intensely annoyed at git fanboys who said git was so simple and wonderful to use. No, it wasn’t. svn revert -c 8 is what I wanted, and the madness that is purely-numeric-options to git log weighed heavily on my mind.

It got better. I Have Opinions about git branching strategy nowadays. All change is difficult.

Part of what is amusing to me about watching the FreeBSD switch with memory of the KDE switch in mind, is to see the same wailing and tooth-gnashing from developers. “Why wasn’t I told?” as a response to things years-in-the-making is a weird one (also one I used, so I’m not one to cast stones). History, once a tragedy, becomes a farce when repeated. Except it’s still a tragedy for those going through it the first time.

Git documentation

One thing the FreeBSD git-transition team has done, with Warner Losh doing a ton of the heavy lifting, is write documentation. There are, ahead of and parallel with the switch, extensive documents on how to work with git in a general sense, how git works in the FreeBSD project, and what the workflows are for various kinds of contributors to the project.

  • There’s a mini git-primer on how things work and how to get the sources in a post-SVN world. I used it to update my local source checkouts and rebuild everything in my network (I had last updated in November and was holding off because of the git switch, but having a guide made all the difference).
  • There are hows and whys and a big picture document about the schedule.

Some of this material will end up in the handbook: it is onboarding material for the project, and will remain so even if “knowing how to use git” becomes a commoditized skill. So, kudos to Warner, Ed and others who led the switch-project and wrote the docs. They’re worth a gander.