GitIntro.ipynb

{
 "metadata": {
  "name": ""
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "skip"
      }
     },
     "source": [
      "<style>\n",
      "div.cell, div.text_cell_render{\n",
      "  max-width:750px;\n",
      "  margin-left:auto;\n",
      "  margin-right:auto;\n",
      "}\n",
      "\n",
      ".rendered_html\n",
      "{\n",
      "  font-size: 140%;\n",
      "  }\n",
      "\n",
      ".rendered_html li\n",
      "{\n",
      "  line-height: 1.8;\n",
      "  }\n",
      "\n",
      ".rendered_html h1, h2 {\n",
      "  text-align:center;\n",
      "  font-familly:\"Charis SIL\", serif;\n",
      "}\n",
      "</style>"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "<small><i>This notebook was put together by [Jake Vanderplas](http://www.vanderplas.com) for UW's [Astro 599](http://www.astro.washington.edu/users/vanderplas/Astr599/) course. Source and license info is on [GitHub](https://github.com/jakevdp/2013_fall_ASTR599/).</i></small>"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "# Version control for fun and profit:\n",
      "\n",
      "## the tool you didn't know you needed\n",
      "\n",
      "#### Sources of this material:\n",
      "\n",
      "This tutorial is adapted from \n",
      "[\"Version Control for Fun and Profit\"](http://nbviewer.ipython.org/urls/github.com/fperez/reprosw/raw/master/Version%2520Control.ipynb) by Fernando Perez\n",
      "\n",
      "For an excellent list of Git resources for scientists, see [Fernando's Page](http://www.fperez.org/py4science/git.html).\n",
      "\n",
      "Fernando's original notebook specifically mentions two references he drew from:\n",
      "\n",
      "- [\"Git for Scientists: A Tutorial\"](http://nyuccl.org/pages/GitTutorial) by John McDonnell \n",
      "- Emanuele Olivetti's lecture notes and exercises from the G-Node summer school on [Advanced Scientific Programming in Python](https://python.g-node.org/wiki/schedule).\n",
      "\n",
      "Via Fernando, some of the images below are copied from the [Pro Git book](http://git-scm.com/book)\n",
      "\n",
      "Also see [J.R. Johansson](https://github.com/jrjohansson)'s [tutorial on version control](http://nbviewer.ipython.org/urls/raw.github.com/jrjohansson/scientific-python-lectures/master/Lecture-7-Revision-Control-Software.ipynb), part of his excellent series [Lectures on Scientific Computing with Python](https://github.com/jrjohansson/scientific-python-lectures)"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "## What is Version Control?\n",
      "\n",
      "#### From Wikipedia:\n",
      "\u201cRevision control, also known as version control, source control\n",
      "or software configuration management (SCM), is the\n",
      "**management of changes to documents, programs, and other information stored as computer files.**\u201d\n",
      "\n",
      "#### Reproducibility?\n",
      "\n",
      "* Tracking and recreating every step of your work\n",
      "* In the software world: it's called *Version Control*!\n",
      "\n",
      "What do (good) version control tools give you?\n",
      "\n",
      "* Peace of mind (backups)\n",
      "* Freedom (exploratory branching)\n",
      "* Collaboration (synchronization)\n"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "## Git is an enabling technology: Use version control for everything\n",
      "* Paper writing (never get ``paper_v5_jake_final_oct22_9.tex``\n",
      "  by email again!)\n",
      "* Grant writing\n",
      "* Everyday research\n",
      "* Teaching (never accept an emailed homework assignment again!)\n",
      "* Code management\n",
      "* Personal website history tracking"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "## The plan for this tutorial\n",
      "\n",
      "- Overview of Git key concepts\n",
      "\n",
      "- Hands-on work with Git\n",
      "\n",
      "- 5 \"stages\" of using Git:\n",
      "            \n",
      "    1. Local, single-user, linear workflow\n",
      "    2. Single local user, branching\n",
      "    3. Using remotes as a single user\n",
      "    4. Remotes for collaborating in a small team\n",
      "    5. Full-contact github: distributed collaboration with large teams"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "## High level picture: overview of key concepts\n",
      "\n",
      "The **commit**: *a snapshot of work at a point in time*\n",
      "\n",
      "![](files/images/commit_anatomy.png)\n",
      "\n",
      "Credit: ProGit book, by Scott Chacon, CC License."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### Looking at my current directory:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "!ls"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "00_intro.ipynb                    myfile.html\r\n",
        "01_basic_training.ipynb           myfile.py\r\n",
        "02_advanced_data_structures.ipynb myfile.pyc\r\n",
        "03_IPython_intro.ipynb            mymodule.py\r\n",
        "04_Functions_and_modules.ipynb    mymodule.pyc\r\n",
        "05_NumpyIntro.ipynb               mymodule2.py\r\n",
        "05_Trapezoid_Solution.ipynb       mymodule2.pyc\r\n",
        "06_Denoise_Solution.ipynb         number_game.py\r\n",
        "06_MatplotlibIntro.ipynb          style.css\r\n",
        "07_GitIntro.ipynb                 test.npy\r\n",
        "README.txt                        test.npz\r\n",
        "\u001b[34mimages\u001b[m\u001b[m                            test.out\r\n",
        "modfun.py                         tmp.py~\r\n"
       ]
      }
     ],
     "prompt_number": 1
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "A **repository**: a group of *linked* commits\n",
      "\n",
      "![](files/images/threecommits.png)\n",
      "\n",
      "Note: these form a Directed Acyclic Graph (DAG), with nodes identified by their *hash*."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "A **hash**: a fingerprint of the content of each commit *and its parent*"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "import sha\n",
      "\n",
      "# Our first commit\n",
      "data1 = 'This is the start of my paper2.'\n",
      "meta1 = 'date: 1/1/12'\n",
      "hash1 = sha.sha(data1 + meta1).hexdigest()\n",
      "print 'Hash:', hash1"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Hash: 7bb695b77966e27cfaebfa59e27a0b91f1d33813\n"
       ]
      }
     ],
     "prompt_number": 2
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# Our second commit, linked to the first\n",
      "data2 = 'Some more text in my paper...'\n",
      "meta2 = 'date: 1/2/12'\n",
      "# Note we add the parent hash here!\n",
      "hash2 = sha.sha(data2 + meta2 + hash1).hexdigest()\n",
      "print 'Hash:', hash2"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Hash: 543da8bac9f643ba5611897b192a16dea42d2ab7\n"
       ]
      }
     ],
     "prompt_number": 3
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "And this is pretty much the essence of Git!"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "## First: Configuring Git\n",
      "The minimal amount of configuration for git to work without pestering you is to tell it who you are.  All the commands here modify the ``.gitconfig`` file in your home\n",
      "directory.\n",
      "\n",
      "Modify these before running them:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "git config --global user.name \"Jake Vanderplas\"\n",
      "git config --global user.email \"vanderplas@astro.washington.edu\""
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [],
     "prompt_number": 2
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### Other settings\n",
      "\n",
      "Change how you will edit text files (it will often ask you to edit messages and other information, and thus wants to know how you like to edit your files):"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "# Put here your preferred editor. If this is not set, git will honor\n",
      "# the $EDITOR environment variable\n",
      "git config --global core.editor /usr/bin/nano  # my preferred editor\n",
      "\n",
      "# On Windows Notepad will do in a pinch,\n",
      "#   I recommend Notepad++ as a free alternative\n",
      "# On the mac, you can set nano or emacs as a basic option"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [],
     "prompt_number": 3
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "# And while we're at it, we also turn on the use of color, which is very useful\n",
      "git config --global color.ui \"auto\""
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [],
     "prompt_number": 4
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### Password memory\n",
      "\n",
      "Set git to use the credential memory cache so we don't have to retype passwords too frequently. On Linux, you should run the following (note that this requires git version 1.7.10 or newer):"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash \n",
      "git config --global credential.helper cache\n",
      "# Set the cache to timeout after 2 hours (setting is in seconds)\n",
      "git config --global credential.helper 'cache --timeout=7200'"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [],
     "prompt_number": 6
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "Github offers in its help pages instructions on how to configure the credentials helper for [Mac OSX](https://help.github.com/articles/set-up-git#platform-mac) and [Windows](https://help.github.com/articles/set-up-git#platform-windows)."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "## Double-checking the result:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "!cat ~/.gitconfig"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "[user]\r\n",
        "\tname = Jake Vanderplas\r\n",
        "\temail = vanderplas@astro.washington.edu\r\n",
        "[core]\r\n",
        "\teditor = /usr/bin/nano\r\n",
        "[color]\r\n",
        "\tui = auto\r\n",
        "[credential]\r\n",
        "\thelper = cache --timeout=7200\r\n"
       ]
      }
     ],
     "prompt_number": 7
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "## Stage 1: Local, single-user, linear workflow\n",
      "Simply type `git` to see a full list of all the 'core' commands.  We'll now go through most of these via small practical exercises:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "!git"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "usage: git [--version] [--exec-path[=<path>]] [--html-path] [--man-path] [--info-path]\r\n",
        "           [-p|--paginate|--no-pager] [--no-replace-objects] [--bare]\r\n",
        "           [--git-dir=<path>] [--work-tree=<path>] [--namespace=<name>]\r\n",
        "           [-c name=value] [--help]\r\n",
        "           <command> [<args>]\r\n",
        "\r\n",
        "The most commonly used git commands are:\r\n",
        "   add        Add file contents to the index\r\n",
        "   bisect     Find by binary search the change that introduced a bug\r\n",
        "   branch     List, create, or delete branches\r\n",
        "   checkout   Checkout a branch or paths to the working tree\r\n",
        "   clone      Clone a repository into a new directory\r\n",
        "   commit     Record changes to the repository\r\n",
        "   diff       Show changes between commits, commit and working tree, etc\r\n",
        "   fetch      Download objects and refs from another repository\r\n",
        "   grep       Print lines matching a pattern\r\n",
        "   init       Create an empty git repository or reinitialize an existing one\r\n",
        "   log        Show commit logs\r\n",
        "   merge      Join two or more development histories together\r\n",
        "   mv         Move or rename a file, a directory, or a symlink\r\n",
        "   pull       Fetch from and merge with another repository or a local branch\r\n",
        "   push       Update remote refs along with associated objects\r\n",
        "   rebase     Forward-port local commits to the updated upstream head\r\n",
        "   reset      Reset current HEAD to the specified state\r\n",
        "   rm         Remove files from the working tree and from the index\r\n",
        "   show       Show various types of objects\r\n",
        "   status     Show the working tree status\r\n",
        "   tag        Create, list, delete or verify a tag object signed with GPG\r\n",
        "\r\n",
        "See 'git help <command>' for more information on a specific command.\r\n"
       ]
      }
     ],
     "prompt_number": 80
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "### `git init`: create an empty repository"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "rm -rf test\n",
      "git init test"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Initialized empty Git repository in /Users/jakevdp/Opensource/2013_fall_ASTR599/notebooks/test/.git/\n"
       ]
      }
     ],
     "prompt_number": 8
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "**Note:** all these cells below are meant to be run by you in a terminal  where  you change *once* to the `test` directory and continue working there.\n",
      "\n",
      "Since we are putting all of them here in a single notebook for the purposes of the tutorial, they will all be prepended with the first two lines:\n",
      "\n",
      "    %%bash\n",
      "    cd test\n",
      "\n",
      "that tell IPython to do that each time.  But you should ignore those two lines and type the rest of each cell yourself in your terminal."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "Let's look at what git did:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "ls"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [],
     "prompt_number": 9
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "ls -la"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "total 12\n",
        "drwxr-xr-x 3 fperez wavelet 4096 Feb 14 00:57 .\n",
        "drwxr-xr-x 7 fperez wavelet 4096 Feb 14 00:57 ..\n",
        "drwxr-xr-x 7 fperez wavelet 4096 Feb 14 00:57 .git\n"
       ]
      }
     ],
     "prompt_number": 40
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "ls -l .git"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "total 32\n",
        "drwxr-xr-x 2 fperez wavelet 4096 Feb 14 00:57 branches\n",
        "-rw-r--r-- 1 fperez wavelet   92 Feb 14 00:57 config\n",
        "-rw-r--r-- 1 fperez wavelet   73 Feb 14 00:57 description\n",
        "-rw-r--r-- 1 fperez wavelet   23 Feb 14 00:57 HEAD\n",
        "drwxr-xr-x 2 fperez wavelet 4096 Feb 14 00:57 hooks\n",
        "drwxr-xr-x 2 fperez wavelet 4096 Feb 14 00:57 info\n",
        "drwxr-xr-x 4 fperez wavelet 4096 Feb 14 00:57 objects\n",
        "drwxr-xr-x 4 fperez wavelet 4096 Feb 14 00:57 refs\n"
       ]
      }
     ],
     "prompt_number": 41
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "Now let's edit our first file in the test directory with a text editor... I'm doing it programatically here for automation purposes, but you'd normally be editing by hand"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "echo \"My first bit of text\" > file1.txt"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [],
     "prompt_number": 11
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "ls -al"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "total 8\n",
        "drwxrwxrwx   4 jakevdp  staff   136 Sep 12 10:05 .\n",
        "drwxr-xr-x  30 jakevdp  staff  1020 Sep 12 10:03 ..\n",
        "drwxrwxrwx   9 jakevdp  staff   306 Sep 12 10:03 .git\n",
        "-rw-rw-rw-   1 jakevdp  staff    21 Sep 12 10:05 file1.txt\n"
       ]
      }
     ],
     "prompt_number": 13
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "### `git add`: tell git about this new file"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git add file1.txt"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [],
     "prompt_number": 14
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "We can now ask git about what happened with `status`:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git status"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "# On branch master\n",
        "#\n",
        "# Initial commit\n",
        "#\n",
        "# Changes to be committed:\n",
        "#   (use \"git rm --cached <file>...\" to unstage)\n",
        "#\n",
        "#\tnew file:   file1.txt\n",
        "#\n"
       ]
      }
     ],
     "prompt_number": 15
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### `git commit`: permanently record our changes in git's database\n",
      "For now, we are *always* going to call `git commit` either with the `-a` option *or* with specific filenames (`git commit file1 file2...`).\n",
      "\n",
      "This delays the discussion of an aspect of git called the *index* (often referred to also as the 'staging area') that we will cover later.  Most everyday work in regular scientific practice doesn't require understanding the extra moving parts that the index involves, so on a first round we'll bypass it.  Later on we will discuss how to use it to achieve more fine-grained control of what and how git records our actions."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git commit -a -m\"This is our first commit\""
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "[master (root-commit) 609a459] This is our first commit\n",
        " 1 file changed, 1 insertion(+)\n",
        " create mode 100644 file1.txt\n"
       ]
      }
     ],
     "prompt_number": 16
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "In the commit above, we  used the `-m` flag to specify a message at the command line.\n",
      "\n",
      "If we don't do that, git will open the editor we specified in our configuration above and require that we enter a message.\n",
      "\n",
      "By default, git refuses to record changes that don't have a message to go along with them (though you can obviously 'cheat' by using an empty or meaningless string: git only tries to facilitate best practices, it's not your nanny)."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### `git log`: what has been committed so far"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git log"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "commit 609a45916899c56d1e3b8fe021b907f58845e75e\n",
        "Author: Jake Vanderplas <vanderplas@astro.washington.edu>\n",
        "Date:   Thu Sep 12 10:06:55 2013 -0700\n",
        "\n",
        "    This is our first commit\n"
       ]
      }
     ],
     "prompt_number": 17
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### `git diff`: what have I changed?\n",
      "Let's do a little bit more work... Again, in practice you'll be editing the files by hand, here we do it via shell commands for the sake of automation (and therefore the reproducibility of this tutorial!)"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "echo \"And now some more text...\" >> file1.txt"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [],
     "prompt_number": 18
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "And now we can ask git what is different:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git diff"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "diff --git a/file1.txt b/file1.txt\n",
        "index ce645c7..4baa979 100644\n",
        "--- a/file1.txt\n",
        "+++ b/file1.txt\n",
        "@@ -1 +1,2 @@\n",
        " My first bit of text\n",
        "+And now some more text...\n"
       ]
      }
     ],
     "prompt_number": 19
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### The cycle of git virtue: work, commit, work, commit, ..."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git commit -a -m\"I have made great progress on this critical matter.\""
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "[master 43ed8dd] I have made great progress on this critical matter.\n",
        " 1 file changed, 1 insertion(+)\n"
       ]
      }
     ],
     "prompt_number": 20
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### `git log` revisited\n",
      "First, let's see what the log shows us now:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git log"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "commit 43ed8dd431bde1d511934526da8414113965178b\n",
        "Author: Jake Vanderplas <vanderplas@astro.washington.edu>\n",
        "Date:   Thu Sep 12 10:09:41 2013 -0700\n",
        "\n",
        "    I have made great progress on this critical matter.\n",
        "\n",
        "commit 609a45916899c56d1e3b8fe021b907f58845e75e\n",
        "Author: Jake Vanderplas <vanderplas@astro.washington.edu>\n",
        "Date:   Thu Sep 12 10:06:55 2013 -0700\n",
        "\n",
        "    This is our first commit\n"
       ]
      }
     ],
     "prompt_number": 21
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "Sometimes it's handy to see a very summarized version of the log:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git log --oneline --topo-order --graph"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "* 2d29a7b I have made great progress on this critical matter!\n",
        "* 679f246 This is our first commit\n"
       ]
      }
     ],
     "prompt_number": 51
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### Defining an alias\n",
      "\n",
      "Git supports *aliases:* new names given to command combinations. Let's make this handy shortlog an alias, so we only have to type `git slog` and see this compact log:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "# We create our alias (this saves it in git's permanent configuration file):\n",
      "git config --global alias.slog \"log --oneline --topo-order --graph\"\n",
      "\n",
      "# And now we can use it\n",
      "git slog"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "* 43ed8dd I have made great progress on this critical matter.\n",
        "* 609a459 This is our first commit\n"
       ]
      }
     ],
     "prompt_number": 22
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### `git mv` and `rm`: moving and removing files\n",
      "While `git add` is used to add fils to the list git tracks, we must also tell it if we want their  names to change or for it to stop tracking them.  In familiar Unix fashion, the `mv` and `rm` git commands do precisely this:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git mv file1.txt file-newname.txt\n",
      "git status"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "# On branch master\n",
        "# Changes to be committed:\n",
        "#   (use \"git reset HEAD <file>...\" to unstage)\n",
        "#\n",
        "#\trenamed:    file1.txt -> file-newname.txt\n",
        "#\n"
       ]
      }
     ],
     "prompt_number": 23
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "Note that these changes must be committed too, to become permanent!  In git's world, until something hasn't been committed, it isn't permanently recorded anywhere."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git commit -a -m\"I like this new name better\"\n",
      "echo \"Let's look at the log again:\"\n",
      "git slog"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "[master 110c1bb] I like this new name better\n",
        " 1 file changed, 0 insertions(+), 0 deletions(-)\n",
        " rename file1.txt => file-newname.txt (100%)\n",
        "Let's look at the log again:\n",
        "* 110c1bb I like this new name better\n",
        "* 43ed8dd I have made great progress on this critical matter.\n",
        "* 609a459 This is our first commit\n"
       ]
      }
     ],
     "prompt_number": 24
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "And `git rm` works in a similar fashion."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### Exercise\n",
      "Add a new file `file2.txt`, commit it, make some changes to it, commit them again, and then remove it (and don't forget to commit this last step!)."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "## 2. Single Local user, branching\n",
      "What is a branch?  Simply a *label for the 'current' commit in a sequence of ongoing commits*:\n",
      "\n",
      "![](files/images/masterbranch.png)"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### Mulitple Branches\n",
      "There can be multiple branches alive at any point in time; the working directory is the state of a special pointer called HEAD.  In this example there are two branches, *master* and *testing*, and *testing* is the currently active branch since it's what HEAD points to:\n",
      "\n",
      "![](files/images/HEAD_testing.png)"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "Once new commits are made on a branch, HEAD and the branch label move with the new commits:\n",
      "\n",
      "![](files/images/branchcommit.png)"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "This allows the history of both branches to diverge:\n",
      "\n",
      "![](files/images/mergescenario.png)"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "But based on this graph structure, git can compute the necessary information to merge the divergent branches back and continue with a unified line of development:\n",
      "    \n",
      "![](files/images/mergeaftermath.png)"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### Branching Example\n",
      "\n",
      "Let's now illustrate all of this with a concrete example.  Let's get our bearings first:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git status\n",
      "ls"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "# On branch master\n",
        "nothing to commit, working directory clean\n",
        "file-newname.txt\n"
       ]
      }
     ],
     "prompt_number": 25
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "We are now going to try two different routes of development: on the `master` branch we will add one file and on the `experiment` branch, which we will create, we will add a different one.  We will then merge the experimental branch into `master`."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git branch experiment\n",
      "git checkout experiment"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stderr",
       "text": [
        "Switched to branch 'experiment'\n"
       ]
      }
     ],
     "prompt_number": 26
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "echo \"Some crazy idea\" > experiment.txt\n",
      "git add experiment.txt\n",
      "git commit -a -m\"Trying something new\"\n",
      "git slog"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "[experiment 2ac278c] Trying something new\n",
        " 1 file changed, 1 insertion(+)\n",
        " create mode 100644 experiment.txt\n",
        "* 2ac278c Trying something new\n",
        "* 110c1bb I like this new name better\n",
        "* 43ed8dd I have made great progress on this critical matter.\n",
        "* 609a459 This is our first commit\n"
       ]
      }
     ],
     "prompt_number": 27
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git checkout master\n",
      "git slog"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "* 110c1bb I like this new name better\n",
        "* 43ed8dd I have made great progress on this critical matter.\n",
        "* 609a459 This is our first commit\n"
       ]
      },
      {
       "output_type": "stream",
       "stream": "stderr",
       "text": [
        "Switched to branch 'master'\n"
       ]
      }
     ],
     "prompt_number": 28
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "echo \"All the while, more work goes on in master...\" >> file-newname.txt\n",
      "git commit -a -m\"The mainline keeps moving\"\n",
      "git slog"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "[master 0c5002e] The mainline keeps moving\n",
        " 1 file changed, 1 insertion(+)\n",
        "* 0c5002e The mainline keeps moving\n",
        "* 110c1bb I like this new name better\n",
        "* 43ed8dd I have made great progress on this critical matter.\n",
        "* 609a459 This is our first commit\n"
       ]
      }
     ],
     "prompt_number": 29
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "ls"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "file-newname.txt\n"
       ]
      }
     ],
     "prompt_number": 30
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git merge experiment\n",
      "git slog"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Merge made by the 'recursive' strategy.\n",
        " experiment.txt | 1 +\n",
        " 1 file changed, 1 insertion(+)\n",
        " create mode 100644 experiment.txt\n",
        "*   3471d04 Merge branch 'experiment'\n",
        "|\\  \n",
        "| * 2ac278c Trying something new\n",
        "* | 0c5002e The mainline keeps moving\n",
        "|/  \n",
        "* 110c1bb I like this new name better\n",
        "* 43ed8dd I have made great progress on this critical matter.\n",
        "* 609a459 This is our first commit\n"
       ]
      }
     ],
     "prompt_number": 31
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "## 3. Using remotes as a single user"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "We are now going to introduce the concept of a *remote repository*: a pointer to another copy of the repository that lives on a different location.  This can be simply a different path on the filesystem or a server on the internet.\n",
      "\n",
      "For this discussion, we'll be using remotes hosted on the [GitHub.com](http://github.com) service, but you can equally use other services like [BitBucket](http://bitbucket.org) or [Gitorious](http://gitorious.org) as well as host your own.\n",
      "\n",
      "If you don't have a Github account, take a moment now to [sign up](https://github.com/)"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### ``git remote``: view/modify remote repositories"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "ls\n",
      "echo \"Let's see if we have any remote repositories here:\"\n",
      "git remote -v"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "experiment.txt\n",
        "file-newname.txt\n",
        "Let's see if we have any remote repositories here:\n"
       ]
      }
     ],
     "prompt_number": 61
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "Since the above cell didn't produce any output after the `git remote -v` call, it means we have no remote repositories configured."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "#### Configuring a remote\n",
      "Log into GitHub, go to the [new repository page](https://github.com/new) and make a repository called `test`.\n",
      "\n",
      "Do **not** check the box that says `Initialize this repository with a README`, since we already have an existing repository here.  That option is useful when you're starting first at Github and don't have a repo made already on a local computer.\n",
      "\n",
      "We can now follow the instructions from the next page:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": true,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git remote add origin https://github.com/jakevdp/test.git"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Process is terminated.\n"
       ]
      }
     ],
     "prompt_number": 32
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "Let's see the remote situation again:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git remote -v"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "origin\thttps://github.com/fperez/test.git (fetch)\n",
        "origin\thttps://github.com/fperez/test.git (push)\n"
       ]
      }
     ],
     "prompt_number": 67
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "#### Pushing changes to a remote repository\n",
      "\n",
      "Now push the ``master`` branch to the remote named ``origin``:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git push origin master"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "We can now [see this repository publicly on github](https://github.com/fperez/test)."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### Using Git to Sync Work\n",
      "\n",
      "Let's see how this can be useful for backup and syncing work between two different computers.  I'll simulate a 2nd computer by working in a different directory..."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "\n",
      "# Here I clone my 'test' repo but with a different name, test2, to simulate a 2nd computer\n",
      "git clone https://github.com/jakevdp/test.git test2\n",
      "cd test2\n",
      "pwd\n",
      "git remote -v"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Cloning into 'test2'...\n",
        "Checking connectivity... done\n",
        "/Users/jakevdp/Opensource/2013_fall_ASTR599/notebooks/test2\n",
        "origin\thttps://github.com/jakevdp/test.git (fetch)\n",
        "origin\thttps://github.com/jakevdp/test.git (push)\n"
       ]
      }
     ],
     "prompt_number": 34
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "Let's now make some changes in one 'computer' and synchronize them on the second."
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test2  # working on computer #2\n",
      "\n",
      "echo \"More new content on my experiment\" >> experiment.txt\n",
      "git commit -a -m\"More work, on machine #2\""
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "[master 8852251] More work, on machine #2\n",
        " 1 file changed, 1 insertion(+)\n"
       ]
      }
     ],
     "prompt_number": 35
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "Now we put this new work up on the github server so it's available from the internet"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test2\n",
      "\n",
      "git push origin master"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stderr",
       "text": [
        "Everything up-to-date\n"
       ]
      }
     ],
     "prompt_number": 39
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "Now let's fetch that work from machine #1:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git pull origin master"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Already up-to-date.\n"
       ]
      },
      {
       "output_type": "stream",
       "stream": "stderr",
       "text": [
        "From https://github.com/jakevdp/test\n",
        " * branch            master     -> FETCH_HEAD\n"
       ]
      }
     ],
     "prompt_number": 38
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "## An important aside: conflict management\n",
      "While git is very good at merging, if two different branches modify the same file in the same location, it simply can't decide which change should prevail.  At that point, human intervention is necessary to make the decision.  Git will help you by marking the location in the file that has a problem, but it's up to you to resolve the conflict.  Let's see how that works by intentionally creating a conflict.\n",
      "\n",
      "We start by creating a branch and making a change to our experiment file:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git branch trouble\n",
      "git checkout trouble\n",
      "echo \"This is going to be a problem...\" >> experiment.txt\n",
      "git commit -a -m\"Changes in the trouble branch\""
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "[trouble d46245e] Changes in the trouble branch\n",
        " 1 file changed, 1 insertion(+)\n"
       ]
      },
      {
       "output_type": "stream",
       "stream": "stderr",
       "text": [
        "Switched to branch 'trouble'\n"
       ]
      }
     ],
     "prompt_number": 40
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "And now we go back to the master branch, where we change the *same* file:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git checkout master\n",
      "echo \"More work on the master branch...\" >> experiment.txt\n",
      "git commit -a -m\"Mainline work\""
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "[master 387f3ef] Mainline work\n",
        " 1 file changed, 1 insertion(+)\n"
       ]
      },
      {
       "output_type": "stream",
       "stream": "stderr",
       "text": [
        "Switched to branch 'master'\n"
       ]
      }
     ],
     "prompt_number": 41
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### The conflict...\n",
      "\n",
      "So now let's see what happens if we try to merge the `trouble` branch into `master`:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git merge trouble"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Auto-merging experiment.txt\n",
        "CONFLICT (content): Merge conflict in experiment.txt\n",
        "Automatic merge failed; fix conflicts and then commit the result.\n"
       ]
      }
     ],
     "prompt_number": 42
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "Let's see what git has put into our file:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "cat experiment.txt"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Some crazy idea\n",
        "More new content on my experiment\n",
        "<<<<<<< HEAD\n",
        "More work on the master branch...\n",
        "=======\n",
        "This is going to be a problem...\n",
        ">>>>>>> trouble\n"
       ]
      }
     ],
     "prompt_number": 43
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "At this point, we go into the file with a text editor, decide which changes to keep, and make a new commit that records our decision.  I've now made the edits, in this case I decided that both pieces of text were useful, but integrated them with some changes:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "cat experiment.txt"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "Some crazy idea\n",
        "More new content on my experiment\n",
        "More work on the master branch...\n",
        "This is going to be a problem...\n"
       ]
      }
     ],
     "prompt_number": 44
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "Let's then make our new commit:"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "%%bash\n",
      "cd test\n",
      "\n",
      "git commit -a -m\"Completed merge of trouble, fixing conflicts along the way\"\n",
      "git slog"
     ],
     "language": "python",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "outputs": [
      {
       "output_type": "stream",
       "stream": "stdout",
       "text": [
        "[master 0213b88] Completed merge of trouble, fixing conflicts along the way\n",
        "*   0213b88 Completed merge of trouble, fixing conflicts along the way\n",
        "|\\  \n",
        "| * d46245e Changes in the trouble branch\n",
        "* | 387f3ef Mainline work\n",
        "|/  \n",
        "* 8852251 More work, on machine #2\n",
        "*   3471d04 Merge branch 'experiment'\n",
        "|\\  \n",
        "| * 2ac278c Trying something new\n",
        "* | 0c5002e The mainline keeps moving\n",
        "|/  \n",
        "* 110c1bb I like this new name better\n",
        "* 43ed8dd I have made great progress on this critical matter.\n",
        "* 609a459 This is our first commit\n"
       ]
      }
     ],
     "prompt_number": 45
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### Merge Tools\n",
      "\n",
      "*Note:* While it's a good idea to understand the basics of fixing merge conflicts by hand, in some cases you may find the use of an automated tool useful.\n",
      "\n",
      "Git supports multiple [merge tools](https://www.kernel.org/pub/software/scm/git/docs/git-mergetool.html): a merge tool is a piece of software that conforms to a basic interface and knows how to merge two files into a new one.  Since these are typically graphical tools, there are various to choose from for the different operating systems, and as long as they obey a basic command structure, git can work with any of them."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "## 4. Collaborating on github with a small team\n",
      "\n",
      "Here we will set up a shared collaboration with one partner -- choose someone sitting next to you. \n",
      "\n",
      "We will have two people, let's call them Alice and Bob, sharing a repository.  Alice will be the owner of the repo and she will give Bob write privileges.  \n",
      "\n",
      "**Find a partner & decide who will be Alice, and who will be Bob.**\n",
      "\n",
      "<small><i>\n",
      "Note for SVN users: this is similar to the classic SVN workflow, with the distinction that commit and push are separate steps.  SVN, having no local repository, commits directly to the shared central resource, so to a first approximation you can think of `svn commit` as being synonymous with `git commit; git push`.</i></small>"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### 1. Synchronization\n",
      "\n",
      "We begin with a simple synchronization example.  Working together, follow these steps:\n",
      "\n",
      "#### Creating a new repository\n",
      "- Alice: create a new repository on github called ``AliceBob``\n",
      "- Alice: create a file ``README.md``, commit it, and push it to the remote.\n",
      "- Alice: on github, go to the settings for ``AliceBob``, and add your partner to the list of collaborators\n",
      "\n",
      "#### Cloning your partner's repository\n",
      "- Bob: clone the ``AliceBob`` repository using ``git clone [url]``\n",
      "- Bob: makes changes to the ``README.md`` file and commit locally.\n",
      "- Bob: push changes to github.\n",
      "- Alice: pull Bob's changes to the local repository.\n",
      "\n",
      "Now Alice and Bob should both have the same ``README.md`` file on their own computer."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### 2. Dealing with conflicts\n",
      "\n",
      "Next, we will have both parties make non-conflicting changes each, and commit them locally.  Then both try to push their changes:\n",
      "\n",
      "- Alice: create & commit a new file, ``alice.txt`` to the local repo\n",
      "- Bob: create & commit a new file, ``bob.txt`` to the local repo\n",
      "- Alice: push the latest commit to github\n",
      "- Bob: try to push to github.  What happens?\n",
      "\n",
      "- Alice adds a new file, `alice.txt` to the repo and commits.\n",
      "- Bob adds `bob.txt` and commits.\n",
      "- Alice pushes to github.\n",
      "- Bob tries to push to github.  What happens here?\n",
      "\n",
      "The problem is that Bob's changes create a commit that conflicts with Alice's, so git refuses to apply them.\n",
      "\n",
      "Bob must do\n",
      "\n",
      "    git pull origin master\n",
      "    \n",
      "And then deal with the conflict manually, then push again."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "## 5. Full-contact github: distributed collaboration with large teams\n",
      "\n",
      "On large teams, you don't always want all contributors to have access to the main repository.  So how do you move forward?  Using Pull Requests.\n",
      "\n",
      "Again, we'll do this as an exercise with your partner:"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "[Brief demo of how this works on scikit-learn]"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "fragment"
      }
     },
     "source": [
      "We'll practice this here, by having Alice now *fork* Bob's repository.\n",
      "\n",
      "1. **Bob:** create a new repository named ``BobAlice`` with a ``README.md`` file, and push it to the github remote.\n",
      "\n",
      "2. **Alice:** go to Bob's github page and click the *fork* button.  You now have your own remote version of the repository, that looks like ``http://github.com/Alice/BobAlice.git``\n",
      "\n",
      "3. **Alice:** use ``git clone [url]`` to get a local version of *your fork* on your own computer. \n",
      "\n",
      "4. **Alice:** use ``git remote add upstream [url]`` to add a pointer to Bob's remote (the original)\n",
      "\n",
      "5. **Alice:** type ``git remote -v``, and you should see both your own fork (called ``origin``) and Bob's fork (called ``upstream``)\n",
      "\n",
      "6. **Alice:** create a new branch called ``alice_changes``\n",
      "\n",
      "7. **Alice:** add a file called ``alice.txt`` commit, and use ``git push origin alice_changes`` to push to the remote.\n",
      "\n",
      "8. **Alice:** reload the github page for *your own* fork: there should now be a button that says \"compare and pull request\".  Click it and fill it out.\n",
      "\n",
      "9. **Bob:** go to your own notifications page (the blue circle in the upper-left of GitHub) and you should see a notification of Alice's Pull request.  Check the diff, add some comments, and merge the changes.\n",
      "\n",
      "10. **Alice:** on your computer, checkout the master branch, and update it from Bob's fork with ``git pull upstream master``\n",
      "\n",
      "Congratulations!  You're now a collaborator!\n",
      "\n",
      "This is how virtually all open source collaboration proceeds on Github!"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "## Other useful commands\n",
      "- [show](http://www.kernel.org/pub/software/scm/git/docs/git-show.html)\n",
      "- [reflog](http://www.kernel.org/pub/software/scm/git/docs/git-reflog.html)\n",
      "- [rebase](http://www.kernel.org/pub/software/scm/git/docs/git-rebase.html)\n",
      "- [tag](http://www.kernel.org/pub/software/scm/git/docs/git-tag.html)"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "## Git resources\n",
      "### Introductory materials\n",
      "There are lots of good tutorials and introductions for Git, which you\n",
      "can easily find yourself; this is just a short list of things I've found\n",
      "useful.  For a beginner, I would recommend the following 'core' reading list, and\n",
      "below I mention a few extra resources:\n",
      "\n",
      "1. The smallest, and in the style of this tuorial: [git - the simple guide](http://rogerdudler.github.com/git-guide)\n",
      "contains 'just the basics'.  Very quick read.\n",
      "\n",
      "1.  The concise [Git Reference](http://gitref.org): compact but with\n",
      "    all the key ideas. If you only read one document, make it this one.\n",
      "\n",
      "1. In my own experience, the most useful resource was [Understanding Git\n",
      "Conceptually](http://www.sbf5.com/~cduan/technical/git).\n",
      "Git has a reputation for being hard to use, but I have found that with a\n",
      "clear view of what is actually a *very simple* internal design, its\n",
      "behavior is remarkably consistent, simple and comprehensible.\n",
      "\n",
      "1.  For more detail, see the start of the excellent [Pro\n",
      "    Git](http://progit.org/book) online book, or similarly the early\n",
      "    parts of the [Git community book](http://book.git-scm.com). Pro\n",
      "    Git's chapters are very short and well illustrated; the community\n",
      "    book tends to have more detail and has nice screencasts at the end\n",
      "    of some sections.\n",
      "\n",
      "If you are really impatient and just want a quick start, this [visual git tutorial](http://www.ralfebert.de/blog/tools/visual_git_tutorial_1)\n",
      "may be sufficient. It is nicely illustrated with diagrams that show what happens on the filesystem.\n",
      "\n",
      "For windows users, [an Illustrated Guide to Git on Windows](http://nathanj.github.com/gitguide/tour.html) is useful in that\n",
      "it contains also some information about handling SSH (necessary to interface with git hosted on remote servers when collaborating) as well\n",
      "as screenshots of the Windows interface.\n",
      "\n",
      "Cheat sheets\n",
      ":   Two different\n",
      "    [cheat](http://zrusin.blogspot.com/2007/09/git-cheat-sheet.html)\n",
      "    [sheets](http://jan-krueger.net/development/git-cheat-sheet-extended-edition)\n",
      "    in PDF format that can be printed for frequent reference."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### Beyond the basics\n",
      "At some point, it will pay off to understand how git itself is *built*.  These two documents, written in a similar spirit, \n",
      "are probably the most useful descriptions of the Git architecture short of diving into the actual implementation.  They walk you through\n",
      "how you would go about building a version control system with a little story. By the end you realize that Git's model is almost\n",
      "an inevitable outcome of the proposed constraints:\n",
      "\n",
      "* The [Git parable](http://tom.preston-werner.com/2009/05/19/the-git-parable.html) by Tom Preston-Werner.\n",
      "* [Git foundations](http://matthew-brett.github.com/pydagogue/foundation.html) by Matthew Brett.\n",
      "\n",
      "[Git ready](http://www.gitready.com)\n",
      ":   A great website of posts on specific git-related topics, organized\n",
      "    by difficulty.\n",
      "\n",
      "[QGit](http://sourceforge.net/projects/qgit/): an excellent Git GUI\n",
      ":   Git ships by default with gitk and git-gui, a pair of Tk graphical\n",
      "    clients to browse a repo and to operate in it. I personally have\n",
      "    found [qgit](http://sourceforge.net/projects/qgit/) to be nicer and\n",
      "    easier to use. It is available on modern linux distros, and since it\n",
      "    is based on Qt, it should run on OSX and Windows.\n",
      "\n",
      "[Git Magic](http://www-cs-students.stanford.edu/~blynn/gitmagic/index.html)\n",
      ":   Another book-size guide that has useful snippets.\n",
      "\n",
      "The [learning center](http://learn.github.com) at Github\n",
      ":   Guides on a number of topics, some specific to github hosting but\n",
      "    much of it of general value.\n",
      "\n",
      "A [port](http://cworth.org/hgbook-git/tour) of the Hg book's beginning\n",
      ":   The [Mercurial book](http://hgbook.red-bean.com) has a reputation\n",
      "    for clarity, so Carl Worth decided to\n",
      "    [port](http://cworth.org/hgbook-git/tour) its introductory chapter\n",
      "    to Git. It's a nicely written intro, which is possible in good\n",
      "    measure because of how similar the underlying models of Hg and Git\n",
      "    ultimately are.\n",
      "\n",
      "[Intermediate tips](http://andyjeffries.co.uk/articles/25-tips-for-intermediate-git-users)\n",
      ":   A set of tips that contains some very valuable nuggets, once you're\n",
      "    past the basics."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### For SVN users\n",
      "If you want a bit more background on why the model of version control\n",
      "used by Git and Mercurial (known as distributed version control) is such\n",
      "a good idea, I encourage you to read this very well written\n",
      "[post](http://www.joelonsoftware.com/items/2010/03/17.html) by Joel\n",
      "Spolsky on the topic. After that post, Joel created a very nice\n",
      "Mercurial tutorial, whose [first page](http://hginit.com/00.html)\n",
      "applies equally well to git and is a very good 're-education' for anyone\n",
      "coming from an SVN (or similar) background.\n",
      "\n",
      "In practice, I think you are better off following Joel's advice and\n",
      "understanding git on its own merits instead of trying to bang SVN\n",
      "concepts into git shapes. But for the occasional translation from SVN to\n",
      "Git of a specific idiom, the [Git - SVN Crash\n",
      "Course](http://git-scm.org/course/svn.html) can be handy."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "### A few useful tips for common tasks\n",
      "#### Better shell support\n",
      "\n",
      "Adding git branch info to your bash prompt and tab completion for git commands and branches is extremely useful.  I suggest you at least copy:\n",
      "\n",
      "- [git-completion.bash](https://github.com/git/git/blob/master/contrib/completion/git-completion.bash)\n",
      "- [git-prompt.sh](https://github.com/git/git/blob/master/contrib/completion/git-prompt.sh)\n",
      " \n",
      "You can then source both of these files in your `~/.bashrc` and then set your prompt (I'll assume you named them as the originals but starting with a `.` at the front of the name):\n",
      "\n",
      "    source $HOME/.git-completion.bash\n",
      "    source $HOME/.git-prompt.sh\n",
      "    PS1='[\\u@\\h \\W$(__git_ps1 \" (%s)\")]\\$ '   # adjust this to your prompt liking\n",
      "\n",
      "See the comments in both of those files for lots of extra functionality they offer."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "#### Embedding Git information in LaTeX documents\n",
      "\n",
      "(Sent by [Yaroslav Halchenko](http://www.onerussian.com))\n",
      "su\n",
      "I use a Make rule:\n",
      "\n",
      "    # Helper if interested in providing proper version tag within the manuscript\n",
      "    revision.tex: ../misc/revision.tex.in ../.git/index\n",
      "       GITID=$$(git log -1 | grep -e '^commit' -e '^Date:' | sed  -e 's/^[^ ]* *//g' | tr '\\n' ' '); \\\n",
      "       echo $$GITID; \\\n",
      "       sed -e \"s/GITID/$$GITID/g\" $< >| $@\n",
      "\n",
      "in the top level `Makefile.common` which is included in all\n",
      "subdirectories which actually contain papers (hence all those\n",
      "`../.git`). The `revision.tex.in` file is simply:\n",
      "\n",
      "    % Embed GIT ID revision and date\n",
      "    \\def\\revision{GITID}\n",
      "\n",
      "The corresponding `paper.pdf` depends on `revision.tex` and includes the\n",
      "line `\\input{revision}` to load up the actual revision mark."
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {
      "slideshow": {
       "slide_type": "slide"
      }
     },
     "source": [
      "#### git export\n",
      "\n",
      "Git doesn't have a native export command, but this works just fine:\n",
      "\n",
      "    git archive --prefix=fperez.org/  master | gzip > ~/tmp/source.tgz"
     ]
    }
   ],
   "metadata": {}
  }
 ]
}