CCL | Software | Download | Manuals | Forum | Papers
CCL Home

Research

Software Community Operations

Git Introduction


Introduction

This document is designed to help you get started with the Git distributed version control system (DVCS) which the CCL now uses to manage its source code. This guide will teach you how to setup your working space, gain commit access, and do basic tasks. In addition to managing source code using Git, we now use the commercial (but free) GitHub website for allowing outside collaborators easily contribute to CCTools, track issues, and manage a shared Wiki.

Git is, from Wikipedia:

In software development, Git is a distributed revision control and source code management (SCM) system with an emphasis on speed. Git was initially designed and developed by Linus Torvalds for Linux kernel development; it has since been adopted by many other projects. Every Git working directory is a full-fledged repository with complete history and full revision tracking capabilities, not dependent on network access or a central server. Git is free software distributed under the terms of the GNU General Public License version 2.

When using git, you should use the CCL built package so everyone is using the same version of git. Add this to your shell startup file:

cclimport git current Action Item #1

The "mainline" CCTools repository is hosted on GitHub. Keep in mind Git has no concept of a mainline repository. Organizations can adopt any repository as a central repository. Think how Linus' linux repository is a central repository for the Linux community, by universal agreement.

Getting Started

To get started with checking out CCTools, first you should set up an account on GitHub.

Action Item #2

You will also need to setup SSH keys to authenticate with GitHub.

Action Item #3

Email Prof Thain with your GitHub username to be added to the Cooperative Computing Lab organization on GitHub.

Action Item #4

Next, we will formally create a fork of CCTools on GitHub for easier management of your branches and code. To do this, we will be following, with modifications, these instructions here.

Start by forking the CCL CCTools repository:

Action Item #5

Next we will clone your personal fork of CCTools on your workstation, using your GitHub username:

Action Item #6
$ git clone git@github.com:username/cctools.git # Clones your fork of the repository into the current directory in terminal

At this point, you have usable copy of the CCTools code. Not everything is setup though! In particular, you can't yet push changes to the mainline repository. We also don't have the full history of the CCTools code base (due to the way Git does cloning). For CCL team members, you will probably want the Subversion repository history too. We will get that setup now.

So, we will configure the remote repositories our local workstation copy will use. Remote origin is already setup for us, pointing to your personal GitHub repository https://github.com/username/cctools:

$ cd cctools $ git remote show origin $ git remote show origin * remote origin Fetch URL: git@github.com:username/cctools.git Push URL: git@github.com:username/cctools.git HEAD branch: master Remote branch: master tracked Local branch configured for 'git pull': master merges with remote master Local ref configured for 'git push': master pushes to master (up to date)

To connect our workstation clone to the mainline Cooperative Computing Lab repository, we will add one more remote:

Action Item #7
$ git remote add ccl git@github.com:cooperative-computing-lab/cctools.git # Adds the "ccl" remote repository $ git config remote.ccl.fetch '+refs/*:refs/remotes/ccl/*' # Configures git to fetch all references (including Subversion history) $ git fetch ccl # Fetch all of remote "ccl" references

You will be able to see all of the references your Git repository is now tracking by using:

$ git show-ref

You will see many results including all of the Subversion history:

ee317bc46ef24e5585741794e5c496b0cc406034 refs/remotes/ccl/remotes/svn/tags/3.7.0 be54baa2bd1b8fe988ee10ba611f1136ac98d590 refs/remotes/ccl/remotes/svn/tags/3.7.1 6d78cb87024ea5b4108b9865ec47d9f3715e74e7 refs/remotes/ccl/remotes/svn/trunk

At this point, your repository is completely setup. The repositories are shown pictorially in ASCII below to visualize the relationship of the various repositories. The Notre Dame mirror is used as a backup and repository for launching regular builds and tests via Autobuild. Your personal repository on GitHub is used primarily as a collaboration tool for sharing your branches and as a mechanism for code review.

+--------+ +---------------------+ ( Everyone ) --> | Master | |Personal repositories| |(github)|<----------+ | (github) | <---- ( Your Collaborators / Lab Mates ) +--------+ | +---------------------+ ^ | ^ github | | | -------------------------------------------------------------------- ND AFS | | | v | v +--------+ | +-----------------------+ [ Backups ] <--- | Mirror | +---->|Personal working copies| [ Autobuild ] <- | (ND) | | (~ccl/work/...) | <---- ( Just You ) +--------+ +-----------------------+

Getting Work Done

Below we will discuss a simple workflow for getting changes committed to the mainline repository.

At the beginning of any workflow for coding, make sure you have the latest source:

$ git pull ccl master

Here, we're pulling changes from the ccl remote repository and merging its master branch into your working copy master branch. Normally, you won't pull from the origin remote since only you push to it. Your working repository will always be synchronized or ahead of origin.

Making Changes

You can make changes normally to your working copy. When you are ready to commit, you must stage your changes into the Git index. The index is used to communicate to Git which changes you want part of your next commit. For example, to inform git you wish to commit changes to recently modified README, you run:

$ git add README

Then commit the changes:

$ git commit

When committing, enter a simple log message that describes the change, like "Fixed bug #123" or "Added feature XYZ".

Pushing Your Changes

Once you have made changes to your repository by adding new commits, you may push these changes to a remote repository to share with others, e.g. the rest of the lab. If you are sharing a large change you want others to examine before adding to the mainline repository, you can do this by pushing the changes to your personal fork on GitHub:

$ git push origin master

→ → This pushes your master branch to the origin remote (your personal GitHub repository). ← ←

Integrating Other Updates

While working on your code, other people may be making changes to the master repository. But, you won't see them unless you ask for them. To integrate changes into your local copy, you must rebase your work on the latest commits: $ git pull --rebase ccl master

This process may fail if your copy of master is out-of-date with the mainline ccl remote. You will need to pull the latest changes as discussed in Updating Your Repository in order to try pushing again. This is similar to a failed commit due to your working copy being out-of-date in Subversion.

To summarize, a normal workflow for fixing a bug might look like:

$ git pull ccl master <...> modify some files $ git add file1 file2 $ git commit $ git pull --rebase ccl master $ git push origin master

Making a Pull Request

At this point, your changes are pushed to your personal repository, but not integrated into the master repository. Instead of changing the master repository directly, you must make a pull request (via your github page) that asks for your changes to be accepted.

Another member of the team will review the code and possibly ask for changes. To make changes, make more commits to your local copy and then push to your repository again. Once the code is acceptable, it will be committed to the master repository.

Branches

We strongly recommend you do most work in a branch, even if the branch is short-lived. Some small changes you may want to commit directly to your master branch but changes which add features are better suited for a branch on your working repository. Branches can also be pushed to your GitHub personal repository to be shared with collaborators. Having your code be in master would end up being confusing to others.

There are numerous resources on getting started with branches in Git. The online git-scm book has a good chapter on branching and merging. The CCL "Version Control with Git" book also has a number of pages dedicated to this topic.