How to Use Git: a Tutorial

This document is a work in progress.

Git is a free & open source, distributed version control system designed to handle everything from small to very large projects with speed and efficiency...

Git can be a little confusing at first when coming from a Subversion background. In this tutorial, we'll write the Subversion terms in italic.

The most important things to remember about git are:

• it is distributed: every checkout is actually a clone of the master repository, this means that there is no higher authority or single point of failure. Effectively every developer has it own repository with its own branches and own commits.
• because of that, it can also be describe as disconnected: one does not need to access the master repository in order to commit, branch, merge or review the history.
• this makes all operations that would normally use the Subversion server __usable__ (checking commit log, blame, branching and merging).
• it is storage efficient: the Opentaps repository in Git including 1.0.0 / 1.4 / 1.0 and all the branches and tags takes around 900Mo, typically a SVN checkout of 1.4 alone would be more than 600M, multiply this be each branch and by each tag ...

Probably one of the most important point is branching. Because Subversion branches are difficult to merge and expensive to create (one need to do a whole checkout to get a branch) they are mostly used as dead branches.

In comparison, in Git branches are very easy to create and merge back. In the git way of thinking, they are "free," and because they are local they are actually used all the time. The reason why a complete Git repository of opentaps is only 900Mo instead of a few gigabyte is because they all share a lot of common content.

Git branches are typically used for:

• local only configuration
• unit of work (tickets)
• client and sub projects

Local Configuration Branch

One of the first thing that we all do is the configuration of the database in `entityengine.xml`, and in subversion we have to lock the file else it ends up accidentally modified.

In Git one could instead use a configuration branch.

This branch can be considered a floating branch, because we want to apply it on top of whatever branch we are currently working on.

*-----[master]----[work]----[configuration]

Unit of work Branch

Let's say you want to work on a feature. With git, You can create a branch for your feature, work on it, and then merge it back to the main branch. A typical workflow is, from

*-----[master]

Create a working branch:

*-----[master][1234-some-ticket]

Make some commits, so your 1234-some-ticket branch advances further:

*-----[master]---[1234-some-ticket]

Then push the branch on `origin` for review, and have the reviewer merge it:

*-----o------[master]
      |                       
       \---[1234-some-ticket]

master> git merge 1234-some-ticket

*-----o-----------------------(1234 merged)[master]
      |                       |
       \---[1234-some-ticket]/

If we do not want the reviewer to do any conflict resolution and want to do it ourselves, we can merge the master into our 1234-some-ticket branch first:

*-----o------[master]
      |                       
       \---[1234-some-ticket]

1234-some-ticket> git merge master

*-----o------[master]
      |             |
       \------------(master merged)[1234-some-ticket]
<

Note that all of this do not mean that the branch has be local until ready, it can be pushed little by little.

We can then push it back to the master. This only produce one merge commit in the `master` branch per ticket / feature. This makes it easier for third parties to follow.

Client and Sub Projects

Typically clients implementing opentaps or developers creating a project based on it use their own subversion repository created from a checkout of opentpas. Luckily the architecture of opentaps allow them to only store a custom hot-deploy component, but sometimes this is still a bit limited and as we know they end up touching code outside of there own components. Finally they sometimes request features / bug fixes that we implement in both our and their repository.

Having the ability to clone our repository and branch it easily means that the changes they make are contained in their branch. It also makes it easier for them to receive updates from the main opentaps repository. Finally, by setting up their repository as a new remote (eg: `client-origin`), you can have many clients in the same local repository (saving some disk space in the process). All that is needed is an SSH access, which is much easier to setup than a SVN server.

*--o--o-----------------------------[origin/master]
   |  |                                 |     |
   |  |                                 |     |  
   |  \----------[client-origin1/client]| [merged]
   |                                    |
   |                                    |
    \---------[client-origin2/client] [merged]