We use Git to manage our source code. Our Gitorious installation is the front end we use to manage our different Git repositories.

This page will help you get started with Git and getting the KIELER sources. For more detailed information, see Git's official documentation. The SVN Crash Course is probably a good place to start. For more in-depth information, see the Git Community Book or the Pro Git book. Furthermore, each office has a copy of another excellent book about Git, so you might as well go ahead and read it. This will help ease you in to some of the more advanced concepts of Git, which are a little hard to understand at first. If everything else fails, Miro and Tim will be more than happy to help you with Git and rant about how excellent of a system it is. (wink) For more information on Git Eclipse integration, see the EGit User's Guide.

Content

Checking Out KIELER

KIELER is essentially a large heap of Eclipse plug-ins that aren't easy to find your way through as a new developer. The Overview page has a nice overview of our sub-projects and what plug-ins belong where. This section will tell you how to get the KIELER sources. As for what plug-ins you will actually need to checkout, ask your advisor.

The Git protocol runs on port 9418, and SSH runs on port 22. HTTP transfer is also possible in read-only mode, but is not recommended due to its bad performance.

You essentially have the choice of either checking out the KIELER sources using our project sets (preconfigured sets of plug-ins that are automatically imported into your Eclipse environment), or by selecting the plug-ins you want manually.

Checkout Using Team Project Sets

If you need a specific subset of the KIELER plugins, select a suitable project set, copy its URL, and select File - Import - Team - Team Project Set. There are two versions of the project sets:

For access using the SSH protocol you first need to do steps 1 to 3 of the manual checkout section below.

Manual Checkout

In case you only need read access, omit steps 1 to 4 and copy the following URI instead:

 git://git.rtsys.informatik.uni-kiel.de/kieler/mainline.git

Otherwise, follow these steps:

  1. If you don't have an SSH key yet, you have to create one. You can do this by:
  2. Register with Gitorious and upload your public SSH key (Dashboard - Manage SSH keys - Add SSH key).
  3. Ask a KIELER administrator to add you to the kieler-dev Gitorious team.
  4. Copy the repository URI git@git.rtsys.informatik.uni-kiel.de:kieler/mainline.git into the clipboard.
  5. Open the Git Repositories view, right-click it, select Paste Repository Path or URI, select ssh connection protocol, Next, select master branch, Next, select destination directory (e.g. /home/<username>/shared/kieler), Finish. Wait for the repository to be downloaded to your computer. Note that the whole history of the repository will be stored in your local filesystem, which is pretty awesome.
  6. Right-click the Working directory entry in the kieler repository, select Import Projects, Next, select the projects that you want in your workspace, Finish.

In case you already checked out the repository over the read-only git protocol, but you want to be able to commit to the remote repository, open the Git Repositories view, right-click kieler/Remotes/origin, select Configure Push, and change the URI to the ssh variant.

Checking out on the command line is done with the command git clone <URI> <local path>. Instead of the URI you can also use a path to an existing repository, which then creates a clone of that repository.

Adding an Existing Local Repository to EGit

If you have already cloned the KIELER repository and are only looking for a way to import it into EGit, follow these steps:

  1. Click the button Add an existing local Git Repository to this view in the Git Repositories view and enter the local path.
  2. Right-click the Working directory entry in the added repository, select Import Projects, Next, select the projects that you want in your workspace, Finish.

Updating the Repository

Your working copy must be clean before you can merge any updates into it. Therefore, always commit your changes locally before you pull. If you don't want to commit them into the master branch, commit them into a new branch. Note that pulling is the same as fetching remote changes and merging them into your local branch. Since a normal merge operation is involved, this can lead to conflicts, which need to be resolved as described below. Note that pulling always merges the remote changes into your current branch. If that's not what you want, checkout the correct branch first or just do a fetch.

Do one of the following three things:

Resolving Conflicts

Whenever branches are merged or rebased, conflicts can occur. They can be resolved by adjusting the state of your working copy, marking it as clean, and committing the changes. Conflicted files are modified so they contain both your version and the remote version. Edit them until all conflict areas are clean. In Eclipse this can be done by right-clicking the conflicted files - Team - Merge Tool.

If you try to pull from a remote repository or merge branches although you have local uncommitted changes, and the merge would affect the same files, Git leaves those files as they are, thus discarding the changes that would be made by the pull or merge operation. As a consequence, committing such a conflicted state would ignore the changes of the merged branch even if the commit graph looks like a regular merge has happened. Therefore keep in mind never to pull or merge with uncommitted changes.

Taking your version of conflicted files: git checkout --ours <path>

Taking the remote version of conflicted files: git checkout --theirs <path>

Committing Changes

Git manages changes in two separate steps:

  1. Commit changes to your local repository.
  2. Push the commit to the remote repository.

The first step can be done offline, which is very useful in situations where you don't have an internet connection, but would like to save intermediate development snapshots in the history. You can push multiple commits to the remote repository, which for example means that if you are performing changes that would create broken intermediate states, you can commit any number of snapshots locally and only push the whole bundle of commits after you have reached a state that works again.

If another developer has pushed changes since the last time you have pulled from the server, your attempt to push your commits online may fail. In this case you need to pull the remote changes before you can push. Never use force pushing! (git push -f)

Make sure you have set up your name and email address properly, as described on the Configuring Eclipse page.

Committing

To commit changes with EGit, do one of the following and select the files you would like to commit:

To commit your changes on the command line, do the following:

  1. Use git add to select (stage) the files you would like to commit (new files as well as modified files).
  2. Enter git commit to create a commit from the staged files.

Pushing

To push your commits to a remote repository with EGit, do one of the following:

To push your commits on the command line, enter git push.

Getting Earlier Versions of Files

If you want to revert all your local changes and get back to the previous repository state, use git reset --hard or the Reset item in the EGit context menu. If you only want to revert some specific files, do one of the following:

By giving a branch, tag, or commit number in git checkout <commit> <path>, you can get to any existing version of the files. If no path is given, git checkout <commit> switches your whole working copy and index to the specified branch, tag, or commit number. If git reset is given a commit number, the current branch is modified to point at the given commit.

This is a brute force modification, and you probably won't be able to push the new branch

Cleaning Your Working Directory

In case the working directory is messed up with unstaged files, which are not affected by git reset --hard, a clean up is achieved by means of git clean -f. The additional switch -d applies this to directories, respectively. Hence, git reset + git clean act like svn revert.

git clean -X removes only the files that are ignored by Git, that is mainly the .class files generated by the Java compiler. A full rebuild is required afterwards.

Branching and Merging