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.

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.

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.

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:

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.

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.