Home

Forking Psi: Step-by-step Guide

Installing Git

1. Mac OS X.
   The easiest way to get relatively fresh version of Git on Mac OS X is through MacPorts. After getting and installing MacPorts, it’s just a simple matter of:
   sudo port install git-core +svn

   If you don’t want to interact to SVN repositories through Git (it’s actually very usable), you could omit the +svn part of the command.

2. Linux. sudo apt-get install git-core should do the trick for Ubuntu users. The package also may be named git in other distributions.
3. Windows. There’s a guide for Windows users, hosted on github.com.

Initializing fork on github.com

1. Get an account on github.com.
2. Go to the master Psi branch.
   
3. Click on fork button.

Downloading forked code

1. Make sure that your account contains your SSH Public Key, otherwise you’ll be unable to commit to your repository.
2. Go to master branch of your fork (be sure to replace hummbl with your own username).
   
3. Note the Your Clone URL. You’ll be using it now.
4. Time to open a Terminal. Type away:
   git clone [email protected]:hummbl/psi.git psi-fork
5. Your fork is now ready for hacking.

Compiling Psi

1. cd psi-fork
2. git submodule add git://github.com/mblsha/iris.git iris
3. ./configure --enable-debug
4. make -j 2

Reviewing diffs and committing patches

You’re welcome to read one of Git Crash Courses. They’re short and up to the task.

Note: For TextMate there’s a very useful Git Bundle.

Pushing your patches back to github

git push is your friend here.

Getting patches back to the Psi Team

There a “pull request” button on your fork branch page. Clicking it reveals a small form.

Staying on the bleeding edge

Once you’ve got some custom patches, chances are high that the master Psi branch has moved further ahead. Rebasing your patches on top of the master Psi branch will get all the new stuff from there, plus it will apply all the code you’ve written on top of it. And if some of your patches will make it into the main repository, you won’t have to worry about them anymore.

UPD: see Keeping a git fork in sync with the forked repo for the general approach that’s follows the git spirit.

1. git remote add psi-master git://github.com/mblsha/psi.git — should only be issued once in order to initialize the ‘psi-master’ name.
2. git fetch psi-master will update the contents of ‘psi-master’ remote.
3. It’s a good idea to issue gitk --all now.
   
4. If you have some uncommitted changes, do git stash. After rebase is done you could return them in place using git stash apply (and don’t forget to clear the stash buffer using git stash clear).
5. Time to rebase our custom patches on top of main Psi ones.
   git rebase git rebase psi-master/master
6. Now our commit history is flat again, as could be visible on gitk --all screenshot:
   
7. Since we’ve modified commit history by doing rebase (it’s actually considered evil in the Git world, but it seems to be inevitable as the Psi Team still interacts with the central SVN repository. Please correct me if I’m wrong), in order to propagate our updated tree to the github repository, we must the git push --force command.