Developer FAQ

How do I get and install Git?:

I will leave the installation and configuration of Git for you to figure out.

Git Home Page : http://git.or.cz/

This presentation give an excellent and detailed overview of Git:

http://www.gitcasts.com/git-talk

How is Git different than Subversion?

http://git.or.cz/course/svn.html

How should I configure Git before development?

The following config is mandatory:

# personalize these with your own name and email address
git config --global user.name "My Full Name"
git config --global user.email "someone@example.com"

I highly recommend the following additional global config tips for Git:

http://rails.wincent.com/wiki/Git_quickstart

http://rails.wincent.com/tags/git?type=article

So what will the development process look like now?

Git allows for entirely new workflows and can be used in a myriad of ways. For now lets stick to a simple workflow model:

Forking your own Git repo from the master and creating your first commit

This approach gives you your very own copy of the repo that is linked to the master. This is preferred since it allows us to easily do Git to Git merges which is where Git shines. There is no need to generate a patch file, or email anything.

• Create your account on GitHub
• View the xmpp4r repo at http://github.com/ln/xmpp4r/tree/master
• Click the ‘fork’ button (This will make a server copy of the repo, linked to its parent, under your account)
• View your copy of the repo at http://github.com/YOURGITHUBUSERNAME/xmpp4r/tree/master
• Click on the link that says : “Your Clone URL”, copy and paste this into your terminal window.
• You will start out on the ‘master’ branch. This is where your commits should end up eventually. Any private branches you create will likely not be seen by others.
• Create a working or ‘topic’ branch with ‘git checkout -b my_new_branch_name master’. You’ll now be on the new branch.
• Hack. Commit. Hack. Commit. Hack. Commit. etc…
• Stand back and admire your new code. Make sure you have tests, comments, docs created and ‘rake test’ still passes.
• ‘git checkout master’
• ‘git pull’
• ‘git merge my_new_branch_name’
• ‘git push’ # pushes your code back to your fork on GitHub
• Go visit GitHub, look at your commit, and send a URL for your commit to the ‘xmpp4r-devel AT gna DOT org’ devel list for review. If no-one has any issues or changes for you then:
• Go to the github site for your fork and click ‘pull request’. This sends a message to those users you specify. ‘ln’ is Lucas’ account and is the ‘master’ repo for us. (Equivalent to the central repo in the SVN world).
• Lucas, or one of us, will review your changes, and pull them into the master.
• You can track progress of your fork against the master here: http://github.com/ln/xmpp4r/network

Use and keep your fork current with the master Git repository

A key difference between a Git fork, when compared to either a simple Git clone, or an SVN checkout, is that your fork will never keep itself up to date with the master repo unless you do it. Fortunately, there is a simple tool to help you do this. Your fork is separate and equal to the master in Git terms so if you want to track changes to the master you can create a tracking branch in your forked repo and merge those changes into your fork’s master branch whenever you want to commit something.

I highly recommend the ‘GitHub’ gem which is a tool you can install to help you easily track changes in any other repository related to yours. See the README text at the bottom of this page for installation and usage:

http://github.com/defunkt/github-gem/tree/master

Once this is installed you can do something like:

• I see my master branch is out of date since I have not updated it in a while.
• I installed the GitHub gem and do ‘github pull ln’ (note ‘github’ command and not ‘git’!)
• This will create a tracking branch in your local repo and put you on that branch.
• Checkout your master branch and do ‘git rebase ln/master’

All that is too complicated. What if I just want to track a simple clone of the master repo? And submit patches like I used to?

The steps above look complicated when you read them. But once you do them once or twice it really starts to be easy and fast.

However, If you prefer to work in a model that is much more similar to the traditional SVN model, or you don’t want to change code but just want to track it locally, feel free to clone the master directly with:

git clone git://github.com/ln/xmpp4r.git

and then a simple ‘git pull’ anytime on the master branch will keep you up to date with the latest and greatest.

If you want to submit patches from a simple clone you should not make commits on the master branch. Instead you should create a ‘topic’ branch for all your development commits and when ready to submit them do:

git format-patch master

This will generate one Git patch file for each commit on your topic branch and you can then email those to the devel list. Don’t merge these commits with your master branch. Later, when your patches are accepted and merged to the master you’ll see them show up on your local master with a ‘git pull’ on your master branch. Once they show up on the master branch from upstream you can delete your local topic branch with ‘git branch -d my_cool_topic_branch’.