QuickGit.ipynb

{
 "metadata": {
  "name": "QuickGit"
 },
 "nbformat": 3,
 "nbformat_minor": 0,
 "worksheets": [
  {
   "cells": [
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "# Revision Control Software (RCS) or Version Control Software (VCS)\n",
      "\n",
      "http://en.wikipedia.org/wiki/Revision_control\n",
      "\n",
      "### Main purpose\n",
      "\n",
      "1. Keep track of changes\n",
      "    * text files, images, manuscripts, code\n",
      "    * **revert** to an old version\n",
      "    * **tag** a specific snapshot (eg version of manuscript sent to journal x)\n",
      "    * **branch** creation to create modifications that can be **merged** back into **trunk**\n",
      "    * **commit** messages help keep track of changes\n",
      "\n",
      "2. Collaborative work\n",
      "    * many people working on same code base\n",
      "    * easy visualization of who makes which cnhnages and when\n",
      "    * **commit messages** to help you keep track of what you changed and why\n",
      "\n",
      "## Example Development Tree\n",
      "\n",
      "![alt text](files/images/200px-Revision_controlled_project_visualization-2010-24-02.png \"Example Repository\")\n"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "I will be primarily focussing on [Git](http://git-scm.com/)\n",
      "\n",
      "There are **so** many resources for git online (all my good notes are pirated from these sources)\n",
      "\n",
      "* http://git-scm.com/book\n",
      "\n",
      "* [J.R. Johansson tutorial](http://nbviewer.ipython.org/urls/raw.github.com/jrjohansson/scientific-python-lectures/master/Lecture-7-Revision-Control-Software.ipynb)\n",
      "\n",
      "* [reproducible software repository (Fernando Perez)](https://github.com/fperez/reprosw)\n",
      "\n",
      "## Terms\n",
      "\n",
      "Lets start with some basic terms so when I tal about something you have a sense of what it means.\n",
      "We will go into more detail later on.\n",
      "\n",
      "**master** or **trunk** : The main **branch** of the **repository**  \n",
      "\n",
      "1. **clone** or **fork** (get a copy of the repo)\n",
      "2. **checkout**  (access a specific **branch**)\n",
      "3. **branch**  (create a new **branch** to work on)\n",
      "4. **merge**  (apply changes from one **branch** to **master** - or other **branch**)\n",
      "5. **rebase** ( apply changes from **master** to branch, and place your edits ontop ) \n",
      "6. **push**  ( send changes to a remote  repo )\n",
      "7. **pull**  ( grab changes from a remote repo )\n",
      "8. **tag** (mark and save a specific snapshot ) \n",
      "\n",
      "\n",
      "## What does a **Distributed Version Control System** look like?\n",
      "![alt text](files/images/distrib_vcs.png \"Distributed Version Control\")"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "## Some Nice Properties of GIT\n",
      "\n",
      "1. Git works with snapshots not Differences\n",
      "\n",
      "2. Almost all operations are local (you can work without wifi)\n",
      "\n",
      "3. Primarily **adds** data, so hard to lose anything (and with integrity)\n",
      "\n",
      "4. Integrity? Git uses checksums so you cannot change anything without git knowing\n",
      "\n",
      "## THREE MAIN STATES\n",
      "\n",
      "1. **committed** (safely stored in database)\n",
      "\n",
      "2. **modified**  ( changed file, but not committed to database )\n",
      "\n",
      "3. **staged** ( marked a changed file to go into your next commit )\n",
      "\n",
      "![alt text] (files/images/git_working_directory.png \"Git states\")\n",
      "\n",
      "\n",
      "\n"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "# Basic Workflow\n",
      "\n",
      "\n",
      "(note this would all be **local**)\n",
      "\n",
      "1. clone repo or initialize repo\n",
      "2. checkout **working directory** or **branch**\n",
      "3. modify files\n",
      "4. stage files\n",
      "5. commit files\n"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "\n",
      "# Work flows\n",
      "\n",
      "## stand alone user\n",
      "\n",
      "If you are working on code or another project that **only you** will use.\n",
      "\n",
      "1. open web browser and go to github https://github.com/\n",
      "2. login\n",
      "3. create repo on github\n",
      "\n",
      "![alt text](files/images/newrepo.png \"new repo button\")\n",
      "\n",
      "Just follow the instructions\n",
      "\n",
      "\n",
      "\n",
      "### On your local machine"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "## Make direoctory with the same name as your repo and cd into that directory\n",
      "! #mkdir <repo>\n",
      "! #cd <repo>\n",
      "\n",
      "# set up necessary git files\n",
      "! git init\n",
      "\n",
      "# what branch are you on??\n",
      "# the -a flag lists all branches, we see nothing as this is a empty repo\n",
      "! git branch -a\n",
      "\n",
      "# make empty README file\n",
      "! touch README\n",
      "\n",
      "## check status (README is not \"staged\")\n",
      "! git status\n",
      "\n",
      "# stage new file\n",
      "! git add README\n",
      "\n",
      "## check status README is now \"staged\"\n",
      "! git status\n",
      "\n",
      "## see what has changed\n",
      "! git diff\n",
      "\n",
      "## commit your first file \n",
      "## the -a flag commits all changes\n",
      "## the -m flag adds your message\n",
      "! git commit -am \"Added README\"\"\n",
      "\n",
      "## look at branches again\n",
      "## there will be a '*' next to your current branch (master)\n",
      "! git branch -a\n",
      "\n",
      "## We need to link this to your remote repo\n",
      "## First create an alias (origin) for your remote repo on Github\n",
      "! #git remote add origin git@github.com:<username>/<repo>.git\n",
      "\n",
      "## see our new link to the \"remote\"\n",
      "! git remote -v\n",
      "\n",
      "## now we can push your changes to Github\n",
      "!git push origin master\n",
      "\n",
      "## look at your history using log\n",
      "!git log\n"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "# git config\n",
      "\n",
      "this sets up config files that can change how your repo and git behave\n",
      "\n",
      "You should have both a **.gitconfig** in your home directory, \n",
      "\n",
      "and a **.git/config** file specific to this repo in the repo directory\n",
      "\n"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "## Look at config in your current repo\n",
      "! less .git/config\n",
      "\n",
      "## Look at your global config\n",
      "! less ~/.gitconfig"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": "*"
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "## Config via the command line\n",
      "\n",
      "This will update your settings in your global config file"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "! #git config --global user.name \"John Doe\"\n",
      "! #git config --global user.email johndoe@example.com\n",
      "\n",
      "! #git config --global core.editor emacs\n",
      "! #git config --list\n",
      "\n",
      "! git help config"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": "*"
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "If you work with a repo alot, you may not want to enter your username and password each time.  To avoid this you can set up ssh keys for the computers you work on (eg the cluster)\n",
      "\n",
      "The instructions are here:\n",
      "https://help.github.com/articles/generating-ssh-key\n",
      "\n",
      "But I will not be reviewing this today unless we have time.\n"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "# Workflows\n",
      "\n",
      "## collaboration via forking\n",
      "\n",
      "1. fork on github\n",
      "2. clone to machine\n",
      "3. create new branch\n",
      "4. edit\n",
      "5. stage\n",
      "6. commit\n",
      "7. pull request via github \n",
      "8. changes accepted!!\n",
      "9. pull remote/master to  master\n",
      "10. remove branch\n",
      "\n",
      "\n",
      "reset --hard"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "## Lets Fork!\n",
      "\n",
      "1. You should already have an account on [github](https://github.com/)\n",
      "2. Go to https://github.com/cindeem/quickgit-lab\n",
      "3. Fork the repo\n",
      "![alt text](files/github_fork.png \"fork\")\n",
      "\n",
      "4. This will create your own repo!!\n",
      "5. Checkout your **forked** version on the cluster\n",
      "\n",
      "    git clone git@github.com:<username>/quickgit-lab.git\n",
      "\n"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "! # cd /where/you/want/the/repo\n",
      "! #git clone git@github.com:<username>/quickgit-lab.git\n",
      "! cd quickgit-lab\n",
      "! ls -al"
     ],
     "language": "python",
     "metadata": {},
     "outputs": [],
     "prompt_number": "*"
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "So in the previous example **single user** we did all our work on master.  \n",
      "\n",
      "This time we want collaborate with another person repo..\n",
      "\n",
      "1. add remote to follow\n",
      "2. to make a **branch** and do all our changes there\n"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "## setup alias  \"upstream\" to remote repo \n",
      "git remote add upstream git://github.com/cindeem/quickgit-lab.git\n",
      "\n",
      "# create and checkout a new branch called \"myfix\"\n",
      "! git checkout -b myfix\n",
      "\n",
      "# create a new file called pie.py\n",
      "# add \"blueberry\" to file pie.py\n",
      "\n",
      "## check status (pie.py is not \"staged\")\n",
      "! git status\n",
      "\n",
      "# stage new file\n",
      "! git add pie.py\n",
      "\n",
      "## check status pie.py is now \"staged\"\n",
      "! git status\n",
      "\n",
      "## see what has changed\n",
      "! git diff\n",
      "\n",
      "! git commit -am \"Added blueberry to pie.py\"\"\n",
      "\n",
      "## push to github (origin) your new branch (myfix)\n",
      "! git push origin myfix"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "##Pull Request\n",
      "\n",
      "Now go back to your web browser and look at your repo\n",
      "\n",
      "![alt text] (files/images/pullrequest.png \"pull request\")\n",
      "\n",
      "Choose the correct branch  you want to have merged, and the correct repo branch desitnation\n",
      "\n",
      "Quick code review\n",
      "\n",
      "Merge the pull"
     ]
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "## Update your master\n",
      "\n"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# check out local master branch\n",
      "!git checkout master\n",
      "\n",
      "# pull changes from github\n",
      "!git fetch upstream\n",
      "\n",
      "# update the master branch\n",
      "!git rebase upstream/master\n",
      "\n",
      "# push it to your Github repo\n",
      "!git push\n",
      "\n",
      "## Delete the branch\n",
      "! git branch -D myfix\n",
      "\n",
      "## delete on github\n",
      "!git push origin --delete myfix\n",
      "\n"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "## Rebasing repo to **upstream** master\n",
      "\n",
      "Sometimes you need to update your local repo (**master**) to get the updates in the **upstream** repo\n",
      "\n",
      "Othertimes you will be working on a local **branch**, and there will be changes to the **upstream** **master**\n",
      "\n",
      "Before you submit a pull request, you will want to incorporate these changes into your branch.  This has a few steps that seems to work quite well...\n",
      "\n",
      "1. in your local repo checkout **master**\n",
      "2. **fetch** and **rebase** changes from remote\n",
      "3. **checkout** your branch\n",
      "4. **rebase** **branch** to **master**\n",
      "(this will effectively bring your branch up to date, and then put your changes on top....so the  history will be maintained)\n",
      "\n",
      "Lets spell this out below"
     ]
    },
    {
     "cell_type": "code",
     "collapsed": false,
     "input": [
      "# go to the master branch\n",
      "!git checkout master\n",
      "\n",
      "# fetch changes from github\n",
      "!git fetch upstream\n",
      "\n",
      "# update the local master branch\n",
      "!git rebase upstream/master\n",
      "\n",
      "# push it to your Github repo\n",
      "!git push origin master\n",
      "\n",
      "## switch to your branch\n",
      "!git checkout <branch>\n",
      "\n",
      "# make a backup in case you mess up\n",
      "!git branch tmp my-new-feature\n",
      "\n",
      "# rebase <branch> on local master\n",
      "!git rebase master"
     ],
     "language": "python",
     "metadata": {},
     "outputs": []
    },
    {
     "cell_type": "markdown",
     "metadata": {},
     "source": [
      "Again, this is the **tip of the iceberg** with git. There are so many more items that can be covered, but this should give you two workflows that should serve you well.  Again I highly recommend reading the [git book](http://git-scm.com/book). Another great resource to get your head around the conceptual ideas behind git is covered in this nice notebook (by Matthew Brett) **roll_your_own_cms.ipynb** which is included in this repo."
     ]
    }
   ],
   "metadata": {}
  }
 ]
}