Git Primer

To obtain a read-only copy of the Starlink git repository:

 % git clone git://starlink.jach.hawaii.edu/starlink.git
 % git clone http://starlink.jach.hawaii.edu/starlink.git

The first option is preferred since it is much faster to use the native protocol than http. In some cases the git protocol causes problems so the alternative is provided. If you have small one-off patches and do not need write access to the repository you can use git-send-email and mail the patch to mailto:stardev@jiscmail.ac.uk.

To clone a read/write version of the repository you will need to request an account. The repository can be cloned with:

 % git clone ssh://ssh.jach.hawaii.edu/jac_sw/gitroot/starlink.git

To find out what has been changed:

 % git status
 % git diff

After editing, if you want to commit all changes (in the entire repository, not just your current working directory):

 % git commit -a

You will be placed into an editor to enter your commit message. Note that this will not send your work back to the Joint Astronomy Centre. To do that you should first synchronize with the JAC server and then push your changes out:

 % git pull
 % git push

To obtain the history of a particular file:

 % git log --follow -- filename

or browse the repository using gitk.

Each commit is given a unique identifier (an SHA1) and can be used in many commands to indicate a single revision. Only the first few characters are required (usually about 6).

That is enough information to get started. Policies and conventions to use for the Starlink repository itself are discussed elsewhere.

Who are you?

Make sure that git knows who you are before you push any changes:

git config --global user.name "Your Name Comes Here"
git config --global user.email you@yourdomain.example.com

Seeing what changed yesterday

There are a number of ways to see what changed recently.

There is currently no nightly email job indicating recent commits.

Using a remote branch

If you want to use a particular release branch (eg Lehuakona) you do not check it out explicitly when you clone. Instead you clone the main repository and then ask git to track the remote branch.

 % git clone git://starlink.jach.hawaii.edu/starlink.git
 % git branch --track lehuakona origin/lehuakona
 % git checkout lehuakona

Now you have a lehuakona working copy. git pull will update this branch if there are fixes in the remote branch.

You can list all the remote branches:

 % git branch -r
  origin/HEAD
  origin/hokulei
  origin/humu
  origin/keoe
  origin/lehuakona
  origin/master
  origin/puana

Further Reading

There are many documents available to help learn git: