How to use the Repository on Jupiter
In this page we describe how to get access, the first thing you have to do (clone the repository) and how one should usually proceed to exchange new versions.
Getting access
In order to get access, you have to create a ssh-key and ask the system administrators to install it on the web server. They can assist you in creating it. Remember the secret pass phrase that you have to enter and don't give it away!
Cloning
The very first step on your local computer is as follows
git clone git@jupiter:molecuilder.git
This will ask you for your passphrase and will then count some objects, transfer them and after this you will find a new directory molecuilder with some files and a sub folder .git in there.
The second important step is to create your own branch to work. One important thing to understand about the version control system git, is that each of the coders has its complete own repository. There is basically no central instance. Jupiter just serves as another repository where we know that no changes to the code will appear (it is also marked as a bare repository). Hence, a branch that exists on Jupiter has nothing to do with branches of code on your computer (or harddrive rather). That's why we have to create a new branch: enter the molecuilder directory and there type in the following
git checkout <branch> -b <newname>
where <branch> is the name of the branch on jupiter and <newname> is the name of the branch you may choose as you wish.
Note that by entering
git branch -a
you may inspect all the branches there. The switch -a shows you all branches, all local ones and all remote ones that your git repository knows about. Remote ones are those on other computers, they are usually prefixed with origin/ or something alike.
Coding
As you start coding in your new branch, from time to time commit! Committing often is very important! If possible try to dissect your changes to the code in tiny steps, such that each step can be compiled successfully and afterwards committed. The dream world would be that every commit is both compilable and all unit tests run fine. The latter may be disregarded if needs be, but successful compilation is a must!
See the additional information in this [Wiki http://wissrech.ins.uni-bonn.de/inside/wikka/Git] for how to daily use git.
Exchanging versions …
Parts of the code that have been implemented and tested successfully have to be broadcast to others. There are two ways to do this.
... between users
This is easy if your computers reside in the same network (i.e. wiss-stud), just tell your colleague that he should pull one of your branches as this
git pull ssh://adamantium:/home/<user>/<path>/ <name>
where <user> is your name and <path> the path to your local molecuilder code and <name> finally is the name of your branch.
It is however safer to proceed as follows:
- Setup a remote by giving git a shorthand of the above "ssh://.../" line, where <friend> should be a suitable name of your colleague as shorthand reference.
git remote add <friend> ssh://.../
- Use the remote to fetch all remote branches.
git fetch <friend>
- Merge the obtained remote branch <remotebranch> with one of yours, here called <yours>.
git checkout <yours> git merge <remotebranch>
Note that git pull performs the fetch and the merge in a single step.
... with the jupiter repository
Here, you tell the repository administrator that he should pull one of your branches in the same manner as above. He will check your code and if it is fine, push it onto the jupiter repository. Note that you should never ever push branches by yourself thereto! (except of course you are the administrator :).
However, from time to time the repository is updated (by the administrator). You however have all branches that are local still branching from the now outdated versions. How to remedy that?
... updating your branches
Let us assume that your branch is called MyBranch and branches of v0.9.9 and the administrator has updated the branch stable such that it no longer coincides with v0.9.9 but with v1.0.0. Also, I assume that you have remote (see above) called jupiter that is the repository administrated by the administrator.
First of all, pull the changes in (remote) branch stable from jupiter and merge the changes into your (local) branch stable.
git checkout stable git pull jupiter stable
Now your local branch is updated, as you can see in
gitk --all
However, as you also can see, MyBranch now branches off from the old version v0.9.9 and not from updated stable at v1.0.0. What you need to do is rebase your commits from the first till the current one and place them on top of branch stable. This can be achieved in one go via git rebase --onto ....
For this to work, you need to know three pieces of information:
- where to rebase onto, here it's simply stable, i.e. the updated branch
- begin~1 ..., where the ~1 indicates that it should by the one commit before your first (e.g. v0.9.9 if it branched off the old stable at v.0.9.9). This can be easily got from inside gitk, you just have to copy the <hash>.
- ... and end of your branch, here it is MyBranch.
Note again that the the interval of your commits to replay on top of the now current stable has to be given as [first-1, last], where first is your first and last your last commit, i.e. we need the one commit before it (If you are unsure, select the hash code of your first commit and add ~1 to it. You may check whether it's the correct one via
git log <hash>~1
Log should display none of your commits but only immediately up till your last one).
Then execute
git rebase --onto stable <hash>~1 MyBranch
and git will replay each of your commits on top of the current stable branch.
It may happen that changes in your branch and changes occuring between v0.9.9 and v1.0.0 coincide. This will cause an interruption, a so-called conflict, and git will ask you to fix this by yourself.
git status
gives you all files that have been modified from both sides (i.e. you and the administrator).
Edit the files and you see lines like these
... <<<<<<<<<< HEAD size_t index = 0; // this was changed by admin ========== size_t index = INDEX_NULL; // this was changed by you >>>>>>>>>> ...
You have to decide (for your local branch) which are the appropriate changes, i.e. eventually it may look like this
... size_t index = INDEX_NULL; // this was changed by you ...
because your changes are the correct ones.
After editing all files and fixing all conflicts in the aforedescribed manner, type
git add <file>
where <file> is a list of changed files, and continue the rebase with
git rebase --continue
If it stops with more conflicts, fix them in the same way as above, until you have successfully performed the rebase.
Now your branch MyBranch is up-to-date, as gitk will show you when you reload its database.
... from the outside
From outside you need at least an VPN connection to the network of Uni Bonn (as is obtained by local Rechenzentrum). From there you can get access to the wiss-stud network via a tunnel. Ask the system administrators for more details on this.
In general terms, you always need some access to the wiss-stud network to make exchanges with repositories.
