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:

  1. Fork the Primer3Redux project on GitHub (click the big “Fork” button)
  2. Clone my new GitHub Bio-Tools-Primer3Redux repository to my local machine:
      git clone git@github.com:cassj/Bio-Tools-Primer3Redux.git
    
  3. 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.

      git remote add upstream git://github.com/cjfields/Bio-Tools-Primer3Redux.git
    
  4. Create a branch

    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
    
  5. checkout new branch
      git checkout universal_removal
    
  6. 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.

  7. When I’m done, I can return to the main branch:
      git checkout master
    
  8. Pull any upstream changes
      git fetch upstream
      git merge upstream/master
    
  9. merge the completed changes from the branch
      git merge universal_removal
    
  10. 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
    
  11. Run any tests to make sure the changes work ok.
  12. 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
    
  13. 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.

    Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s