Using Git
From WorldForgeWiki
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.
Contents |
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...
The remaining parts of this section are outdated
Finally, we want to get our new features to the main repository. In order to do so, you need to contact Kai to get an account on git.worldforge.org. Make sure to also provide Kai with a ssh public key.
We first need to make sure we are up-to-date.
$ git fetch
Now we need to rebase our working repository.
$ git rebase origin/master Current branch my_branch is up to date.
And finally push the changes to the remote repository.
$ git push ssh://github.com/data/git/ember.git my_branch:master
Counting objects: 87, done.
Compressing objects: 100% (37/37), done.
Writing objects: 100% (64/64), 81.72 KiB, done.
Total 64 (delta 32), reused 58 (delta 27)
To ssh://git.worldforge.org/data/git/ember.git
f12012e..4042383 my_branch -> master
(Note that "push" uses ssh:// instead of git:// and the full path on the file system (/data/git/).
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.
Git for GSoCers
Our stalwart Summer of Code students should use a slightly different setup. We have copies of all the relevant repositories on GitHub. If you don't already have an account there, you should get one. After you set up git for GitHub, you should fork the repositories you're interested in. You can then work on your own repository on GitHub. Once your changes are ready to be committed, you can send a pull-request to get your changes integrated into the main repository.
If you have any more questions, don't hesitate to ask.
