git.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Version Control with Git"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**This tutorial is largely based on the repository**:\n",
    "\n",
    "git@github.com:rdadolf/git-and-github.git\n",
    "\n",
    "**which was created for IACS's ac297r course, By Robert Adolf. Most of the credit goes to him**.\n",
    "\n",
    "I edited it for cs109, and subsequently for cs207,and now for ai1.\n",
    "\n",
    "Version control is a way of tracking the change history of a project. Even if you have never used a version control tool, you've probably already done it manually: copying and renaming project folders (\"paper-1.doc\", \"paper-2.doc\", etc.) is a form of version control.\n",
    "\n",
    "Git is a tool that automates and enhances a lot of the tasks that arise when dealing with larger, longer-living, and collaborative projects. It's also become the common underpinning to many popular online code repositories, [GitHub](https://github.com/) being the most popular.\n",
    "\n",
    "We'll go over the basics of git, but we should point out that a *lot* of talented people have given git tutorials, and we won't do any better than they have. In fact, if you're interested in learning git deeply and have some time on your hands, I suggest you stop reading this and instead read [the Git Book](http://git-scm.com/book/en/v2). Scott Chacon and Ben Straub have done a tremendous job, and if you want to understand both the interfaces and the mechanisms behind git, this is the place to start."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Table of Contents\n",
    "* [Version Control with Git](#Version-Control-with-Git)\n",
    "\t* [Why should you use version control?](#Why-should-you-use-version-control?)\n",
    "\t* [Git Basics](#Git-Basics)\n",
    "\t* [Common Tasks in the version control of files.](#Common-Tasks-in-the-version-control-of-files.)\n",
    "\t\t* [Forking a repository](#Forking-a-repository)\n",
    "\t\t* [Cloning a repository](#Cloning-a-repository)\n",
    "\t\t* [Poking around](#Poking-around)\n",
    "\t\t* [Making changes](#Making-changes)\n",
    "\t* [Creating a new repository](#Creating-a-new-repository)\n",
    "\t* [Git habits](#Git-habits)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**At this point, we assume you have installed git as described in HW0 and have followed the instructions there to create ssh keys for your machine**. This enables you to use git without a pesky username-password combination."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Why should you use version control?"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you ask 10 people, you'll get 10 different answers, but one of the commonalities is that most people don't realize how integral it is to their development process until they've started using it. Still, for the sake of argument, here are some highlights:\n",
    "\n",
    "- ** You can undo anything: ** Git provides a *complete history* of every change that has ever been made to your project, timestamped, commented, and attributed. If something breaks, you always have the choice of going back to a previous state.\n",
    "- ** You won't *need* to keep undo-ing things: ** One of the advantages of using git properly is that by keeping new changes separate from a stable base, you tend to avoid the massive rollbacks associated with constantly tinkering with a single code.\n",
    "- ** You can identify exactly when and where changes were made: ** Git allows you to pinpoint when a particular piece of code was changed, so finding what other pieces of code a bug might affect or figuring out why a certain expression was added is easy.\n",
    "- ** Git forces teams to face conflicts directly: ** On a team-based project, many people are often working with the same code. By having a tool which understands when and where files were changed, it's easy to see when changes might conflict with each other. While it might seem troublesome sometimes to have to deal with conflicts, the alternative&mdash;*not* knowing there's a conflict&mdash;is much more insidious."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Git Basics"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The first thing to understand about git is that the contents of your project are stored in several different states and forms at any given time. If you think about what version control is, this might not be surprising: in order to remember every change that's ever been made, you need to store a record of those changes *somewhere*, and to be able to handle multiple people changing the same code, you need to have different copies of the project and a way to combine them.\n",
    "\n",
    "You can think about git operating on four different areas:\n",
    "\n",
    "![Git Commands](images/git_layout.png)\n",
    "\n",
    " - The **working directory** is what you're currently looking at. When you use an editor to modify a file, the changes are made to the working directory.\n",
    " - The **staging area** is a place to collect a set of changes made to your project. If you have changed three files to fix a bug, you will add all three to the staging area so that you can remember the changes as one historical entity. It is also called the **index**. You move files from the working directory to the index using the command `git add`.\n",
    " - The **local repository** is the place where git stores everything you've ever done to your project. Even when you delete a file, a copy is stored in the repo (this is necessary for always being able to undo any change). It's important to note that a local repository doesn't look much at all like your project files or directories. Git has its own way of storing all the information, and if you're curious what it looks like, look in the `.git` directory in the working directory of your project. Files are moved from the index to the local repository via the command `git commit`.\n",
    " - When working in a team, every member will be working on their own local repository. An **upstream repository** allows everyone to agree on a single version of history. If two people have made changes on their local repositories, they will combine those changes in the upstream repository. In our case this upstream repository is hosted by github. This need not be the case; SEAS provides git hosting, as do companies like Atlassian (bitbucket). This upstream repository is also called a **remote** in git parlance. The standard github remote is called the **origin**: it is the repository which is given a web page on github. One usually moves code from local to remote repositories using `git push`, and in the other direction using `git fetch`.\n",
    "\n",
    "You can think of most git operations as moving code or metadata from one of these areas to another."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Common Tasks in the version control of files."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Forking a repository"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Forking a repository done on github. On github, go to the url https://github.com/univai/toplay. Click the \"Fork button on the upper right side. A screenshot is below. \n",
    "\n",
    "![forking](images/github-forking.png)\n",
    "\n",
    "Forking brings a repository into your own namespace. Its really a *cloning* process (see below), but its done between two \"remotes\" on the server. In other words it creates a second upstream repository on the server, called the **origin**.\n",
    "\n",
    "The forking process on github will either fork to your own github id on github, or ask you *where* you want to fork the repository. In that case choose your own github id. Then you will see a screen like this:\n",
    "\n",
    "![forking](images/github-forking2.png)\n",
    "\n",
    "In my case I will choose `@rahuldave`. In this tutorial, wherever you see `rahuldave`, substitute your own github id.\n",
    "\n",
    "This leaves me with my own repository, `rahuldave/toplay`, as seen in this image\n",
    "\n",
    "![forking](images/github-forking3.png)\n",
    "\n",
    "You will get a similar page."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Cloning a repository"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that we have a **fork** of the `univai/toplay` repository, lets **clone** it down to our local machines."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----\n",
    "`clone`\n",
    "\n",
    "![clone](images/git_clone.png)\n",
    "\n",
    "Cloning a repository does two things: it takes a repository from somewhere (usually an **upstream repository**) and makes a local copy (your new **local repository**), and it creates the most recent copy of all of the files in the project (your new **working directory**). This is generally how you will start working on a project for the first time."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Cloning a repository depends a lot on the type of repository you're using. If you're cloning out of a directory on the machine you're currently on, it's just the path to the `<project>.git` file. For github, you can clone over *ssh* using the SSH clone url in the bottom right corner of the last screenshot. This assumes you have set up your ssh keys. If you have no clue what we are talking about, use *https* instead."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note for windows users**\n",
    "\n",
    "`bash.exe` is installed along with git but isnt in your path. Type the contents of the next cell to your terminal and run it to add the path to bash to your path"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "import os\n",
    "os.environ['path']+=\"C:\\Program Files\\Git\\\\bin\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Make sure now that you are in a folder where you want to work, such as your `Documents` folder, or a created `Documents/ai1` folder. Then type the following, ignoring the lines starting with hashes, which are comments:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```bash\n",
    "rm -rf toplay \n",
    "#remove if it exists\n",
    "git clone git@github.com:rahuldave/toplay \n",
    "#use https if no ssh setup\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "    Cloning into 'toplay'...\n",
    "    remote: Enumerating objects: 14, done.\n",
    "    remote: Counting objects: 100% (14/14), done.\n",
    "    remote: Compressing objects: 100% (8/8), done.\n",
    "    remote: Total 14 (delta 3), reused 14 (delta 3), pack-reused 0\n",
    "    Receiving objects: 100% (14/14), done.\n",
    "    Resolving deltas: 100% (3/3), done.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Lets see the contents of this new folder:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```bash\n",
    "ls toplay\n",
    "```\n",
    "```\n",
    "    LICENSE   README.md app.py    hello.md\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Poking around"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We have a nice smelling fresh repository. Lets look around it.\n",
    "\n",
    "```bash\n",
    "cd toplay\n",
    "```\n",
    "\n",
    "This gets us inside the folder"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`log`\n",
    "\n",
    "Log tells you all the changes that have occured in this project as of now..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```bash\n",
    "git log\n",
    "```\n",
    "```\n",
    "    commit 0b80eb4f1c4ce9aafb0a39b93f89380b4595335c\n",
    "    Author: Rahul Dave <rahuldave@gmail.com>\n",
    "    Date:   Fri Sep 2 16:32:54 2016 -0400\n",
    "\n",
    "         comitted the poor fellow to an institution\n",
    "\n",
    "    commit 62846b8b8829359722d7e4a20745aea0b1161796\n",
    "    Author: Rahul Dave <rahuldave@gmail.com>\n",
    "    Date:   Thu Sep 1 16:03:02 2016 -0400\n",
    "\n",
    "        Said hello to myself\n",
    "\n",
    "    commit 94e60ac8f57024a03e861bc34f20c65c7d8f7961\n",
    "    Author: Rahul Dave <rahuldave@gmail.com>\n",
    "    Date:   Thu Sep 1 15:53:55 2016 -0400\n",
    "\n",
    "        random choices\n",
    "\n",
    "    commit 20523188138fb29f59bf392156ac68b1764b8fd5\n",
    "    Author: Rahul Dave <rahuldave@gmail.com>\n",
    "    Date:   Thu Sep 1 15:46:54 2016 -0400\n",
    "\n",
    "        Initial commit\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Each one of these \"commits\" is a SHA hash. It uniquely identifies all actions that have happened to this repository previously. We shall soon see how to add our own actions in. In the meanwhile, lets see the \"status\"of our working directory."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you ever need help on a command, you can find the git man pages by hyphenating `git` and the command name:"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "$man git-status"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----\n",
    "`status`\n",
    "\n",
    "![status](images/git_status.png)\n",
    "\n",
    "Status is your window into the current state of your project. It can tell you which files you have changed and which files you currently have in your staging area."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```bash\n",
    "git status\n",
    "```\n",
    "```\n",
    "    On branch master\n",
    "    Your branch is up-to-date with 'origin/master'.\n",
    "    nothing to commit, working tree clean\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Pay close attention to the text above. It says we are on the master branch of our **local repository**, and that this branch is up-to-date with the master branch of the **upstream  repository** or **remote** named **origin**. We know this as clone brings down a copy of the remote branch:  \"`origin/master`\" represents the local copy of the branch that came from the upstream repository (nicknamed \"`origin`\" in this case). **Branches** are different, co-existing versions of your project. Here we have encountered two of them, but remember there is a third one in the repository we forked from, and perhaps many more, depending on who else made these forks (as well as my original clones of cs109/Testing).\n",
    "\n",
    "This sounds like a recipe for disaster, but in a sense, branches are just like commits. They represent a snapshot of the project, by someone, at some particular point in time. In general you will only care about your own branches, and those of the \"parent\" remotes you forked/cloned from.\n",
    "\n",
    "Configuration Information is stored in a special file `config`, in a hidden folder called `.git` in your working directory. (The index and the local repository are stored there as well...more on that in  a bit)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```bash\n",
    "cat .git/config\n",
    "```\n",
    "```\n",
    "    [core]\n",
    "        repositoryformatversion = 0\n",
    "        filemode = true\n",
    "        bare = false\n",
    "        logallrefupdates = true\n",
    "        ignorecase = true\n",
    "        precomposeunicode = true\n",
    "    [remote \"origin\"]\n",
    "        url = git@github.com:rahuldave/toplay\n",
    "        fetch = +refs/heads/*:refs/remotes/origin/*\n",
    "    [branch \"master\"]\n",
    "        remote = origin\n",
    "        merge = refs/heads/master\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Notice that this file tells us about a remote called \"origin\" which is simply the github repository we cloned from. So the process of cloning left us with a remote. The file also tells us about a branch called \"master\", which \"tracks\" a remote branch valled master at \"origin\". \n",
    "\n",
    "Finally I set us up with a `.gitignore` file, hidden in the repository folder. It tells us what files to ignore when adding files to the index, and then comitting them to the local repository. We use this file to ignore temporary data files and such when working in our repository. Folders are indicated with a `/` at the end, in which case, all files in that folder are ignored."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```bash\n",
    "cat .gitignore\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "    # Byte-compiled / optimized / DLL files\n",
    "    __pycache__/\n",
    "    *.py[cod]\n",
    "    *$py.class\n",
    "\n",
    "    # C extensions\n",
    "    *.so\n",
    "\n",
    "    # Distribution / packaging\n",
    "    .Python\n",
    "    env/\n",
    "    build/\n",
    "    develop-eggs/\n",
    "    dist/\n",
    "    downloads/\n",
    "    eggs/\n",
    "    .eggs/\n",
    "    lib/\n",
    "    lib64/\n",
    "    parts/\n",
    "    sdist/\n",
    "    var/\n",
    "    *.egg-info/\n",
    "    .installed.cfg\n",
    "    *.egg\n",
    "\n",
    "    # PyInstaller\n",
    "    #  Usually these files are written by a python script from a template\n",
    "    #  before PyInstaller builds the exe, so as to inject date/other infos into it.\n",
    "    *.manifest\n",
    "    *.spec\n",
    "\n",
    "    # Installer logs\n",
    "    pip-log.txt\n",
    "    pip-delete-this-directory.txt\n",
    "\n",
    "    # Unit test / coverage reports\n",
    "    htmlcov/\n",
    "    .tox/\n",
    "    .coverage\n",
    "    .coverage.*\n",
    "    .cache\n",
    "    nosetests.xml\n",
    "    coverage.xml\n",
    "    *,cover\n",
    "    .hypothesis/\n",
    "\n",
    "    # Translations\n",
    "    *.mo\n",
    "    *.pot\n",
    "\n",
    "    # Django stuff:\n",
    "    *.log\n",
    "    local_settings.py\n",
    "\n",
    "    # Flask stuff:\n",
    "    instance/\n",
    "    .webassets-cache\n",
    "\n",
    "    # Scrapy stuff:\n",
    "    .scrapy\n",
    "\n",
    "    # Sphinx documentation\n",
    "    docs/_build/\n",
    "\n",
    "    # PyBuilder\n",
    "    target/\n",
    "\n",
    "    # IPython Notebook\n",
    "    .ipynb_checkpoints\n",
    "\n",
    "    # pyenv\n",
    "    .python-version\n",
    "\n",
    "    # celery beat schedule file\n",
    "    celerybeat-schedule\n",
    "\n",
    "    # dotenv\n",
    "    .env\n",
    "\n",
    "    # virtualenv\n",
    "    venv/\n",
    "    ENV/\n",
    "\n",
    "    # Spyder project settings\n",
    "    .spyderproject\n",
    "\n",
    "    # Rope project settings\n",
    "    .ropeproject\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You are always working on a given branch in a repository. Typically this is `master`. More on this later..You can know which branch you are on by typing `git branch`. The starred one is the one you are on."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```bash\n",
    "git branch\n",
    "```\n",
    "```\n",
    "    * master\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Making changes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Ok! Enough poking around. Lets get down to business and add some files into our folder.\n",
    "\n",
    "Now let's say that we want to add a new file to the project. The canonical sequence is \"edit&ndash;add&ndash;commit&ndash;push\"."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```bash\n",
    "echo '# Hello world world' > world.md\n",
    "git status\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```\n",
    "    On branch master\n",
    "    Your branch is up-to-date with 'origin/master'.\n",
    "    Untracked files:\n",
    "      (use \"git add <file>...\" to include in what will be committed)\n",
    "\n",
    "        world.md\n",
    "\n",
    "    nothing added to commit but untracked files present (use \"git add\" to track)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We've added a file to the working directory, but it hasn't been staged yet."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----\n",
    "`add`\n",
    "\n",
    "![add](images/git_add.png)\n",
    "\n",
    "When you've made a change to a set of files and are ready to create a commit, the first step is to add all of the changed files to the staging area. Add does that. Remember that what you see in the filesystem is your working directory, so the way to see what's in the staging area is with the `status` command. This also means that **if you add something to the staging area and then edit it again, you'll also need to add the file to the staging area again if you want to remember the new changes**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```bash\n",
    "git add world.md\n",
    "git status\n",
    "```\n",
    "```\n",
    "    On branch master\n",
    "    Your branch is up-to-date with 'origin/master'.\n",
    "    Changes to be committed:\n",
    "      (use \"git reset HEAD <file>...\" to unstage)\n",
    "\n",
    "        new file:   world.md\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now our file is in the staging area (Index), waiting to be committed.\n",
    "\n",
    "I will sometimes simply use `git add .` in the top level of the repository. This adds all new files and changed files to the index, and is particularly useful if I have created multiple new files."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----\n",
    "`commit`\n",
    "\n",
    "![commit](images/git_commit.png)\n",
    "\n",
    "When you're satisfied with the changes you've added to your staging area, you can commit those changes to your local repository with the `commit` command. Those changes will have a permanent record in the repository from now on."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Every commit has two features you should be aware of. The first is a hash. This is a unique identifier for all of the information about that commit, including the code changes, the timestamp, and the author. The second is a commit message. This is text that you can (and should) add to a commit to describe what the changes were.\n",
    "\n",
    "**Good commit messages are important.**\n",
    "\n",
    "Commit messages are a way of quickly telling your future self (and your collaborators) what a commit was about. For even a moderately sized project, digging through tens or hundreds of commits to find the change you're looking for is a nightmare without friendly summaries.\n",
    "\n",
    "By convention, commit messages start with a single-line summary, then an empty line, then a more comprehensive description of the changes.\n",
    "\n",
    "[This](https://github.com/rdadolf/clangtool/commit/bdd8f1290146c28a4cb05b62ccb0ffbaaa314ff7) is an okay commit message. The changes are small, and the summary is sufficient to describe what happened.\n",
    "\n",
    "[This](https://github.com/rdadolf/protos/commit/9fcbe1084b17027e003c62043d764ed5551ddadc) is better. The summary captures the important information (major shift, direct vs. helper), and the full commit message describes what the high-level changes were.\n",
    "\n",
    "[This](https://github.com/rdadolf/autopaxos/commit/d43dd9b0a699c98bd142ba7cbc1836fbc4eba2ac). Don't do this."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```bash\n",
    "git commit -m \"Said hello world to world\"\n",
    "git status\n",
    "```\n",
    "```\n",
    "    [master 55c7b65] Said hello world to world\n",
    "     1 file changed, 1 insertion(+)\n",
    "     create mode 100644 world.md\n",
    "    On branch master\n",
    "    Your branch is ahead of 'origin/master' by 1 commit.\n",
    "      (use \"git push\" to publish your local commits)\n",
    "    nothing to commit, working tree clean\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The `git commit -m...` version is just a way to specify a commit message without opening a text editor (ipython notebook can't handle it). Otherwise you just say `git commit` or `git commit -a` (if you `add`ed a new file to the current branch on the repository)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```bash\n",
    "git branch -a\n",
    "```\n",
    "```\n",
    "    * master\n",
    "      remotes/origin/HEAD -> origin/master\n",
    "      remotes/origin/master\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now we see that our branch, \"`master`\", has one more commit than the \"`origin/master`\" branch, the local copy of the branch that came from the upstream repository (nicknamed \"`origin`\" in this case). Let's push the changes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`push`\n",
    "\n",
    "![push](images/git_push.png)\n",
    "\n",
    "The `push` command takes the changes you have made to your local repository and attempts to update a remote repository with them. If you're the only person working with both of these (which is how a solo GitHub project would work), then push should always succeed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "```bash\n",
    "git push\n",
    "git status\n",
    "```\n",
    "```\n",
    "    Counting objects: 3, done.\n",
    "    Delta compression using up to 4 threads.\n",
    "    Compressing objects: 100% (2/2), done.\n",
    "    Writing objects: 100% (3/3), 292 bytes | 0 bytes/s, done.\n",
    "    Total 3 (delta 1), reused 0 (delta 0)\n",
    "    remote: Resolving deltas: 100% (1/1), completed with 1 local object.\n",
    "    To github.com:rahuldave/toplay\n",
    "       0b80eb4..55c7b65  master -> master\n",
    "    On branch master\n",
    "    Your branch is up-to-date with 'origin/master'.\n",
    "    nothing to commit, working tree clean\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating a new repository"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Creating a repository can be done with git command line tools, or it can be done on github. On your github home, click on the 'Repositories' tab, then click the green 'New' button. You'll be brought to a page that asks for some basic project information.\n",
    "\n",
    "![new repo](images/github_new.png)\n",
    "\n",
    " - The repository name needs to be unique, but only amongst *your* github repositories. Despite what github suggests, try to pick something at least a little representative of your project.\n",
    " \n",
    " - The description field is just a short text field that will accompany your repository's name on the github website.\n",
    "\n",
    " - If you're creating a new repository, check the \"Initialize this repository with a README\" box. This is a little bit of a misnomer. If you don't do this, you won't be able to clone your repository at all. Instead, you'll have to manually create a new repository on your computer and upload that to github. Suffice to say, unless you've got an existing git repository that was hosted somewhere besides github, *always check this box*.\n",
    "\n",
    " - You're free to click the `.gitignore` or `license` buttons, too, but there's no requirement to do so. You can easily create either later. For our class I use a python `.gitignore` from the dropdown menu"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "----"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Git habits"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Commit early, commit often.**\n",
    "\n",
    "Git is more effective when used at a fine granularity. For starters, you can't undo what you haven't committed, so committing lots of small changes makes it easier to find the right rollback point. Also, merging becomes a lot easier when you only have to deal with a handful of conflicts.\n",
    "\n",
    "**Commit unrelated changes separately.**\n",
    "\n",
    "Identifying the source of a bug or understanding the reason why a particular piece of code exists is much easier when commits focus on related changes. Some of this has to do with simplifying commit messages and making it easier to look through logs, but it has other related benefits: commits are smaller and simpler, and merge conflicts are confined to only the commits which actually have conflicting code.\n",
    "\n",
    "**Do not commit binaries and other temporary files.**\n",
    "\n",
    "Git is meant for tracking changes. In nearly all cases, the only meaningful difference between the contents of two binaries is that they are different. If you change source files, compile, and commit the resulting binary, git sees an entirely different file. The end result is that the git repository (which contains a complete history, remember) begins to become bloated with the history of many dissimilar binaries. Worse, there's often little advantage to keeping those files in the history. An argument can be made for periodically snapshotting working binaries, but things like object files, compiled python files, and editor auto-saves are basically wasted space.\n",
    "\n",
    "**Ignore files which should not be committed**\n",
    "\n",
    "Git comes with a built-in mechanism for ignoring certain types of files. Placing filenames or wildcards in a `.gitignore` file placed in the top-level directory (where the `.git` directory is also located) will cause git to ignore those files when checking file status. This is a good way to ensure you don't commit the wrong files accidentally, and it also makes the output of `git status` somewhat cleaner.\n",
    "\n",
    "\n",
    "**Write good commit messages**\n",
    "\n",
    "I cannot understate the importance of this.\n",
    "\n",
    "**Seriously. Write good commit messages.**"
   ]
  }
 ],
 "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.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}