= 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 == #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 == #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 -b }}} where is the name of the branch on jupiter and 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 == #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 ... == #exchanging 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 === #exchanging-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/// }}} where '''' is your name and '''' the path to your local molecuilder code and '''' finally is the name of your branch. It is however safer to proceed as follows: 1. Setup a remote by giving git a shorthand of the above "ssh://.../" line, where should be a suitable name of your colleague as shorthand reference. {{{ git remote add ssh://.../ }}} 2. Use the remote to fetch all remote branches. {{{ git fetch }}} 3. Merge the obtained remote branch '''' with one of yours, here called ''''. {{{ git checkout git merge }}} Note that ''git pull'' performs the fetch and the merge in a single step. === ... with the jupiter repository === #exchanging-repo 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 ==== #exchanging-repo-update 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 ''''. * ... 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 ~1 }}} Log should display none of your commits but only immediately up till your last one). Then execute {{{ git rebase --onto stable ~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 }}} where '''''' 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.