• GitWorkflow

Introduction

There are a couple of FreeBSD git repositories that have been converted with various programs and various parameters. This page describes the "official" git-branch of the FreeBSD project that should be used as a common repository to base other work on.

The repository is provided as a read-only mirror of the state of the Subversion src repository at http://svn.FreeBSD.org/base. Using git to commit changes to this repository is not officially supported, instead it is supposed to serve as a collaboration point by using additional tools like Github, Gitorious, or Gerrit, etc.

Bear in mind that git will not replace Subversion for use in FreeBSD and the repository is only offered on a best-effort basis. The steps to redo the conversion are outlined below, so that people can move the process in-house should they see the need for it.

The Repositories

The official repository-mirrors are updated at least hourly, should they lag the svn repository by more than that, please contact <uqs@FreeBSD.org> (monitoring still needs to be put into place, help wanted btw).

• git://git.freebsd.org/freebsd.git (the canonical source)

• git://github.com/freebsd/freebsd.git (master_new, user/*, projects/*, avoid "master" for now, see http://github.com/freebsd/freebsd)

• https://code.google.com/p/freebsd (dito)

The Github and Googlecode mirrors are in the process of being switched from the old master branch to master_new, which will eventually become master in a couple of weeks. You are advised to rebase your work onto master_new before you are being forced to do so by the switch. While all commit-ids are changed (there was a bug in the timestamps formatting), you'll notice that the tree-object hashes are identical, so merging/rebasing your work should be seamlessly possible.

The historical, non-compatible repositories are:

• A git-svn clone of head and a couple of stable branches, but with truncated history.
  • git://gitorious.org/freebsd/freebsd.git

• A git-svn clone of head, with complete history. It's what you get when doing: git svn clone -Thead svn+ssh://svn.freebsd.org/base/

  • git://git.freebsd.your.org/freebsd-head
  • rsync://repos.freebsd.your.org/freebsd-head.git/
  • git://github.com/freebsd/freebsd-head.git
  • git://gitorious.org/freebsd/freebsd-head.git

  • https://code.google.com/p/freebsd-head

  • https://bitbucket.org/freebsd/freebsd-head (not git but mercurial/hg)

Quick Start

$ git clone git://github.com/freebsd/freebsd.git
$ cd freebsd
$ hack, hack, hack
$ git commit

Advanced, useful examples to show the diff between a subdir of a branch, or the commits that introduced these diffs. It is basically what svn mergeinfo --show-revs=eligible does. See git-log(1) for more info.

$ git diff origin/stable/9 master -- usr.sbin/acpi
$ git log --graph --format=oneline --right-only --cherry-pick --no-merges origin/stable/9...origin/master -- usr.sbin/acpi

See any other git howto or documentation if you're stuck on the basics.

Collaboration

There is no endorsed way yet of how users should collaborate with developers on changes they have made. Please bear in mind that git is strictly ancillary at this point and not many committers are using it.

Having your patches/feature-branches published on github for a FreeBSD committer to comment and pull on seems like the first sensible step. Sending a patch-bomb with git send-email might be an alternative to github or for developers that do not want to use git.

Receiving and integrating these patches can be done in various ways, see below.

Integration

Integrating the changes back into svn is not as trivial as using git-svn(1), as the current repository doesn't have the required meta-information. Instead patches can be applied to a subversion workspace just like any other regular patch.

A more sophisticated approach would be to share the svn and the git workspaces, which can be done by putting .svn in .gitignore and vice versa. This requires subversion 1.7 and you need to know how to recover from out-of-sync workspaces in both subversion and git, or be extra careful to avoid this situation.

Using git-svn (FreeBSD committers only)

This is only useful if you have write access to the repository and needs to be further documented ...

[svn-remote "svn"]
        rewriteRoot = svn+ssh://svn.freebsd.org/base
        url = svn+ssh://svn.freebsd.org/base # if you are a committer, add username@ if it differs from your local username
        url = svn://svn.freebsd.org/base     # if you just have read-only access
        fetch = head:refs/remotes/trunk

Things to keep in mind:

• Never git merge branches, unless you know what you're doing.

• Always git rebase your work on top of master, then git svn dcommit can push the top commits to svn.

• Always double-check with git svn dcommit -n to see what would happen.

• While you can use git add for new files just fine, you won't be able to push those upstream, you can however use the patch, apply it to some subversion checkout and do the commit there. This is a shortcoming of our very own Subversion hacks, but hey, it's better than nothing!

• While git-svn now allows you to set svn:mergeinfo when committing, this is so fragile that the FreeBSD projects discourages its use. Please use svn(1) for merging, sorry.

FAQ

• I want authornames!

  • Good for you, and this has been done but abandoned again for various reasons: There's no authoritative, complete and stable mapping of svn users to "Name <email>" pairs. Especially for people without access to freefall. Random contributors are more likely to have a conversion using the current parameters.

• Why the full history and not only since day X
  • It would make the history incompatible with other people's repository and the space savings are simply not worth the hassle. As of Mar/2012, all revisions make up about 770MB.

Further Reading

It is *really* recommended, that you read Git for computer scientists and skim GitTalkDevSummit, although parts of it are outdated.

It really helps to understand the data structure of a git commit, because then you know how merging/rebasing works and can fix snafus easily.

Implementation Details

The software used for the conversion is a slightly modified fork of svn2git, as used by the KDE project. It can be found at https://gitorious.org/~uqs/svn2git/uqs-svn2git

It requires a rules file to map svn trees and/or revisions to git branches or tags. The current rules don't make use of tags but simply store them as branches.

See the attached freebsd.rules for the current ruleset (subject to change). The command line parameters used for the continuous conversion are:

svn2git/svn-all-fast-export --rules freebsd.rules --add-metadata-notes --identity-domain FreeBSD.org http://svn.freebsd.org/base