orientation/notebooks/intro2github.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<DIV ALIGN=CENTER>\n",
    "\n",
    "# Source Code Version Control    \n",
    "\n",
    "Note: Viewing this on github may result in some strange styling. IPython\n",
    "Notebooks are best viewed by using a Jupyter Server, which will be\n",
    "discussed in Week 1.\n",
    "\n",
    "\n",
    "</DIV>  \n",
    "-----\n",
    "-----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Source Code Version Control\n",
    "\n",
    "Whether you are writing a document or developing a computer program,\n",
    "eventually you will find a need for version control (or [revision\n",
    "control](https://en.wikipedia.org/wiki/Revision_control). In standard\n",
    "document editing software this is provided by the Undo feature, but we\n",
    "often want s more powerful solution to version control that allows:\n",
    "\n",
    "- Multiple users to work simultaneously\n",
    "- Document who made a change and why\n",
    "- Allow for recovery to a specific savepoint\n",
    "- Allow for remote backup and recovery\n",
    "\n",
    "Version control software has existed to provide one or more of these\n",
    "features for many years. Currently, one of the more popular version\n",
    "control software tools is `git`, in large part because of the popular\n",
    "__github__ online repository that uses the git tool to provide an easy\n",
    "version control tool for open source software development.\n",
    "\n",
    "In this lesson, we will learn how to use `git` and __github__ for source code version control.\n",
    "\n",
    "-----"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# Uncomment to live browse the PHD Comics site.\n",
    "# from IPython.display import HTML\n",
    "# HTML('<iframe src=http://www.phdcomics.com/comics/archive.php?comicid=1531 width=800 height=800></iframe>')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![PHD Comics version control](images/phdcomics.gif)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "-----\n",
    "## Github\n",
    "\n",
    "The most popular online source code control site is known as github,\n",
    "since it is a __hub__ of software projects that are all archived on the\n",
    "github website by using the `git` source code version control software.\n",
    "While you can use the `git` software locally, the real power of source\n",
    "code version control comes from working collaboratively on a project. A\n",
    "company or organization can run their own, secure, `git` server to\n",
    "support shared development, or you can use the __github__ web site as\n",
    "your server. __github__ by default supports open source development with\n",
    "public repositories, but you can purchase _enterprise_ support to allow\n",
    "private repositories.\n",
    "\n",
    "To use __github__, you first need to sign up for an account, after which\n",
    "you can either use the `git` software tool, as demonstrated later in\n",
    "this notebook, or the github desktop tool to create repositories, to\n",
    "commit changes, and to sync your local repository with the public\n",
    "repository maintained by __github__.\n",
    "\n",
    "-----"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# Uncomment to live browse the course github site.\n",
    "# from IPython.display import HTML\n",
    "# HTML('<iframe src=https://github.com/ProfessorBrunner width=800 height=800></iframe>')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Github Account\n",
    "\n",
    "In this course, we eventually would like to use __github__ to provide\n",
    "user authentication to a cloud computing system. In preparation for\n",
    "this, you can obtain a free __github__ account. If you already have a\n",
    "__github__ account, you can reuse your existing github credentials for\n",
    "this course. If not, you should go to the [Github\n",
    "Website](http://github.com), and sign up for a new account by clicking\n",
    "on the __Sign up for Github__ button on the main github website, as\n",
    "shown below, and following the directions.\n",
    "\n",
    "![Github website](images/github-website.png)\n",
    "\n",
    "Since you may need these credentials to access the course computing\n",
    "resources in the future (and we would encourage you to use github for\n",
    "your source code or document revision control), you should save your\n",
    "credentials for future use.\n",
    "\n",
    "-----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Github Desktop Client\n",
    "\n",
    "While `git` and __github__ were designed to be used from the Unix\n",
    "command line, __github__ can also be accessed via a Desktop client\n",
    "application, as shown below.\n",
    "\n",
    "![Github Desktop Client](images/github-appclient.png)\n",
    "\n",
    "The __github__ desktop application can be downloaded directly from the\n",
    "[__github__ site](https://desktop.github.com), shown in the following screenshot.\n",
    "\n",
    "![Github Desktop Client](images/github-app.png)\n",
    "\n",
    "From this application you can clone github repositories, easily by\n",
    "clicking the _Clone in Desktop_ button on the left hand side of the\n",
    "repositories homepage, as shown below for the github\n",
    "repository for this course.\n",
    "\n",
    "![Github Clone Button ](images/github-button.png)\n",
    "\n",
    "The app will also track changed files, including new files\n",
    "or deleted files, so that you can commit changes by simply clicking the\n",
    "_Commit to master_ button. To push these changes to the __github__\n",
    "repository, simply click the _Sync_ button.\n",
    "\n",
    "-----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## `git`\n",
    "\n",
    "[`git`](http://git-scm.com) is a popular, free, open source version\n",
    "control software tool. `git` can support fully distributed projects, by\n",
    "using a shared server.\n",
    "\n",
    "![Git Website Note](images/git-website.png)\n",
    "\n",
    "In this course, you will not be required to frequently use `git`,\n",
    "however, you can do so if you wish to use a source code versioning\n",
    "system for your class notes and software assignments. If you wish to do\n",
    "this, you can use `git` and (optionally) __github__ from within a\n",
    "terminal window, either a regular Unix shell or a terminal connected to\n",
    "a JupyterHub docker container. The rest of this document demonstrates\n",
    "how to do this.\n",
    "\n",
    "-----"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "# We could uncomment to display and live browse the git website\n",
    "# from IPython.display import HTML\n",
    "# HTML('<iframe src=http://git-scm.com width=800 height=500></iframe>')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Install & Configure `git`\n",
    "\n",
    "If `git` is not already installed on your computer, you can easily\n",
    "[download][1] and install `git`. However, `git` is installed in our\n",
    "course Docker image. Once you have completed [Lesson 2 in Week\n",
    "1](https://github.com/UI-DataScience/info490-fa15/blob/master/Week1/lesson2.md), you can set up `git` in your course Docker\n",
    "container (the same steps will work in a terminal window that runs on\n",
    "our course JupyterHub server):\n",
    "\n",
    "1. Start a terminal window. This can be your course Docker container\n",
    "running in interactive mode, a standard Unix terminal on a Linux or Mac\n",
    "OSX system, or, if you have a Jupyter Server running, you can access a\n",
    "terminal window by clicking the _new_ button on your Jupyter server\n",
    "homepage.\n",
    "2. Test to see if `git` is already installed by entering `git` at the container prompt.  \n",
    "2.1. `git` should be installed in the container so you should see the `git` usage displayed.   \n",
    "2.2. If `git` is not installed, you can easily [download][1] and install `git`.  \n",
    "3. Once `git` is installed, we should set several configuration parameters   \n",
    "3.1. We can specify a name: `git config --global user.name \"Your Name Here\"`  \n",
    "3.2. We can specify an email: `git config --global user.email \"Your Email Here\"`  \n",
    "3.3. We might need to define a proxy (e.g., http) to use a distributed repository.  \n",
    "3.4. We could set a number of other options, including colorization or default editor (e.g., `vim`).  \n",
    "\n",
    "In the following screen shots, we show `git` being used in a terminal\n",
    "window running on a JupyterHub server. You should see similar results on\n",
    "other terminals, although the unix prompt and the background and prompt colors might be\n",
    "different.\n",
    "\n",
    "![Git Configure](images/git-config.png)\n",
    "\n",
    "-----\n",
    "[1]: http://www.git-scm.com/downloads"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create a `git` Repository\n",
    "\n",
    "Once `git` is installed and configured, we can create a new repository.\n",
    "In this example, we will create a new directory, and add a single file.\n",
    "but you can take an existing set of files and directories and transform\n",
    "them into a `git` repository by following the same steps.\n",
    "\n",
    "First, we will create a new directory, called `projects`:\n",
    "\n",
    "```console\n",
    "data_scientist@temp_host:~$ mkdir projects\n",
    "```\n",
    "\n",
    "Second, change into this new directory and create a single file called\n",
    "`plan`. We can write some placeholder text in this file by using the\n",
    "`echo` command (alternatively we could use an editor like `vim`).\n",
    "\n",
    "```console\n",
    "data_scientist@temp_host:~$ cd projects\n",
    "```\n",
    "\n",
    "At this point, we have a project directory. We can create a repository\n",
    "for this file by using the `git init` command:\n",
    "\n",
    "```console\n",
    "data_scientist@temp_host:~$ git init\n",
    "```\n",
    "\n",
    "![Git Init](images/git-init.png)\n",
    "\n",
    "Notice how in the new directory listing, we have a new sub-directory\n",
    "called `.git`. This sub-directory contains the tracking information for\n",
    "this project; deleting this directory will remove the entire project\n",
    "history.\n",
    "\n",
    "-----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Modifying a `git` repository\n",
    "\n",
    "Now that our repository is initialized, we can add a file to track. First, we create a file called `plan`. We write placeholder text into this file by using the `echo` command (alternatively we could use an editor like vim).\n",
    "\n",
    "```console\n",
    "data_scientist@temp_host:~$ echo \"Todo: Write the great American novel!\" > plan\n",
    "```\n",
    "\n",
    "At this point, we have a project directory containing one file. We can always track the status of our repository by using the `git status` comand:\n",
    "\n",
    "```console\n",
    "data_scientist@temp_host:~$ git status\n",
    "```\n",
    "\n",
    "The output of this command states that there is an untracked file in our project directory. To have git track this file, we need to `add` it to the repostiory, which we do with the `git add` command:\n",
    "\n",
    "```console\n",
    "data_scientist@temp_host:~$ git add plan\n",
    "```\n",
    "\n",
    "![Git Add](images/git-add.png)\n",
    "\n",
    "At this point we have a repository with one file.\n",
    "\n",
    "-----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Committing a `git` repository\n",
    "\n",
    "If we check the status of our git repository at this point, we see that\n",
    "we have uncommitted changes. To save the current state of the repository,\n",
    "we use the `git commit` command. When making a commit, we are given the\n",
    "option of writing detailed comments on what changes are being made. This\n",
    "forms an important history, and allows you, or other members of your\n",
    "team to understand what was changed and why at some later date.\n",
    "\n",
    "The commit message can be directly specified on the command line by\n",
    "using the `-m` flag, which is fine for short messages.\n",
    "\n",
    "```console\n",
    "data_scientist@temp_host:~$ git commit -m\"Added new life plan.\"\n",
    "```\n",
    "\n",
    "We can now check the status of our git repository by issuing a new `git\n",
    "status` command.\n",
    "\n",
    "![Git Commit](images/git-commit.png)\n",
    "\n",
    "Our repository is now up-to-date.\n",
    "\n",
    "-----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Distributed Repositories\n",
    "\n",
    "So far we have only worked with a local repository. This can be useful to provide version control for individuals, or on a shared server. But the real power of git arises when you work on a distributed server. We will not cover setting up and using a general distributed git server in this course. Instead, we will use the online [github site](https://github.com).\n",
    "\n",
    "-----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using _github_\n",
    "\n",
    "To use _github_, you need a working `git` installation, and, if you will\n",
    "be uploading files to a _github_ repository,  you need to choose and set a\n",
    "proxy method since you will need to repeatedly\n",
    "[authenticate](https://help.github.com/articles/set-up-git/#next-steps-authenticating-with-github-from-git) to _github_. [Connecting over\n",
    "HTTPS](https://help.github.com/articles/which-remote-url-should-i-use#cloning-with-https-recommended) is recommended and is the easiest to\n",
    "setup, so for now we will use this method.\n",
    "\n",
    "The [general\n",
    "instructions](https://help.github.com/articles/caching-your-github-password-in-git/) for caching your _github_ password in\n",
    "git are located on the _github_ website. In our case, we can simply set\n",
    "two additional configuration parameters:\n",
    "\n",
    "```console\n",
    "data_scientist@temp_host:~$ git config --global credential.helper cache\n",
    "data_scientist@temp_host:~$ git config --global credential.helpe 'cache --timeout=3600'\n",
    "```\n",
    "\n",
    "Now we can clone an existing repository on _github_ into our local\n",
    "repository. Note that if we do this by using the _github_ web interface,\n",
    "this process is known as forking.\n",
    "\n",
    "![Git CLone](images/git-clone.png)\n",
    "\n",
    "### Warning: Do not upload sensitive information to _github_!\n",
    "\n",
    "-----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Additional References\n",
    "\n",
    "1. The [git tutorial](http://git-scm.com/book/en/v1/Getting-Started)\n",
    "2. [Try out git](https://try.github.io/levels/1/challenges/1) online.\n",
    "3. How to [setup github](https://help.github.com/articles/set-up-git/).\n",
    "\n",
    "-----"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.4.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}