Using git With Multiple QGIS Branches

This post is for those of you that build QGIS on a regular basis and want to keep up with everything going on in the current release branches (1.7.2 and 1.8) as well as the master branch that will eventually become version 2.0.

While you can do all your work in one clone, this method has a couple of advantages, at the expense of a bit of disk space:

  1. Quicker compiles compared to branch switching, especially if you are using ccache
  2. Less likelihood of making a merge mess when switching branches

The basic steps are:

  1. Login to github and clone the QGIS repository (https://github.com/qgis/Quantum-GIS)
  2. Create a working copy of your github clone on your machine
  3. Add a reference to the upstream repository
  4. Fetch and merge (if required) from the upstream repository
  5. Create a new clone for the branch by cloning the working copy created in step 2
  6. Change to the branch clone directory
  7. Add the upstream remote
  8. Fetch from upstream
  9. Create the tracking branch
  10. Checkout the branch

It’s simpler than it sounds—the following steps should work on any platform and assume you have already created your own clone of the QGIS repository on github.

First make a directory for development, change to it, and fetch a copy of your clone of QGIS from github (this will take a while):

    gsherman@dork:~$ mkdir qgis_dev
    gsherman@dork:~$ cd qgis_dev
    gsherman@dork:~/qgis_dev$ git clone git@github.com:g-sherman/Quantum-GIS.git
    Cloning into Quantum-GIS...
    remote: Counting objects: 183812, done.
    remote: Compressing objects: 100% (42255/42255), done.
    remote: Total 183812 (delta 140627), reused 183281 (delta 140221)
    Receiving objects: 100% (183812/183812), 240.80 MiB | 1.19 MiB/s, done.
    Resolving deltas: 100% (140627/140627), done.

Now change to your new clone directory and add the upstream repository (the QGIS repo on github):


    gsherman@dork:~/qgis_dev$ cd Quantum-GIS/
    gsherman@dork:~/qgis_dev/Quantum-GIS$ git remote add upstream git@github.com:qgis/Quantum-GIS.git

We can then list our config to see that the remote was added:

    gsherman@dork:~/qgis_dev/Quantum-GIS$ git config --list
    core.repositoryformatversion=0
    core.filemode=true
    core.bare=false
    core.logallrefupdates=true
    remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
    remote.origin.url=git@github.com:g-sherman/Quantum-GIS.git
    branch.master.remote=origin
    branch.master.merge=refs/heads/master
    remote.upstream.url=git@github.com:qgis/Quantum-GIS.git
    remote.upstream.fetch=+refs/heads/*:refs/remotes/upstream/*

Then we do a fetch from the QGIS repo to make sure things are up to date:


    gsherman@dork:~/qgis_dev/Quantum-GIS$ git fetch upstream

If your clone of the QGIS repository on github is not brand new, you should do a merge before proceeding:


    gsherman@dork:~/qgis_dev/Quantum-GIS$ git merge upstream/master

Now we can create a new clone for the 1.7.2 branch using our local master:

    gsherman@dork:~/qgis_dev/Quantum-GIS$ cd ..
    gsherman@dork:~/qgis_dev$ git clone ./Quantum-GIS Quantum-GIS-1_7_2
    Cloning into Quantum-GIS-1_7_2...
    done.

Now we need to add the remote for the main QGIS repository:


    gsherman@dork:~/qgis_dev$ cd Quantum-GIS-1_7_2/
    gsherman@dork:~/qgis_dev/Quantum-GIS-1_7_2$ git remote add upstream git@github.com:qgis/Quantum-GIS.git

The next step is to fetch from upstream to make sure we have references to the branches:

    gsherman@dork:~/qgis_dev/Quantum-GIS-1_7_2$ git fetch upstream
     * [new branch]      dev-threading -> upstream/dev-threading
     * [new branch]      master     -> upstream/master
     * [new branch]      release-0_0_11 -> upstream/release-0_0_11
     * [new branch]      release-0_0_12 -> upstream/release-0_0_12
     ...
     * [new branch]      release-1_7_1 -> upstream/release-1_7_1
     * [new branch]      release-1_7_2 -> upstream/release-1_7_2
     * [new branch]      release-1_8 -> upstream/release-1_8

Now we create the branch to track the release of interest—in this case 1.7.2:


    gsherman@dork:~/qgis_dev/Quantum-GIS-1_7_2$ git branch --track release-1_7_2 upstream/release-1_7_2
    Branch release-1_7_2 set up to track remote branch release-1_7_2 from upstream.

The last step is to check out the branch which should go pretty quick:

    gsherman@dork:~/qgis_dev/Quantum-GIS-1_7_2$ git checkout release-1_7_2
    Checking out files: 100% (1809/1809), done.
    Switched to branch 'release-1_7_2'

You are now ready to build the 1.7.2 release branch. Repeat the process for any other branches you want to track.