GitUsage · Biopython

Python Tools for Computational Molecular Biology
These are (draft) general guidelines for Biopython development using git. We’re still working on the finer details etc.
This document is meant as an outline of the way Biopython is developed. It should include all essential technical information as well as typical procedures and usage scenarios. It should be helpful for core developers, potential code contributors, testers and everybody interested in Biopython code.
This version is an unofficial draft and is subject to change.
If you just want to grab the latest (not yet officially released) Biopython from our repository, see our source code page. This page is about actually using git for tracking changes.
If you have found a problem with Biopython, and think you know how to fix it, then we suggest following the simple route of filing a bug and describe your fix. Ideally, you would upload a patch file showing the differences between the latest version of Biopython (from our repository) and your modified version. Working with the command line tools diff and patch is a very useful skill to have, and is almost a precursor to working with a version control system.
You shouldn’t go to the trouble of creating your own git fork unless you are intending to make more than a simple one off contribution.
This section describes technical introduction into git usage including required software and integration with Github. If you want to start contributing to Biopython, you definitely need to install git and learn how to obtain a branch of Biopython. If you want to share your changes easily with others, you should also sign up for a Github account and read the corresponding section of the manual. Finally, if you are engaged in one of the collaborations on experimental Biopython modules, you should look also into code review and branch merging.
You will need to install Git on your computer. Git is available for all major operating systems. Please use the appropriate installation method as described below.
Git is now packaged in all major Linux distributions, you should find it in your package manager.
You can install Git from the git-core package. e.g.,
You’ll probably also want to install the following packages: gitk, git-gui, and git-doc
git is also packaged in rpm-based linux distributions.
should do the trick for you in any recent fedora/mandriva or derivatives
Download the .dmg disk image from http://code.google.com/p/git-osx-installer/
Download the official installers from Windows installers
If your installation succeeded, you should be able to run
in a console window to obtain information on git usage. If this fails, you should refer to git documentation for troubleshooting.
Once you have Git installed on your machine, you can obtain the code and start developing. Since the code is hosted at GitHub, however, you may wish to take advantage of the site’s offered features by signing up for a GitHub account. While a GitHub account is completely optional and not required for obtaining the Biopython code or participating in development, a GitHub account will enable all other Biopython developers to track (and review) your changes to the code base, and will help you track other developers’ contributions. This fosters a social, collaborative environment for the Biopython community.
If you don’t already have a GitHub account, you can create one here. Once you have created your account, upload an SSH public key by clicking on ‘SSH and GPG keys’ after logging in. For more information on generating and uploading an SSH public key, see this GitHub guide.
In order to start working with the Biopython source code, you need to obtain a local clone of our git repository. In git, this means you will in fact obtain a complete clone of our git repository along with the full version history. Thanks to compression, this is not much bigger than a single copy of the tree, but you need to accept a small overhead in terms of disk space.
There are, roughly speaking, two ways of getting the source code tree onto your machine: by simply “cloning” the repository, or by “forking” the repository on GitHub. They’re not that different, in fact both will result in a directory on your machine containing a full copy of the repository. However, if you have a GitHub account, you can make your repository a public branch of the project. If you do so, other people will be able to easily review your code, make their own branches from it or merge it back to the trunk.
Using branches on Github is the preferred way to work on new features for Biopython, so it’s useful to learn it and use it even if you think your changes are not for immediate inclusion into the main trunk of Biopython. But even if you decide not to use github, you can always change this later (using the .git/config file in your branch.) For simplicity, we describe these two possibilities separately.
Getting a copy of the repository (called “cloning” in Git terminology) without GitHub account is very simple:
This command creates a local copy of the entire Biopython repository on your machine (your own personal copy of the official repository with its complete history). You can now make local changes and commit them to this local copy (although we advise you to use named branches for this, and keep the master branch in sync with the official Biopython code).
If you want other people to see your changes, however, you must publish your repository to a public server yourself (e.g. on GitHub).
If you are logged in to GitHub, you can go to the Biopython repository page:
https://github.com/biopython/biopython/tree/master
and click on a button named ‘Fork’. This will create a fork (basically a copy) of the official Biopython repository, publicly viewable on GitHub, but listed under your personal account. It should be visible under a URL that looks like this:
https://github.com/yourusername/biopython
Since your new Biopython repository is publicly visible, it’s considered good practice