Version Control and Error Tracking

This tutorial is an showcasing the material collected in the Pro Git book which is avilable for free online. I also draw on a set of excellent Scientific Python Lecture Notes maintained by Robert Johansson.

Roadmap

Basics
Tutorials
- Git
- GitHub

Definition: Version Control is a system that records changes to a file or set of files over time so that you can recall specific versions later.

Implementations

Local Version Control System
Centralized Version Control System
Distributed Version Control System

Local Version Control System

Centralized Version Control System

Distributed Version Control Systems

Tools

Git
GitHub

Let us get started!



In [ ]:

    
import os

try:
    
    os.mkdir('me')

except OSError:
    
    pass
    
os.chdir('me')

Setting Up



In [ ]:

    
%%bash
echo 'How does our directory look like?'
ls -al

git init

echo 'How does our directory look like now?'
ls -al

git status

# Let us create files for tracking.
echo 'My Project' > README
echo 'peisenha' > CONTRIBUTING.md

# Set up our identity
git config --global user.name  "Philipp Eisenhauer"
git config --global user.email "eisenhauer@policy-lab.org"

Recording Changes to the Repository



In [ ]:

    
%%bash
git add README
git status



In [ ]:

    
%%bash
git add CONTRIBUTING.md
git commit -a -m'initial'



In [ ]:

    
%%bash
echo 'Philipp Eisenhauer' > CONTRIBUTING.md



In [ ]:

    
%%bash
git status



In [ ]:

    
%%bash
git commit -a -m'changes to contributers'

Removing and Moving File



In [ ]:

    
%%bash
# Remove files
git rm README
git status



In [ ]:

    
%%bash
# Move files
git mv CONTRIBUTING.md CONTRIBUTORS.md
git status



In [ ]:

    
%%bash
git commit -m'reorganizing files'

Viewing the Commit History



In [ ]:

    
%%bash
git log

Adding a Remote Repository

Let us create a repository called try_git in our GitHub accounts



In [ ]:

    
%%bash
git remote add origin git@github.com:peisenha/try_git.git
git push -u origin master



In [ ]:

    
%%bash
git clone git@github.com:peisenha/try_git.git ../other

While we are at it, let us check out the class repository.



In [ ]:

    
%%bash
git clone git@github.com:softEcon/course.git /home/vagrant/course_material

From now on, you will find all class material in this repository.

Tracking Changes

GitHub allows to visualize changes to files over time.

Tagging

Types:

Lightweight, pointer to specific commit
Annotated, lightweight tag with additional information

I use annotated tags to release different versions of my research software. You can check it out an example here.



In [ ]:

    
%%bash
# Create tag
git tag -a v1.0 -m'ouf first tag annotated tag'



In [ ]:

    
%%bash
# List tag
git tag -l



In [ ]:

    
%%bash
# Push to remote repository
git commit -a m'added first tag'
git push origin --tags

Let us take a look at our repository in a repository viewer. We choose gitg and can install it using the Ubuntu Software Center.

Git Branching

A Commit and its Tree

Objects

Commit
Tree
Blobs

Commits and their Parents

A Branch and its Commit History

A branch is a lightweight movable pointer to one of the commits. The HEAD is an additional pointer to the local branch you are currently working on.

Creating a New Branch

I ususally create a branch for each feature I would like to add to my research software. Once I satisfied with my implementation I merge the development branch back into master.



In [ ]:

    
%%bash
git branch testing



In [ ]:

    
%%bash
git branch -a



In [ ]:

    
%%bash
git log --oneline --decorate

Switching between Branches

Sometimes I will work on the integration and testing of two new features at the same time. Or, even better, somebody else is adding a feature at the same time. In both cases, I can easily switch between branches.



In [ ]:

    
%%bash
git checkout testing
echo 'Some information on the project.' > README 
git add README
git commit -a -m'adding project information'

Let us check how the content of the directory change as we move between the different branches.



In [ ]:

    
%%bash
git checkout master



In [ ]:

    
%%bash
git checkout testing

Basic Merging

At some point I am hopefully done with my code improvement and it is time to merge my development branch into master.



In [ ]:

    
%%bash
git checkout master
echo 'Some other information on the project.' > README 
git add README
git commit -a -m'adding other project information'



In [ ]:

    
%%bash
git merge master testing



In [ ]:

    
%%bash
git add README
git commit -m'fixed merge conflict'

Let us clean up our branches by deleting testing and keep our repository in good standing.



In [ ]:

    
%%bash
git branch -d testing
git branch -a

Summary

The use of a version control system allows us to improve our economic research in a variety of ways. In my case, I use Git for all my software projects. The debugging process is speed up considerably as I can track back in time and pin down when I introduced a new error. GitHub allows me to easily collaborate with other researchers (or research assistants) and promote my work to a broader audience.

Cleanup



In [ ]:

    
import shutil

os.chdir('../')

for dir_ in ['me', '.ipynb_checkpoints', 'other']:
    
    try:
        
        shutil.rmtree(dir_)
        
    except OSError:
        
        pass

Miscellaneous

You find some additional resources on version control here.

Formatting



In [2]:

    
import urllib; from IPython.core.display import HTML
HTML(urllib.urlopen('http://bit.ly/1K5apRH').read())









    Out[2]: