Project

General

Profile

Using the Git repository

1. Authentication

You need to have a valid kerberos ticket and one that has forwarding obtained via:

kinit -f 

Check with

klist -a

and you should see flags "FRIA" e.g.

Credentials cache: API:501:1
Principal:
Issued Expires Flags Principal
Sep 13 16:05:12 2013 Sep 14 18:05:11 2013 FRIA

You may also need to tweak your ssh configuration, depending on your system's default ssh configuration, by adding

Host                         cdcvs.fnal.gov
HostName cdcvs.fnal.gov
GSSAPIAuthentication yes
ForwardX11Trusted no
GSSAPIDelegateCredentials yes

into your ~/.ssh/config file.

If ssh and kerberos are working then you should be able to type:

ssh  echo hello

and then get back the statement "Only 'lscvs' and 'cvs' commands are allowed".
Although I have had instances where this fails yet the git communication with FNAL is OK.

2. Repository

We have opted for a single repository called gm2-tracker-readout-daq since IpBUS XML files will be shared by the software and the hardware and will generate both "hardware" code and "software" code. The repository however has three folders/directories:

hardware : to store g-2 specific vhdl etc
software : to store IpBus readout code and MIDAS
cactus : to store the IpBus vhdl : which is a copy of that in the CERN SVN (the libraries are binaries are kept as a static release outside of git)

At present the repositories are structured to have a "master" branch which will contain the major code releases and a
"develop" branch for intermediate changes in the code development cycle. The latest production code comes from the "master" branch and the
latest code under development from the "develop" branch. Periodically production releases will be created in the "master" branch.

We are assuming for now that all code development is done in the "develop" branch and we will leave the "master" branch alone until the code is more mature. I have created a "nexys" branch that has all the BU code as of Oct-20 and also tagged the code. We will develop the "atlys" version of the code in "develop". If needs be we can create a separate "atlys" branch but I'm assuming we will be able to take the code in "develop" and use for a nexys board but if there are any nexys specific things then we'd amend the "nexys" branch.

The model for developing code that we are following is described at http://nvie.com/posts/a-successful-git-branching-model/

"Feature branches" are created for personal use and generally just maintained in the local copy of the repository and then they are merged into the "develop" branch of the local repository and the local "develop" branch is then pushed to the FNAL repository. The "feature branch" can also be pushed remotely if it's needed for sharing.

So in general code will be added to the local repository via "feature branches" that hang-off the "develop" branch.

3. Checking out the code

You can get a local copy of the git repository via the command

git clone ssh:///cvs/projects/gm2-tracker-readout-daq

This takes a while (3 mins : "Resolving deltas") since we have added all the IpBus/cactus code in the repository and that has lots of files to index. Once this stage is done it's quick.

Then do the following (you need only do this once) :

cd gm2-tracker-readout-daq
git config --global user.name "Your name"
git config --global user.email
git remote rename origin fnal

4. Changing the code

If your code is a trivial changes to a file in the "develop" branch or if you want to populate the "develop" branch for the first time or you want to create a development "feature branch" (see below) then you can simply do the following:

git checkout develop

(The git checkout just tells it which local branch to work with and it takes the code from the .git sub-directory [that has the local repository files] and puts it in the working directory. If you do a subsequent _git checkout xxxx then the code in the working directory is replaced with that from the xxxx branch i.e. locally the branches are not separate directories : you have one working directory tree that reflects the code for a given branch and you switch between branches with git checkout")

You can then create files and edit files in this branch using svn like commands i.e.

git status -a
git add filename
git commit -m "blah" filename

But note these commands only affect your local copy of the repository. The commit does NOT send the code to the FNAL repository in
the same way that CVS/SVN would. It just sends the code to your local repository.

You (see below for more details) push the code to FNAL (so others can get it) with the command:

git push fnal develop

You can determine which branches you have available and which branch you are working with by issuing the command:

git branch -a

This will return something like:

  • develop (* denotes this is the branch currently in the working directory)
    master
    remotes/fnal/HEAD -> origin/master
    remotes/fnal/develop
    remotes/fnal/master

This says there are two local branches: develop and master and two remote FNAL branches also called develop and master and that the "head" of the local repository is the "master" (as you'd expect).

git add filename
git commit -m "blah" filename

should be fine for simple modifications.

To switch branches e.g. to the "master" branch you do:

git checkout master

Another mode of working, suited to the mode where several people are working on the same local repository, is to create a local "feature branch" (here I'm calling it my-test-feature, either way it should be descriptive) that hangs off the "develop" branch via the command:

git checkout -b my-test-feature develop

(This will essentially copy all the files from the develop branch to a new branch my-test-feature and set the default working branch to be my-test-feature)

Before doing this you may want to ensure your local develop branch is up to date with respect to the FNAL repository so you'd
issue the command

git pull fnal develop

You'd then work on files in this "my-test-feature" branch
To propagate or merge these changes into the local "develop" branch you'd then do:

git checkout develop
git merge --no-ff my-test-feature

You can then delete your local test feature with: git branch -d my-test-feature

5. Pushing code back into the FNAL repository

You do this on a branch by branch basis

You can push all changes from your local develop branch into the FNAL develop branch via

git push fnal develop

If you want to push your changes into a different branch at FNAL then:

git push fnal develop fnal_branch_name

To put your "feature branch" into the repository (e.g. to share code ideas you'd do)

git push fnal my-test-feature

If you add a "-u" flag i.e. git push -u fnal my-test-feature" then that establishes that a future simple "_git push" will be
of my-test-feature to fnal.

6. Keeping up to date with the FNAL repository

You do this using the git pull command e.g.

git checkout develop (go to local develop branch)
git pull fnal develop (get latest changes from FNAL)

7. Miscellaneous

git remote -v  (lists the remote repositories : this should just list the FNAL ones)

If you mistakenly create a feature in FNAL that isn't merged with another branch and you want to delete it then:

git push fnal :my-test-feature
git tag xxxx    (will tag the last commit)
_git push --tags fnal develop

8. GUI interfaces

There are several: "gitk" is the most basic and comes with git.
Other more advanced GUIs are listed at: http://git-scm.com/downloads/guis

9. The commands for the impatient

kinit -f (get kerberos ticket)

Then you need only do this ONCE to get a local copy of the repository:

git clone ssh:///cvs/projects/gm2-tracker-readout-daq
cd gm2-tracker-readout-daq
git config --global user.name "Your name"
git config --global user.email
git remote rename origin fnal

Then to update and commit code using your local repository

git checkout develop   (switch to "develop" branch")
git add file
git commit -m "blah" file (commit change to local repository)
git push fnal develop (send back to FNAL repository)

Issues connecting to repository

If you get permission denied errors when trying to access the git repository, first check you have a valid kerberos ticket using klist -a. If you have and it still doesn't work, you may have an issue resolving the DNS alias in the FNAL git server from cdcvs.fnal.gov (the alias) to ccdcvsvm.fnal.gov (the real hostname). A work around for this is to directly use ccdcvsvm as your remote server.

To do this at the initial clone:

git clone ssh://p-gm2-tracker-readout-daq@ccdcvsvm.fnal.gov/cvs/projects/gm2-tracker-readout-daq

In this case you should then be able to push/pull as normal (e.g. as covered above).

If you have an existing repository already cloned using cdcvs, you can add an additional remote server:

git remote add origin-no-dns ssh://p-gm2-tracker-readout-daq@ccdcvsvm.fnal.gov/cvs/projects/gm2-tracker-readout-daq

You can then push/pull using:

git pull origin-no-dns develop
git push origin-no-dns develop