|CCL HomeSoftware Community Operations||
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:
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 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.
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:
You will be able to see all of the references your Git repository is now tracking by using:
You will see many results including all of the Subversion history:
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 DoneBelow 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:
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.
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:
Then commit the changes:
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:
→ → This pushes your master branch to the origin remote (your personal GitHub repository). ← ←
Integrating Other UpdatesWhile 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:
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:
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.
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.