Git help

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

Getting started

Most probably you figured the clone part out by yourself:

$ git clone git://github.com/performous/performous.git

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

If this is the first time you are using Git, be also sure to set your name and email before committing:

$ git config --global user.name "My Name"

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

Hacking

To update your working copy do a simple:

$ git pull

Discover and investigate changes others made:

$ git log

$ git show (omit 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 (omit to see all changes)

It is useful to examine git status and git diff before each commit (and possibly after adding new files) to make sure there are no unwanted changes. Git status also gives hints about possible actions to take next.

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

$ git add

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 -a parameter to add all your changes (and bypass the git-add stage). This is what most users will probably usually do, but using git add is still required if you are adding new files.

These operations won't interact with the main repository in any way and no internet connection is needed. 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

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 (substitute your username there, without the angle brackets):

$ git config remote.origin.pushurl https://@github.com/performous/performous.git

To push your changes into the internet simply do:

$ git push

Branching

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

It will take all your changes to a new branch, and you can continue working. If you want to switch branches, you can do this by typing

$ git checkout

No internet access is required, but you must have a "clean" working directory, i.e. changes must be committed.

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

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

In other words, the command above will make your local branch look as if you just had branched from master, then made your changes on top of that. If you want a more detailed explanation of what rebasing does (compared to merging) the following article might provide the light you look for: git merge vs git rebase

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.

Bisect

If you find a bug and don't know when it was introduced, git bisect is handy. It will give you commits to test using binary search, allowing for a quick pin-pointing of the dirty commit.

$ git bisect start HEAD bugfree-commit-id

The command above assumes that the current commit is buggy and the bugfree-commit-id is a working one from the history. Git gives you a commit to test and you tell it if it was good or bad:

$ git bisect good

$ git bisect bad

When the search is ready, you get the first dirty commit and it shouldn't be too hard to see where the bug is. To quit bisecting, use:

$ git bisect reset

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