Search


DASWG LAL Doxygen

Docs

How-To's
Technical
Software Docs
Minutes

Download

Browse CVS, Git, or SVN
Software Repositories
OS Security Updates
LIGO software virtual machine
VMware SL6 Install

Participate

SCCB - Software Change Control Board
Edit these pages
Sub-committees
Mailing List
Telecon

Projects

DMT
DQSEGDB
Glue
GraceDB
gstlal
LALSuite
LDAS Tools
LDG Client/Server
LDR
ligoDV
LIGOtools
LVAlert Administration
LVAlert
MatApps
Metaio
NDS Client
PyLAL
LSCSOFT VM

Legacy Projects

geopp
LDAS
LDM
LIGOtools
LSCGIS
Onasys
OSG-LIGO

How to use the LALSuite Git repository

Table of contents

  1. Are these instructions for you?
  2. Introduction
  3. Basic usage
  4. Other features

Are these instructions for you?

These instructions are for beginners who are first learning to use Git to access the LALSuite software and should only be followed for the most basic of code changes. Once you've become familiar with the basics of Git and the LALSuite collaborative code development effort, you will want to explore more advanced code development models. These are described here, and here.

Note: The instructions that follow assume that you are using at least git version 1.5.0, please ensure that you are using at least this version before proceeding.

Introduction

The LALSuite Git repository

The LALSuite (comprised of glue, lal, lalapps, and pylal) uses Git as a collaborative code development system. It is a tool to allow multiple developers to manipulate the same files, merging differences, and identifying conflicts between changes if they arise.

The lalsuite Git repository is structured as follows:

Repository Name:  lalsuite
                     |---->glue
                     |---->lal
                     |---->lalframe
                     |---->lalmetaio
                     |---->lalxml
                     |---->lalburst
                     |---->lalstochastic
                     |---->lalapps
                     +---->pylal

An excellent introduction to why version control is required, and the strengths that git has over other version control systems can be found in the The Git Parable. It is highly recommended to read this carefully as it explains a lot of the concepts and terminology used in following documentation.

Etiquette

We operate the lalsuite Git repository as an open development environment in which we rely on developers not to do deliberate damage to other people's code. This honor system has worked well up to now and we hope it will continue.

Some basic rules about pushing code to the master repository:

Getting access

Everyone has access to read the sandbox repository using the git protocol. If you're in the roster, you have the ability to push to the repository over ssh.

Basic usage

Cloning the master Git repository

First make sure that Git knows who you are so that this can be recorded correctly in the repository running the following, replacing Albert Einstein with your name, and albert.einstein@ligo.org with your ligo.org email address (user.name is literally user.name and not your user name; likewise for user.email):

git config --global user.name "Albert Einstein"
git config --global user.email albert.einstein@ligo.org

Your LIGO.ORG account is used for authentication and you must have a valid ECP Cookie inorder to clone the repository:

$ ecp-cookie-init LIGO.ORG https://versions.ligo.org/git albert.einstein

replacing albert.einstein with your LIGO.ORG Kerberos principle. You need to tell git the location of this cookie using:

$ git config --global http.cookiefile /tmp/ecpcookie.u`id -u`

this needs to be done on each machine that you wish to access the repository from.

To get a copy of the LALSuite Git repository, use the command:

git clone https://versions.ligo.org/git/lalsuite.git

this may take a few minutes. When this is completed you have a repository that contains the entire history of the LALSuite Git repository.

A read-only copy of the repository can be clone anonymously using the following command:

git clone git://versions.ligo.org/lalsuite.git

Making changes and committing them to your Git repository

Once you've made your changes, you commit them to your own Git repository by:

git commit -a

You will be asked to provide a comment for the change log. This does not need to be detailed, but should give some indication of the work you were doing. For example, if this addresses a problem report make a note of which in the commit message. Git will refuse to perform the commit if you leave this blank.

Note that the changes have been pushed to your own local repository. They are not yet in the master repository.

Pushing your changes to the master Git repository

First you should check to make sure that your code works, so that you wont be messing up things for other people (see etiquette).

Make sure that your repository is up-to-date:

git pull

You may have to resolve conflicts. Do so. And double check that your code works. When you're fully satisfied that you are ready...

git push

Keeping your copy up-to-date with changes made to the master repository

To update your local Git repository simply type:

git pull

from the lalsuite directory.

If you have been working in your local repository and your changes conflict with those made by the other person, you will receive a warning and will need to manually edit the file to remove the conflicts. It is usually good practice to update your local repository before working on the files; this avoids conflicts. It is also good practice to commit changes reasonably often.

Adding a new file

To add a file to your local repository, first place it in the appropriate directory. For convenience, let the filename be myfile.a. Type:

git add myfile.a

To move file myfile.a to myfile.b, type:

git mv myfile.a myfile.b

To remove file myfile.b, type:

git rm myfile.b

Once you're done, commit your changes to your local Git repository, test, update, test, then (are you sure?) push your changes to the master repository.

Determining current tree status

The current status of you working tree can be determined by running:

git status
the output will be something like
# On branch master
# Changed but not updated:
#   (use "git add ..." to update what will be committed)
#   (use "git checkout -- ..." to discard changes in working directory)
#
#       modified:   myfile.a
#
# Untracked files:
#   (use "git add ..." to include in what will be committed)
#
#       myfile.b
no changes added to commit (use "git add" and/or "git commit -a")

In the above example we are on the master branch and there are uncommited changes to myfile.a and the file myfile.b is currently untracked by Git.

Other features

Making and checking out tags

To create a tag of the current state of the repository run:

git tag -a tag_name

The working copy of the repository can switched to a given tag with the following:

git checkout tag_name

When you create a new tag this is only within your local repository, in order to get this tag into the master repository it needs to be pushed, this is done with the following:

git push origin refs/tags/tag_name

or all tags that exist in your local repository, that are not in the remote repository, can be pushed with:

git push --tags

Branching and merging

One of the main strengths of Git is its support for dealing with branches. A new branch can be created, and checked out by running:

git checkout -b new_branch origin/remote_branch

This creates a new branch in you local repository called new_branch that tracks the remote upstream branch remote_branch, this means that when you run commands such as git pull with new_branch as your active branch, changes from the remote branch remote_branch will be pulled into this branch.

Note: NEVER checkout these remote branches directly, always checkout a local copy that tracks the remote branch. Checking out the remote branch directly will lead to nothing but problems!

You can list all branches, both local and remote, in a given repository with the following:

git branch -a

Like tags, any new branch you create is only within your local repository. Therefore to get a branch into the master repository it needs to be pushed, this is done with the following:

git push origin new_branch

Now that you have pushed this branch into the remote upstream repository you may want your local branch to track this remote version of the branch, for details on how do do this please consult the Advanced LALSuite Git instructions.

Merging between branches is generally straightforward, to merge changes from the branch new_branch to the current branch run the following:

git merge new_branch

If there are conflicting changes in the merge then the merge process will halt and alert you to the conflict:

$ git merge new_branch
Auto-merging path/to/file
CONFLICT (content): Merge conflict in path/to/file
Automatic merge failed; fix conflicts and then commit the result.
$

You then need to fix the conflict, how to do this is dependant upon the nature of the conflict see the links in the more information section for details on how to resolve conflicts. Once the conflict has been resolved you can proceed with the merge by running:

git update-index path/to/file
git commit

If you only want to merge a single, or handful, of commits from a branch then you can "cherry pick" these commits with the following:

git cherry-pick -x commit_id

Where commit_id is the ID of the commit you wish to push to the remote repository. Again, you may need to resolve conflicts, do this and check that the code works. Note: the -x option records the original commit id of the commit you are cherry picking. If this is on a branch that you are not intending on pushing to the remote repository then the -x option should be dropped.

More information

More information and documentation regarding the usage of git, and details of more advanced features such as branching, merging, patch generation, conflict resolution, and many other advanced features can be found on the following pages:

$Id$