Emulab Git Repository

Table of Contents

  1. Available Repositories
    1. Anonymous Read-Only Access to Emulab Git
    2. Access to Emulab Git via SSH
    3. Tracking Commits to the Emulab Repositories
  2. Workflow
  3. Transitioning From CVS
    1. Creating a Patch
    2. Cloning the Git Repository
    3. Checking Out a CVS Sandbox From a Git Server (alternate)
    4. Applying Patch
    5. Checking Changes Into Local Repository
    6. Tracking Emulab Source
  4. Checking Out a CVS Sandbox From a Git Server

To facilitate development, we are transitioning our version control system from CVS to Git. This will make it easier for other sites to maintain local changes while still tracking against the main Emulab development. For general information about Git, see http://git-scm.com or http://progit.org. We will continue to export a CVS gateway to the main repository after the transition, but it will be read-only.

Available Repositories

There are two Emulab repositories available.

  • A stable repository, called emulab-stable, which contains code after it has been vetted (eg. after it has run for a while on the Utah Emulab site). We recommend that most people use this repository.
  • A development repository, called emulab-devel, which contains the latest "bleeding edge" changes to the code base. This code may not necessarily be tested well, or at all.

We have also created a repository for "contributed code" which will contain code contributed by other developers.

All of our public repositories can be browsed using Gitweb at http://git-public.flux.utah.edu.

Anonymous Read-Only Access to Emulab Git

We provide anonymous read-only access to the Emulab Git repository via git-daemon.

The emulab-stable repository may be cloned using the following git command: 

git clone git://git-public.flux.utah.edu/emulab-stable.git

The emulab-devel repository may be cloned as follows: 

git clone git://git-public.flux.utah.edu/emulab-devel.git

Once you have a Git checkout, following the instructions for upgrading your site.

Access to Emulab Git via SSH

We also provide access to the Emulab Git repository via ssh for administrators of Emulab installations interested in contributing code. To request an account on our Git server, send mail to testbed-ops. Please include an ssh public key when you send your request. Password authentication is not allowed.

The emulab-stable repository may be cloned via ssh using the following git command: 

git clone git-public.flux.utah.edu:/flux/git/emulab-stable.git

The emulab-devel repository may be cloned via ssh as follows: 

git clone git-public.flux.utah.edu:/flux/git/emulab-devel.git

Tracking Commits to the Emulab Repositories

If you would like to track the daily Git commits, there are two possibilities:

  1. Visit the online Changelog an a regular basis.
  2. Join the Stable Commits mailing list, and/or the Devel Commits mailing list. Each commit log entry is sent to these lists, which sounds like a lot of traffic, but is not that bad, really.

Workflow

Here in Utah we have put together a typical workflow that describes how Flux project members are expected to operate.

Transitioning From CVS

Many of the commands in CVS have analogues in the Git world. For tips on doing tasks you are used to in CVS see: http://www.me.kernel.org/pub/software/scm/git/docs/v1.4.4.4/cvs-migration.html

You will need to transition any local changes to the new repository. We will continue to host the old repository, but it will be read-only and will not be updated. The first step is to create a patchfile for any local changes you may have in your old sandbox. Then, you will need to clone the Git repository. Third, you must apply your patch to the files in the new repository. The last step is to commit your changes into your local repository.

After you have completed this process, you will need to track changes in the Emulab source repository by periodically pulling them into your local repository and merging the new Emulab source into it.

If you want to continue to use CVS tools instead of transitioning to Git, we are providing a CVS gateway to the new Git repository which will allow you read-only access.

Creating a Patch

First, you need to make sure your sandbox is up to date with the old repository: 

cd /your/old/src/dir/
cvs update

Make sure to resolve any conflicts.

Create a diff with your local changes: 

cvs diff -u > /your/patch/file.patch

This will ignore any new files you have added to your sandbox that are not in the repository. You must copy those files over separately after patching.

Cloning the Git Repository

Next, you should clone the Git repository. If you wish to use the CVS gateway, skip to the next section: 

cd /your/new/src/dir
git clone git-public.flux.utah.edu:/flux/git/emulab-stable.git

Checking Out a CVS Sandbox From a Git Server (alternate)

After the transition, there may still be some users who need to check out the codebase using CVS. In order to do this, we have set up git-cvsserver which currently allows read-only CVS access to our main git repository. Use the following commands to check out using a CVS client: 

setenv CVS_SERVER "git cvsserver"
cvs -d ":ext:<username>@git-public/flux/git/emulab-stable.git" co <branch>

where <username> is your username on the git server and <branch> is the name of the git branch to check out. For trunk, the git branch is master.

If your CVS client is version 1.12.11 or later, you may use the alternate checkout command 

cvs -d ":ext;CVS_SERVER=git cvsserver:<username>@git-public/flux/git/emulab-stable.git" co <branch>

which has the advantage that the CVS_SERVER setting will be stored in your CVS/Root files and so doesn't need to be set in the environment before using cvs.

Applying Patch

Apply the patch file to your new source tree. Keep in mind that there may be conflicts that you must resolve because the old CVS repository is no longer updated. 

cd /your/new/src/dir
patch -u < /your/patch/file.patch

Make sure to copy any files which you want preserved from your sandbox.

Checking Changes Into Local Repository

With Git, you not only have a local sandbox, but a local repository. After applying the patch, you should check in your local changes to your repository. To understand how the commit process works in git overall, see http://progit.org/book/ch2-2.html. First you stage your files and begin tracking any new files you have created: 

git add changed.file new.file other.file

Then you commit the staged files to the local repository: 

git commit

Now your local repository contains all of your local changes merged into the files at the time you cloned the repository.

Tracking Emulab Source

As time passes, the Emulab source repository will be updated with bugfixes and new features we add to the system. To merge these changes into your local repository, you need to pull them periodically from our repository into your local repository: 

git pull

All of your local changes must be committed to your local repository before pulling the changes from the Emulab repository. The pull command will both download the new changes and merge them into your branch.

Checking Out a CVS Sandbox From a Git Server

There may still be some users who need to check out the codebase using CVS. In order to do this, we have set up git-cvsserver which allows CVS access to our main git repository. Use the following commands to check out using a CVS client: 

setenv CVS_SERVER "git cvsserver"
cvs -d ":ext:<username>@git-public/flux/git/emulab-devel.git" co <branch>

where <username> is your username on the git server and <branch> is the name of the git branch to check out. For trunk, the git branch is master.

If your CVS client is version 1.12.11 or later, you may use the alternate checkout command 

cvs -d ":ext;CVS_SERVER=git cvsserver:<username>@git-public/flux/git/emulab-devel.git" co <branch>

which has the advantage that the CVS_SERVER setting will be stored in your CVS/Root files and so doesn't need to be set in the environment before using cvs.