Making GitHub Less Scary.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Don't Bother With This One\n",
    "\n",
    "The following command loads in presentation-friendly styles, which you probably don't want on your local version:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from IPython.display import HTML\n",
    "HTML(filename='styles/presentation.css')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "source": [
    "## Beforehand Setup\n",
    "<ul>\n",
    "<li>[Install git](https://git-scm.com/downloads)</li>\n",
    "<li>Verify that also installed `git gui` and `gitk`</li>\n",
    "<ul style=\"margin-top: 0\">\n",
    "<li>Open a terminal command prompt and try each command. If a window pops up, you're ready.</li>\n",
    "<li>If not, get in touch via the Women in Data Science (ATX) Slack or Meetup.</li>\n",
    "</ul>\n",
    "<li>Create a [GitHub user account](https://github.com/)</li>\n",
    "<ul style=\"margin-top: 0\">\n",
    "<li>Some use the same account for work and personal, or you might prefer a separate account.</li>\n",
    "</ul>\n",
    "<li>Clone the workshop repo: [https://github.com/scichelli/wids-github.git](https://github.com/scichelli/wids-github.git)</li>\n",
    "</ul>\n",
    "\n",
    "<hr>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# 👻 Making GitHub Less Scary\n",
    "\n",
    "Women in Data Science &ndash; ATX &mdash; October, 2017\n",
    "\n",
    "## What is Git? And GitHub?\n",
    "\n",
    "<img src=\"images/git-logo.png\" alt=\"Git logo\" style=\"display:inline\" width=40>\n",
    "Git is a version-control tool, a way to keep track of changes to files (code, documents, images...).\n",
    "\n",
    "<img src=\"images/octocat.png\" alt=\"GitHub Octocat logo\" style=\"display:inline\" width=40>\n",
    "GitHub is a social website for sharing and collaborating on open-source software and documentation. Or work.\n",
    "\n",
    "<img src=\"images/tracking-source-code.png\" alt=\"Different modifications to the same code, how should they be combined?\" width=800>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Makes Us Want to Set 🔥 to It All\n",
    "* I have to merge?\n",
    "* \"Detached HEAD\"??\n",
    "* My push is rejected???"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Why GitHub\n",
    "\n",
    "### Might have to for work\n",
    "\n",
    "<img src=\"images/github-for-work.png\" width=400 style=\"display:inline\" alt=\"screenshot of GitHub UI for an employer's organization\">\n",
    "\n",
    "### Keep track of personal projects\n",
    "\n",
    "<img src=\"images/github-for-personal-projects.png\" width=500 style=\"display:inline\" alt=\"screenshot of GitHub history for an Arduino project\">\n",
    "\n",
    "### Get involved, make a difference\n",
    "\n",
    "<img src=\"images/github-for-activism.png\" width=700 style=\"display:inline\" alt=\"screenshot of Open Austin's activism project ideas in GitHub\">\n",
    "\n",
    "### Participate in the community &mdash; up-for-grabs.net\n",
    "\n",
    "<img src=\"images/up-for-grabs.png\" width=700 style=\"display:inline\" alt=\"screenshot of up-for-grabs.net banner\">\n",
    "\n",
    "### Fix something that bugs you\n",
    "\n",
    "<img src=\"images/github-for-fixing-things.png\" width=700 style=\"display:inline; vertical-align:text-top; float:left; margin-right:10px\" alt=\"screenshot of pull request with an edit to Microsoft's online documentation\"> Documentation is a great way to contribute to open source."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Fork 🍴 and Clone 👯\n",
    "\n",
    "### GitHub website to fork\n",
    "\n",
    "Make your own copy of the demo repo from https://github.com/scichelli/wids-github-exercises.\n",
    "\n",
    "<img src=\"images/fork.png\" width=800 alt=\"Use the 'fork' button in the upper right of the GitHub UI\">\n",
    "\n",
    "### Command line to clone\n",
    "\n",
    "Use the command-line to get a local version of your repo. Copy the HTTPS url from the \"Clone or download\" button in _your_ GitHub repo.\n",
    "\n",
    "<img src=\"images/clone.png\" width=800 alt=\"Use the 'clone or download' button to get the url to use in your 'clone' command\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Change directory up one level to the folder containing this one:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%cd .."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Put your repo's url into the command below before running it. It will clone your repo into a new folder:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git clone https://github.com/your-user-name/wids-github-exercises.git"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Change directory into your new repo:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%cd wids-github-exercises"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"images/fork-and-clone.png\" width=700 alt=\"Fork makes a copy on GitHub; clone makes a local copy of your GitHub copy.\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Remote repos\n",
    "\n",
    "<img src=\"images/mine-and-yours.png\" width=700 alt=\"The original repo is 'mine'; the copy on GitHub is 'yours', and the local copy is 'also yours'.\">"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git remote -v"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git remote add upstream https://github.com/scichelli/wids-github-exercises.git"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git remote -v"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"images/upstream-origin-remotes.png\" width=700 alt=\"The original repo is a remote named 'upstream'; your fork is a remote named 'origin'.\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Staying in sync\n",
    "\n",
    "<img src=\"images/pull-upstream.png\" width=700 alt=\"'git pull upstream master' will update your local master branch with the master branch from the upstream remote.\">\n",
    "\n",
    "<img src=\"images/push-origin.png\" width=700 alt=\"'git push origin master' will push your local master branch to a branch named master in the origin remote.\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Configure Using `git config`\n",
    "* Full name\n",
    "* Email"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "Change the name and email values below before running the commands."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git config --global user.name \"Your Name\"\n",
    "git config --global user.email you@whatever.com"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "View what the values are set to:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "git config user.name\n",
    "git config user.email"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Resolving Conflicts 🤝\n",
    "* Commit a change in GitHub, directly into the remote\n",
    "* Commit a change locally\n",
    "* Merge and resolve the conflict"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Step 1: Edit `1_first.txt` in GitHub\n",
    "\n",
    "<img src=\"images/commit-in-github.png\" width=500 alt=\"Use the GitHub web UI to edit a file and commit the change\">\n",
    "\n",
    "### Step 2: Edit `2_second.txt` locally\n",
    "\n",
    "Save the file, then use `git gui` to review and commit it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git gui"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "<img src=\"images/commit-in-git-gui.png\" width=700 alt=\"Use 'git gui' utility to review the change and commit it\">\n",
    "\n",
    "Staging a file &rarr; `git add <file>`\n",
    "\n",
    "Entering a message and clicking \"Commit\" &rarr; `git commit -m \"msg\"`\n",
    "\n",
    "Launch `gitk` to look at the history, including your new commit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "gitk"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "<img src=\"images/commit-in-gitk.png\" width=600 alt=\"Use 'gitk' to see your new local commit\">\n",
    "\n",
    "Look at GitHub and notice that your change isn't there (yet)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### What _is_ a Commit?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "Snapshot of:\n",
    "\n",
    "* The state of the files in the repository\n",
    "* Who made the commit\n",
    "* And when\n",
    "* With a comment\n",
    "* And a pointer to prior \"parent\" commit(s)\n",
    "\n",
    "Assigned a unique ID (as a SHA-1 Hash)\n",
    "\n",
    "### Like waiting in line in Spain\n",
    "\n",
    "http://www.theolivepress.es/spain-news/2015/07/11/the-curious-case-of-queuing-in-spain/\n",
    "\n",
    "<img src=\"images/waiting-in-line.png\" alt=\"Commits point at their parents like a person waiting in line can point at the person they follow.\" width=600>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Tiny commits help you track your train of thought.\n",
    "\n",
    "[History of commits for my tiny robot](https://github.com/scichelli/Arduino-Sketches/commits/master/GirlGeniusClank)\n",
    "\n",
    "<img src=\"images/tiny-robot.jpg\" width=400 alt=\"Me with a tiny robot on my shoulder\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Push, but Error?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git push origin master"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "<img src=\"images/history-conflict.png\" width=600 alt=\"Which order should the remote and local commits be placed in?\">\n",
    "\n",
    "Take note of the response message; it contains instructions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Pull and Merge"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git pull origin master"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git push"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "Look in GitHub to see your new commit, plus a merge commit, now added to the remote repo as well as your local one.\n",
    "\n",
    "<img src=\"images/history-with-merge.png\" width=700 alt=\"The 'commits' tab in GitHub will show the local and the remote commits, plus a merge commit.\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Detached HEAD 🎃"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "Check out a previous commit using its hash (its ID).\n",
    "\n",
    "We'll use this one: https://github.com/scichelli/wids-github-exercises/commit/bd43fdcab86c948d11f5d1ff4fec1784f9c9808f\n",
    "\n",
    "To \"check out\" a commit is to put your files into the state they were in at that snapshot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git checkout bd43fdc"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "Look in `2_second.txt` and see that your edits are gone. It's still in the repo's history, but you're looking at a prior point in time."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### `HEAD` is a text file\n",
    "\n",
    "<img src=\"images/head-is-a-text-file.png\" width=600 alt=\"Find the HEAD file inside the .git directory in this repo\">\n",
    "\n",
    "`git checkout bd43fdc` &rarr; `bd43fdcab86c948d11f5d1ff4fec1784f9c9808f`\n",
    "\n",
    "`git checkout master` &rarr; `ref: refs/heads/master`\n",
    "\n",
    "### `HEAD` is a label\n",
    "\n",
    "So are branches.\n",
    "\n",
    "<img src=\"images/passing-head.png\" alt=\"You can think of checking out a branch as passing a sign that says HEAD from one person to another\" width=600>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "Return to normal by checking out a named branch, such as `master`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git checkout master"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Resolving Conflicty Conflicts\n",
    "\n",
    "We've resolved a conflict in history. Two commits had the same parent, and we created a merge commit to relate them to each other."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "What if the _contents_ of the files conflict?\n",
    "\n",
    "* Commit another change in GitHub\n",
    "* Edit the same file locally and commit\n",
    "* Merge and resolve conflict\n",
    "\n",
    "### Step 1: Edit `3_third.txt` in GitHub\n",
    "\n",
    "### Step 2: Locally, edit `3_third.txt` in the same spot and commit"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git gui"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "Pull to start the merge."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git pull"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "You can abort the merge if you need to, make some changes, and then pull again."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git merge --abort\n",
    "git status"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "Use `git pull` to try again."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git pull"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "<img src=\"images/conflict-in-text-editor.png\" width=500 alt=\"Git adds conflict hints to the text file.\">\n",
    "\n",
    "<img src=\"images/conflict-in-git-gui.png\" width=700 alt=\"git gui shows the conflicted file, waiting to be fixed and staged.\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "Edit the file to create the intended final version and commit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git gui"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git push"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Merge Tools"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "<img src=\"images/conflict-in-p4merge.png\" width=800 alt=\"p4merge is a free visual-merge tool\">\n",
    "\n",
    "### Configure in your `.gitconfig`\n",
    "\n",
    "```\n",
    "[diff]\n",
    " \ttool = p4merge\n",
    " \trenames = copies\n",
    "[difftool]\n",
    " \tprompt = false\n",
    "[merge]\n",
    " \ttool = p4merge\n",
    "[mergetool \"p4merge\"]\n",
    "\tprompt = false\n",
    "\tkeepBackup = false\n",
    "\ttrustExitCode = true\n",
    "\tpath = C:\\\\Program Files\\\\Perforce\\\\p4merge.exe\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Undo Changes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "source": [
    "### Local, Not Committed\n",
    "\n",
    "<img src=\"images/revert-in-git-gui.png\" width=500 alt=\"You can use 'git gui' to revert uncommitted changes\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Get Back to How It Looks in GitHub"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "Locally, edit `4_fourth.txt` and commit it. \n",
    "\n",
    "Then make a branch to remember this spot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git branch experiment1\n",
    "gitk"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "<img src=\"images/created-a-branch.png\" width=400 alt=\"gitk shows branch labels for 'master' and 'experiment1' in the local repo, and 'origin/master' on the remote\">"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git fetch origin\n",
    "git reset --hard origin/master"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Explanation of those commands:**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "`fetch` updates your repo with info from the remote named `origin` (but not your working directory). Locally, you have a branch named `master` and you have a picture of `origin/master`. `fetch` updates that picture.\n",
    "\n",
    "`reset` moves HEAD back to the named commit, which in this case is the commit that has the label `master` in the remote named `origin`. \n",
    "\n",
    "`--hard` is the [mode for the reset](https://git-scm.com/docs/git-reset#git-reset-emgitresetemltmodegtltcommitgt), specifying that uncommitted changes should be discarded.\n",
    "\n",
    "Look in the file you edited, and you will see that your change is gone. Look at history with `gitk` to see that local master and remote master point to the same commit.\n",
    "\n",
    "<img src=\"images/after-revert.png\" width=400 alt=\"gitk will now show 'master' and 'origin/master' pointing at the same commit\">"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "gitk"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### _Un_-throw That Away"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git checkout experiment1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "We moved HEAD to the commit we labeled with `experiment1` with the `git branch` command. `experiment1` is called a branch.\n",
    "\n",
    "<img src=\"images/passing-head.png\" width=600 alt=\"Checking out a branch is like moving a label that says HEAD to another commit\">\n",
    "\n",
    "Note that your change is restored.\n",
    "\n",
    "Merge that branch into `master` to keep the change and add it into the history."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git checkout master\n",
    "git merge experiment1"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "<img src=\"images/branch-merged-to-master.png\" width=450 alt=\"After merge, the labels 'master' and 'experiment1' point at the same commit\">\n",
    "\n",
    "Push to GitHub if you wish."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git push"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Helpful Guides\n",
    "* [Choose-Your-Own-Adventure-style](https://sethrobertson.github.io/GitFixUm/fixup.html) by Seth Robertson\n",
    "* [Oh Shit, Git](http://ohshitgit.com/) by Katie Sylor-Miller"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Branches\n",
    "* Shelve a train of thought (more resilient than `git stash`)\n",
    "* Make commits without affecting your team\n",
    "* Push unfinished work (in a branch) to GitHub as a backup\n",
    "* Pull Requests start with branches"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "### Using Branches Effectively\n",
    "* One coherent unit of work (i.e., one feature)\n",
    "* Do file renames, whitespace changes, even merges, in separate commits from any \"real work\" \n",
    "* Merge `origin master` into your branch often\n",
    "* Don't let a branch live too long\n",
    "* Know which branch you're committing to\n",
    "* Bite-sized merges are easier to get right\n",
    "\n",
    "```\n",
    "git checkout master\n",
    "git pull origin master\n",
    "git checkout experiment1\n",
    "git merge master\n",
    "```\n",
    "\n",
    "We'll practice more with branches as we create a pull request."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Pull Request\n",
    "* I _request_ that you _pull_ my changes into your repo.\n",
    "* The way to contribute to open source\n",
    "* Useful for teams, too\n",
    "* Code reviews and conversations\n",
    "* Starts with a branch\n",
    "\n",
    "[Example pull request to Open States project](https://github.com/openstates/openstates/pull/1749)\n",
    "\n",
    "### In-line comments and feedback\n",
    "\n",
    "<img src=\"images/pull-request-conversation.png\" width=700 alt=\"A pull request allows teammates to discuss specific changes\">\n",
    "\n",
    "### Introduction and overview\n",
    "\n",
    "<img src=\"images/pull-request-intro.png\" width=500 alt=\"An introduction can explain the purpose and approach of the pull request\">\n",
    "\n",
    "### Process automation\n",
    "\n",
    "<img src=\"images/pull-request-automation.png\" width=400 alt=\"Teams can create automated responses to pull request actions\">\n",
    "\n",
    "### Conflict detection\n",
    "\n",
    "<img src=\"images/conflict-in-github.png\" width=600 alt=\"GitHub will detect if a conflict will prevent a pull request from merging\">\n",
    "\n",
    "<img src=\"images/conflict-resolved.png\" width=600 alt=\"GitHub will detect when all conflicts have been resolved\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 1: Create a branch"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "git checkout -b experiment2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "`checkout -b` creates a branch and checks it out in one step. Your current branch is now `experiment2`.\n",
    "\n",
    "Ask git for the current branch name:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "git rev-parse --abbrev-ref HEAD"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 2: Edit `5_fifth.txt` and commit\n",
    "\n",
    "### Step 3: Push the new branch to GitHub\n",
    "\n",
    "You can set up a remote tracking branch so that you can use the shorthand `git push` and `git pull` without specifying the remote and branch.\n",
    "\n",
    "I never remember the syntax, but the error message provides it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "git push"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "git push --set-upstream origin experiment2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "notes"
    }
   },
   "source": [
    "### Step 4: Go to GitHub to create the pull request from the branch\n",
    "\n",
    "From the main page of the repo:\n",
    "\n",
    "<img src=\"images/compare-and-pull-request.png\" width=700 alt=\"GitHub offers a 'compare and pull request' button if you recently pushed to a branch\">\n",
    "\n",
    "Or from the list of branches:\n",
    "\n",
    "<img src=\"images/branch-list-pull-request.png\" width=700 alt=\"You can create a pull request from the list of branches in GitHub\">\n",
    "\n",
    "### Step 5: Enter a title and description\n",
    "\n",
    "<img src=\"images/create-pull-request.png\" width=700 alt=\"Enter a title and description for the pull request\">\n",
    "\n",
    "Note that the destination is the repo you forked from.\n",
    "\n",
    "### Step 6: Submit the PR\n",
    "\n",
    "A pull request is for a _branch_, not a point in time. If you keep making commits to the branch, those changes will be included with the pull request.\n",
    "\n",
    "### Step 7: View the list of waiting PRs\n",
    "\n",
    "Your pull request will show up in _my_ repo. See the list here: https://github.com/scichelli/wids-github-exercises/pulls\n",
    "\n",
    "### Step 8: Make a comment on someone else's PR\n",
    "\n",
    "From the conversation tab:\n",
    "\n",
    "<img src=\"images/pull-request-comment.png\" width=700 alt=\"Enter a comment on from the Conversation tab\">\n",
    "\n",
    "And inline on the files tab:\n",
    "\n",
    "<img src=\"images/inline-comment.png\" width=700 alt=\"Enter a comment about a specific change from the Files tab\">\n",
    "\n",
    "### Step 9: After the merge\n",
    "\n",
    "Look at the [history of the repo](https://github.com/scichelli/wids-github-exercises/commits/master).\n",
    "\n",
    "From the \"commits\" tab:\n",
    "\n",
    "<img src=\"images/repo-commit-history.png\" width=500 alt=\"You can get to the repo's history from the 'commits' tab\">\n",
    "\n",
    "When a branch has been merged, you can safely delete the branch.\n",
    "\n",
    "You can also close a PR without merging it, if it turned out to be a bad idea."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Contributing to Open Source\n",
    "* Docs are a super way to help\n",
    "* Some repositories have `CONTRIBUTING.md` ([example](https://github.com/WeAllJS/weallcontribute/blob/latest/CONTRIBUTING.md))\n",
    "* Open a GitHub issue to start a conversation\n",
    "* Find a friendly repo on [up-for-grabs.net](http://www.up-for-grabs.net/)\n",
    "\n",
    "## Next-Level Topics: Rewriting History\n",
    "* `rebase`\n",
    "* `amend`\n",
    "* `cherry-pick`\n",
    "* Fast-forward merge\n",
    "* `squash`\n",
    "* `--force`\n",
    "\n",
    "But do not change shared history!\n",
    "\n",
    "## Next-Level Topics: Exploring History\n",
    "* `blame`\n",
    "* `bisect`\n",
    "* `reflog`\n",
    "* View in GitHub\n",
    "\n",
    "## Summary\n",
    "* A commit is a snapshot\n",
    "* Merging and resolving conflicts\n",
    "* Branches, master, and HEAD\n",
    "* Reverting changes\n",
    "* Pull requests"
   ]
  }
 ],
 "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.6.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}