Using Git

This page should serve as a quick guide in using Git for WorldForge development. It mainly addresses WorldForge-specific settings but also tries to give a short introduction to Git. For more information, see the Git website, the Git tutorial and the Git man pages.

Overview

WorldForge has moved all of the actively developed components to Git. We do however keep all of the unmaintained or dormant components around in a legacy CVS repository.

Getting Git

• The git source code is available from http://www.kernel.org/pub/software/scm/git/.
• The project home page is located at http://git.or.cz/.
• You should probably familiarize yourself with the Git tutorial

The examples in the following sections are based off of the tools and syntax used by git v1.5.3 or later which is the recommended version for WorldForge development.

Most distros allow you to just get a 1.5.3.x version from their repository, for Ubuntu Feisty you will want to enable the backports repo. Note that the git package in Debian/Ubuntu is called git-core.

Tracking WorldForge development using Git

This is basically an easier variant of developing using Git.

Clone the repository you want. (I will use the Ember repository as an example.)

 $ git clone https://github.com/worldforge/ember
 Initialized empty Git repository in /home/kai/wf/git/ember/.git/
 remote: Counting objects: 26916, done.
 remote: Compressing objects: 100% (5218/5218), done.
 remote: Total 26916 (delta 21660), reused 26745 (delta 21521)
 Receiving objects: 100% (26916/26916), 11.74 MiB | 1229 KiB/s, done.
 Resolving deltas: 100% (21660/21660), done.
 $ cd ember

Now, once the busy Ember developers push changes to the main repository, you need to do the following to keep up to date.

 $ git fetch
 $ git rebase origin/master

Developing WorldForge code using Git

For the impatient, WorldForge Git repositories are at git://github.com/worldforge Look at WorldForge GitHub to see which repositories you want to get.

Step Zero is to set your name and email address for commits:

 $ git config --global user.email Your.Email@domain.com
 $ git config --global user.name "Your Real Name"

Now, clone the repository you want. (For sake of example, I will use the Ember repository.)

 $ git clone git://github.com/worldforge/ember
 Initialized empty Git repository in /home/kai/wf/git/ember/.git/
 remote: Counting objects: 26916, done.
 remote: Compressing objects: 100% (5218/5218), done.
 remote: Total 26916 (delta 21660), reused 26745 (delta 21521)
 Receiving objects: 100% (26916/26916), 11.74 MiB | 1229 KiB/s, done.
 Resolving deltas: 100% (21660/21660), done.
 $ cd ember

Now, let's have a look at the local and remote branches.

 $ git branch
 * master
 
 $ git branch -r
 origin/HEAD
 origin/master
 origin/origin

Let's create a local working branch.

 $ git checkout -b my_branch origin/master
 Branch my_branch set up to track remote branch refs/remotes/origin/master.
 Switched to a new branch "my_branch"

Now we'll create a nifty new file called hello_world.txt

 $ touch hello_world.txt

So far, Git does not track the file,

 $ git status
 # On branch my_branch
 # Untracked files:
 #   (use "git add <file>..." to include in what will be committed)
 #
 #       hello_world.txt
 nothing added to commit but untracked files present (use "git add" to track)

So we will tell Git to start tracking the file.

 $ git add hello_world.txt
 $ git status
 # On branch my_branch
 # Changes to be committed:
 #   (use "git reset HEAD <file>..." to unstage)
 #
 #       new file:   hello_world.txt
 #

Now we can commit the change.

 $ git commit -m "A really nifty hello world file."
 Created commit 4042383: A really nifty hello world file.
 0 files changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 hello_world.txt

...Now repeat the edit, add, commit steps while you're working...

Git conventions

If you're commiting to Git, you need to follow these conventions, so that your commits will fit with the rest of the Worldforge system.

• Use your real name, not a nickname. I.e. "Joe Doe <joe.doe@gmail.com>" and NOT "MrBacon <joe.doe@gmail.com>". The reason is that it should be as clear as possible who's the author of a certain commit.
• Use correct english sentences. That means capitalized, with a period at the end.
• Format your commit messages according to the standard described here. In short:
  • Start with a single line, max 50 characters.
  • If more information is needed, provide an empty line between the first and third line.
  • For more infomation, starting at line 3, keep each line to max 72 characters.
• Watch out for line endings. This mainly applies when running on Windows. We use Unix line endings in all of our code.