How to use the LALSuite Git repository
Table of contents
- Are these instructions for you?
- Basic usage
- 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.
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.
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:
- Don't push code that breaks the build
- Don't change another developer's code without checking with the developer
- Do help improve the code and documentation when you see problems
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.
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
email@example.com with your ligo.org email address
user.name is literally
user.name and not your
user name; likewise for
git config --global user.name "Albert Einstein" git config --global user.email firstname.lastname@example.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
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:
You may have to resolve conflicts. Do so. And double check that your code works. When you're fully satisfied that you are ready...
Keeping your copy up-to-date with changes made to the master repository
To update your local Git repository simply type:
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
git add myfile.a
To move file
git mv myfile.a myfile.b
To remove file
git rm myfile.b
Determining current tree status
The current status of you working tree can be determined by running:
git statusthe 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.
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
remote_branch, this means that when you run commands
git pull with
new_branch as your
active branch, changes from the 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
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
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 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:
- Common CVS commands and their Git counterparts
- http://git-scm.com - Git Project Page
- http://git-scm.com/course/svn.html - Git for SVN users
- http://www-cs-students.stanford.edu/~blynn/gitmagic - Git Magic Guide
- http://book.git-scm.com - Git Community Book
- http://progit.org/book - Pro Git, professional version control book
- http://gitready.com - Git Usage Tips
- http://nathanj.github.com/gitguide/tour.html - Illustrated Guide to Git on Windows