Git, Github, Forking etc.

I’m using Chris Field’s Bio::Tools::Run::Primer3Redux for something and there was a typo in it that needed fixing. Turned out it was a mis-spelling of UNIVERSAL, but Chris decided it would be better to get rid of all the UNIVERSAL::isa calls as there are better ways of checking type. Seemed like a good time to get my head around forking git/github projects and submitting pull requests. So, here’s how I think it works:

Fork the Primer3Redux project on GitHub (click the big “Fork” button)

Clone my new GitHub Bio-Tools-Primer3Redux repository to my local machine:

git clone git@github.com:cassj/Bio-Tools-Primer3Redux.git

Pull changes

If I pull from this repository I will get changes from my forked Primer3Redux. Nobody else has a commit bit for this repository, so I won’t need to pull in other peoples changes but I could feasibly want to pull my own changes, for example to keep repositories on my work box and my laptop in sync.

I also need to be able to pull in changes from Chris’s Primer3Redux repository though, so I add it as a remote repository called “upstream”. Note that I’m using the public URL here – I can only pull, I can’t commit to it.

I could just make changes to the master branch of my forked repository, but what if I notice another thing I can fix, fix it and want to submit those changes without having to finish fixing all the UNIVERSAL::isa stuff? This is what branches are for. Create a branch for the UNIVERSAL stuff:

git branch universal_removal

checkout new branch

git checkout universal_removal

make changes needed to fix UNIVERSAL::isa problem on that branch.

I can do stuff like:

git add newfile.pm
git commit -a

to that branch without messing with the master branch.

When I’m done, I can return to the main branch:

git checkout master

Pull any upstream changes

git fetch upstream
git merge upstream/master

merge the completed changes from the branch

git merge universal_removal

Resolve any conflicts

If there are conflicts, you can find out where they are with:

git diff

then you can edit the files to fix the conflicts and complete the merge with a

git commit -a

And just in case it goes totally tits up and is an unresolvable mess, totally give up on the merge with

git reset --hard HEAD

Run any tests to make sure the changes work ok.

push changes to GitHub

Assuming I’ve now got the UNIVERSAL::isa fixes in my master branch, then I can push the changes to my forked GitHub Primer3Redux

git push origin master

Send a pull request

Offer the fix to the Primer3Redux devs by hitting the “Pull request” button from my forked bioperl-run on GitHub. They can then have a look, check they’re ok and apply them to the main code.