Useful information for working with GIT
=======================================

Git is a distributed revision control system. Unlike Subversion and 
others, there is no main-repository. Every developer has an equivilant 
copy of the projects source code and its history.


Getting started
---------------

Most probably you figured the clone part out by yourself:

	$ git clone git://git.performous.org/gitroot/performous/performous <new-working-dir>

This will create a clone of the repository on your local harddisk with 
branch "master" checked out by default.


Branching
---------

If you want to switch branches, you can do this by typing, no internet 
access is necessary:

	$ git checkout <branch>

Doing development happens usually on private branches, only existing in 
your own repository and invisible to others. You can create a new branch 
with the following command:

	$ git checkout -b <new-branch>

It will take all your changes to a new branch, and you can continue 
working.


Hacking
-------

To update your working copy do a simple:

	$ git pull

Discover and investigate changes others made:

	$ git log
	$ git show <commit-hash>	# (omit <commit-hash> to see latest)

Note that only a few characters (of 40) from the commit hash id is needed.

Discovering and investigating your changes isn't any different than 
subversion:

	$ git status
	$ git diff <file>	# (omit <file> to see all changes)

Committing changes in git usually takes two steps. First add the files 
you want to commit:

	$ git add <files>

Next create a new commit. This will invoke a text editor which allows 
you to enter a commit message and have a last glance at what changed:

	$ git commit

You can also pass the `-a` parameter to `git commit` to add all your
changes (and bypass the git-add stage). These operations won't interact
with the main repository in any way and no internet connection is
necessary. All that is altered is your local repository.

If you are not sure what you should do next, git status usually provides
some good suggestions.


Sharing
-------

For sharing your work with other developers it's best to bring your 
changes back to master. This can either be done with a merge, or with a 
rebase:

	$ git checkout master
	$ git merge <your-branch>

This will create a new commit which records the merge. To avoid 
cluttering history with merge commits it's sometimes good to rebase your 
work. This results in nicer, more linear history, but is also a 
dangerous task, as this commands rewrites history (and in the worst case 
can destroy **your local** repository):

	$ git rebase master

Then to finally push your changes to the internet simply do:

	$ git push origin master


Getting involved
----------------

When you become a developer of performous, you'll probably already have
a clone of the performous repository. To be able to push, you need to
change the project url with this command:

	$ git config remote.origin.url <SF.net username>@git.performous.org:/gitroot/performous/performous

Be also sure to set your name and email before committing
(if you haven't done that already):

	$ git config --global user.name "My Name"
	$ git config --global user.email "myemail@example.com"


Tricks
------

If you have already learned the basics of Git, you may find the following
things useful.

Stash:

If you e.g. need to do a hot-fix or switch branch, but you are in a middle
of some hacking you don't want to commit just yet, you can use stash to
put your changes aside, "under the carpet":

	$ git stash

When you are ready to continue, just type:

	$ git stash pop

If you want to keep the stuff in the stash, use 'apply' instead of 'pop'.
You can have multiple things stashed away at once.

Cherry-pick:

If you e.g. committed to a wrong branch and don't want to merge the whole
branch, you can cherry-pick (merge) just the one commit:

	$ git cherry-pick <commit-hash>

