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 git://git.worldforge.org/ember.git 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
If you only want a snapshot of a specific state of the code in the repository, you can use the GitWeb snapshot feature. To use that, go to http://git.worldforge.org/ and browse into the repository you want. The shortlog has lines like
8 hours ago Erik Hjortsberg Added tolua++ file for Compass master commit | commitdiff | tree | snapshot
A click on the snapshot link will get you a tar.gz archive of that specific revision of the repository.
Developing WorldForge code using Git
For the impatient, WorldForge Git repositories are at git://git.worldforge.org/ Look at WorldForge GitWeb 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://git.worldforge.org/ember.git 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...
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://git.worldforge.org/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 for GSoCers
Our stalwart Summer of Code students should use a slightly different setup. In order to make it easier for you to keep track of your own patches (after all you need to submit them to Google at the end of the program) and for us to review those patches, we will set you up with a personal git tree on git.worldforge.org. Your patches will go there first for review and you can merge them into the master repository once your mentor is happy with them.
Contact Kai at kai (dot) blin (at) gmail (dot) com with a ssh public key and a desired account name to get an account on git.worldforge.org.
While he is working on that, configure your local git repo as described above.
Then, once Kai tells you that your account is set up, edit your git config to add the following:
[remote "review"]
url = ssh://account@git.worldforge.org/data/git/account/ember.git
fetch = +refs/heads/*:refs/remotes/review/*
Put this right below the [remote "origin"], replacing "account" with your account name, of course.
Create a local feature branch for the feature you're working on
$ git checkout -b your_branch origin/master
Of course you'll have to name your branch something more descriptive than "your_branch". However, I'll keep using that for the examples.
Now you can push your code into your personal git repository to get review on it, like this:
$ git push review your_branch:refs/heads/your_branch
if you need to create a new branch. After that, it's even easier:
$ git push review your_branch
If the main ember repository changed and you want to make use of the new code, do the following:
$ git fetch $ git rebase origin/master
Now, after you rebased, pushing to the review repository will fail, you will need to force it, using
$ git push -f review your_branch
The reason for this is that usually people shouldn't rebase published branches. For your review tree however, you will want to keep your changes on top of the tree, and git rebase is the way to do this.
Once your mentor OKed the changes, it's time to push them to the master ember repo.
$ git checkout master $ git fetch $ git rebase origin/master $ git reflog
git reflog will print a list of sha1-sums of the things you touched recently. Spot the sha1-sums of the changes you want to get into the master tree and pick them over like this:
$ git cherry-pick <sha1-sum>
Once you picked all the changes in the order you want to push them, you can push to the master repo like this:
$ git push origin master
If you have any more questions, don't hesitate to ask Kai.
