Marble/GsocGit

This tutorial is a quick introduction to the setup and work with git and gitorious.org in Marble's Google Summer of Code (GSOC) projects. Further details can be found in the links listed in the last section of the page.

Overview

The Marble source code is stored in the official KDE Subversion repository. The directory trunk/KDE/kdeedu/marble/ keeps the latest development changes. This is the reference code you should work with during GSOC. For your convenience this repository part is mirrored at gitorious.org in the svn.kde.org branch of the marble repository in the marble project. This branch is updated from time to time to keep in sync with the development in Subversion.

For your GSOC project, you setup another git repository on gitorious.org: Your personal clone of the marble gitorious repository. You will be the only person writing to the repository. Additionally you can synchronize it with (import) the latest Subversion changes at your convenience. There's a fourth repository, your local clone of your personal gitorious clone. Local means that unlike the other repositories, this one is only stored on your system. This is the repository you work with most of the time. The others are only for synchronization.

Summing it up, there are four physical repositories:

• svn.kde.org keeps the latest Marble development code
• marble/marble.git on gitorious.org is a mirror of the svn.kde.org repository
• ~yournick/marble/yournicks-marble.git keeps your GSOC changes visible to the public
• A local clone on your system keeps your current development and is synchronized with your personal gitorious clone

Logically, there are only two repositories:

• The latest Marble code in the marble/marble repository
• Your personal clone of the marble/marble repository which also holds your GSOC project (changed and added files)

To understand how these repositories are updated / synchronized, let's have a look at who does which changes. First, changes from the top:

• Marble developers commit changes to the svn.kde.org repository
• Earthwings (or another Marble developer) from time to time invokes a script that transports the latest changes to svn.kde.org to the marble/marble.git repository on gitorious.org
• You (and nobody else) can import these changes into your personal clone
• You (and nobody else) can import changes to your personal clone on gitorious.org to your local clone. This is only needed if you are working on more than one system.

Changes from bottom to top happen like this:

• You (and nobody else) can push your local development changes to your personal clone on gitorious.org
• Your personal clone is not going to be merged in the marble/marble.git repository (see below)
• The marble/marble.git repository is not going to update svn.kde.org

Now how does your GSOC project end in the official Subversion repository? This will be handled at the end of GSOC via reviewboard. Git can create the necessary patch easily.

While the number of repositories involved may seem huge and the process very complex, it is easy and fast to work with in practice. The main advantage of git in the GSOC context is its ability to handle merges easily. Merges occur when you synchronize your personal clone with the Marble development sources and when your GSOC project is merged ino the Marble development sources at the end of GSOC.

Initial Setup

Gitorious Setup

Your personal clone of the marble/marble repository contains a full copy of the marble/marble repository at the time of cloning. You are the only one modifying this repository and it will contain your GSOC project. Setting up your personal clone of the marble/marble repository in gitorious is quite easy:

• Create an account at Gitorious
• Fill in the details and upload your public SSH key (create one if you don't have one)
• Go to the marble/marble repository
• Click on "Clone repository" and again "Clone repository" on the next page after reviewing the settings

Local Repository Setup

The local repository is a clone (full copy) of your personal clone on gitorious. You use it during development: Review changes and commit them to your local repository. Whenever you feel like it, synchronize it with your personal clone on gitorious: Upload the latest changes so that everyone else can see them.

Initially you need to clone your personal gitorious clone to create the local repository. This goes as follows:

git clone [email protected]:~earthwings/marble/earthwings-marble.git

Replace "earthwings" with your Gitorious account. The clone URL can differ; have a look at your personal clone on gitorious.org where the clone URL is listed.

The clone operation you did in gitorious was a one-time operation. It's possible and useful to synchronize changes happening after the clone operation later. For this to work, configure your local repository to list the marble/marble repository as another remote repository:

git remote add mainline [email protected]:marble/marble.git
git fetch mainline

Day-to-Day operations

With the local repository set up, you can work with it like you work with any other git repository. This tutorial is not meant to replace the existing git tutorials: Please make sure to read one or more of them if you do not know git yet. See the last section at the end of this page for some nice general git tutorials.

The following operations will be useful while working on your GSOC project.

Commit local changes to the local repository

Local commits are a great way to keep your development work in order. You do not need an Internet connection for local commits.

Show modified and new files

git status

Show changes modified files introduce

git diff

Commit all modified files

git commit -a

Commit the new file foo.h

git commit foo.h

See also git add and git add -i

Synchronize changes to the local repository to your personal clone on gitorious

git push

Synchronize changes to your personal clone on gitorious to the local repository

Note: This step is only needed if you have more than one local repository

git pull

Synchronize changes to the marble/marble repository to your personal clone

This is done by synchronizing changes to your local repository (see below) and pushing them to your personal clone afterwards (see above).

Synchronize changes to the marble/marble repository to your local repository

git fetch mainline
git merge mainline/svn.kde.org

You may also rebase the changes (see git tutorials).

Creating Review Requests

In Marble we're using Review Board for peer reviews of code. It is a bit picky about the format of patches it accepts, so we need to prepare a bit for it.

First (but only once), you'll have to add the KDE subversion repository to your list of remote repositories and fetch data from it. This is needed to create a patch against the right files, those in the KDE subversion repository. Adding the remote repository takes two steps (replace nienhueser with your KDE Subversion account name):

git svn init svn+ssh://[email protected]/home/kde/trunk/KDE/kdeedu/marble
git svn fetch -r 1151760

The revision argument should be a recent KDE Subversion revision number. To find out the most recent one, use (replace username again):

svn info svn+ssh://[email protected]/home/kde/trunk/KDE/kdeedu/marble

Once the data is fetched, you can create the diff. One of the following two methods should work:

• post-review -n --server=reviewboard.kde.org > mypatch.diff
• marble-svn-diff > mypatch.diff

The marble-svn-diff script is based on http://wiki.koffice.org/index.php?title=Contributing_a_Patch and http://mojodna.net/2009/02/24/my-work-git-workflow.html

When using marble-svn-diff, the resulting patch needs to be edited manually when new files are included in the patch. To so, open the patch in an editor, locate lines like

--- /dev/null  (revision 1151760)
+++ src/MyNewClass.h  (working copy)

and change them to

--- src/MyNewClass.h  (revision 0)
+++ src/MyNewClass.h  (working copy)

One of the two commands should give you a patch in the file mypatch.diff. Rename it to a sane name, create a review request and attach the file. Use /trunk/KDE/kdeedu/marble as the "Base Directory" it asks you for when uploading the diff.

Further Reading

• Development/Tutorials/Git
• The official tutorial introduction to Git
• Git Screencasts
• Cheat Sheet