lessons/VersionControlWithGit-Copy0_hold.ipynb

{
 "metadata": {
  "name": "",
  "signature": "sha256:3ec063cdb3b392740d3db1844eede02c47a6cdf710869d8aec656687a9826548"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "heading",
     "level": 1,
     "metadata": {},
     "source": [
      "Version Control with Git"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "In this lesson, we will create a repository on GitHub, create a Makefile and generate a latex document with results from R and Python.  "
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Git is a version control system that allows you to keep track of changes to your code.  Everything you do is saved and documented, leaving a record of your entire development process.  It also helps manage a project when there are several developers working together.  We will not cover some of the more intricate details, such as branching, but we will demonstrate how git may be used in the context of 'reproducible research'.\n",
      "\n",
      "\n",
      "\n",
      "To begin, if you do not already have a github account, [create one](https://github.com/index.html).  Once you have an account, sign in."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "One the upper right hand side of the tab, click the '+' sign next to your user name."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "When prompted, give your repository a name.  Set it to public (private requires a fee), and click the box to initialize with a README.  Then, just click 'create repository'."
     ]
    },
    {
     "cell_type": "heading",
     "level": 3,
     "metadata": {},
     "source": [
      "Create a Makefile"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Now, enter the repository and click the '+' at the top of the page to create a new file.  Call this file 'Makefile'.\n"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "The following Makefile and an excellent bare bones tutorial can be found at: http://kbroman.org/minimal_make/:\n",
      "\n",
      "\\# Cut and paste this into your Makefile on Github \n",
      "\n",
      "\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\# Begin Makefile \\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\n",
      "\n",
      "    mypaper.pdf: mypaper.tex Figs/fig1.pdf Figs/fig2.pdf  \n",
      "\n",
      "    # The target is 'mypaper.pdf and what follows after the ':' are dependences\n",
      "\n",
      "        pdflatex mypaper  # run pdflatex\n",
      "    #   bibtex mypaper    # run bibtex\n",
      "        pdflatex mypaper  # run latex\n",
      "        pdflatex mypaper  # run latex (again)  \n",
      "\n",
      "    Figs/fig1.pdf: R/fig1.R     \n",
      "    # Target is 'Figs/fig1.pdf' - it depends on an 'R' script called 'fig1.R'\n",
      "        -mkdir Figs\n",
      "         cd R;R CMD BATCH fig1.R # Go to R directory and execute the script to create fig1\n",
      "\n",
      "    Figs/fig2.pdf: R/fig2.R     \n",
      "    # same for fig2  \n",
      "         cd R;R CMD BATCH fig2.R\n",
      "    \n",
      "\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\# End Makefile \\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\n"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Unfortunately, make has a very fussy syntax: Commands must be preceded by a tab character.  When you copy and paste from the above, you'll need to replace the spaces in front of each command with a tab character.  Also, be sure to switch the spacing option at the top to 'Tabs'.  \n",
      "\n",
      "When you are done, commit your changes.  "
     ]
    },
    {
     "cell_type": "heading",
     "level": 3,
     "metadata": {},
     "source": [
      "Create R Scripts\n"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Now, click return to the top-level directory of your repository.  Click '+' once again to add a file, this time choose the filename:\n",
      "\n",
      "R/fig1.R"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\# Begin R Script \\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\n",
      "\n",
      "library(ggplot2)\n",
      "\n",
      "data=data.frame(x=rnorm(100))\n",
      "\n",
      "plot=qplot(x, data=data, geom=\"histogram\") \n",
      "\n",
      "ggsave(plot,file=\"../Figs/fig1.pdf\")\n",
      "\n",
      "\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\# End R Script \\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Create R/fig2.R:\n",
      "   \n",
      "\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\# Begin R Script \\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\n",
      "\n",
      "library(ggplot2)\n",
      "\n",
      "data=data.frame(x=rexp(100))\n",
      "\n",
      "plot=qplot(x, data=data, geom=\"histogram\") \n",
      "\n",
      "ggsave(plot,file=\"../Figs/fig2.pdf\")\n",
      "\n",
      "\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\# End R Script \\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\n",
      "    "
     ]
    },
    {
     "cell_type": "heading",
     "level": 3,
     "metadata": {},
     "source": [
      "Create Latex file"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Add another file in the top-level directory called \"mypaper.tex\".  Add the following content:\n",
      "    \n",
      "\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\# Begin Latex Document \\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\n",
      "\n",
      "    \\documentclass[12pt]{article}\n",
      "    \\usepackage{graphics}\n",
      "\n",
      "\n",
      "    \\begin{document}\n",
      "    \\huge{Latex Document with Figures}\n",
      "    \\begin{figure}[!p]\n",
      "    \\centering\\includegraphics{Figs/fig1.pdf}\n",
      "    \\caption{Histogram of normally distributed values}\n",
      "    \\label{Fig1}\n",
      "    \\end{figure}\n",
      "\n",
      "    \\begin{figure}[!p]\n",
      "    \\centering\\includegraphics{Figs/fig2.pdf}\n",
      "    \\caption{Histogram of normally distributed values}\n",
      "    \\label{Fig1}\n",
      "    \\end{figure}\n",
      "\n",
      "    \\end{document}\n",
      "\n",
      "\n",
      "\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\# End Latex Document \\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#\\#"
     ]
    },
    {
     "cell_type": "heading",
     "level": 3,
     "metadata": {},
     "source": [
      "Clone your repository to your AMI:"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Create a directory on your AMI called \"GitExample\":\n",
      "    \n",
      "\\$ mkdir GitExample\n",
      "\n",
      "\\$ cd GitExample\n"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Copy the url of your github repository to the clipboard and issue the following command on your AMI in the GitExample directory:\n",
      "    \n",
      "    \n",
      "\\$ git clone *your url*"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "You should now have local copies of all of your repository files and directories."
     ]
    },
    {
     "cell_type": "heading",
     "level": 3,
     "metadata": {},
     "source": [
      "Now you can run the project:"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "cd to the repository directory, and type:\n",
      "\n",
      "        $ make"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "This one command now generates the paper. If you need to change anything in your R code, you can update the paper just by running make!\n"
     ]
    },
    {
     "cell_type": "heading",
     "level": 3,
     "metadata": {},
     "source": [
      "Modifying and Updating"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Let's modify a file locally and then update the github repository.  Use your favorite text editor to change the R code in your local copy of the repository to generate 100 uniformly distributed numbers (between 0 and 1).  When you are finished, commit your changes.  From the top-level directory, type:\n",
      "\n",
      "    $ git commit R/fig1.R\n",
      "\n",
      "\n",
      "You will be prompted to enter a commit message.  Type something *meaningful* - such as \"Changed to generate a histogram of values generated from the uniform distribution\".  Hit Cntrl-X to exit, use defaults to save/name buffer.\n",
      "\n",
      "Now type:\n",
      "\n",
      "    $ git push\n",
      "    \n",
      "    \n",
      "You will be prompted to enter your github login information.  Git will update the github repository.  Go back the github repository and look in the R directory.  You will find fig1.R listed with your commit message.\n",
      "\n",
      "\n",
      "Now, let's do the opposite.  We'll change some files on github and then update the local repository.\n",
      "\n",
      "\n",
      "Add a file fig3.R, to create a histogram of 100 values drawn from the normal distribution.  Change the Makefile and latex file to accomodate this third figure.  When you are finished, return to your AMI, and from the top-level directory of the repository, type:\n",
      "\n",
      "git pull *your url*\n",
      "\n",
      "\n",
      "Now typ\n",
      "\n",
      "\n"
     ]
    }
   ],
   "metadata": {}
  }
 ]
}