X1-Git.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<center><h1> Version Control with git/Github"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![git](img/git.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-success\">\n",
    "Git is a version control system, used to track changes in files, and coordinate them between people / places.\n",
    "</div>\n",
    "<div class=\"alert alert-info\">\n",
    "Git documentation: https://git-scm.com/doc\n",
    "</div>\n",
    "<hr>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![github](img/github.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-success\">\n",
    "Github is a web based version of Git, and version control repository or internet hosting service. It's a place to put code that is tracked with git. \n",
    "</div>\n",
    "<div class=\"alert alert-info\">\n",
    "Github: https://github.com/ (note that Github, Inc is a company)\n",
    "</div>\n",
    "<hr>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note: this notebook writes out git functions for the command-line, but git has the exact same structure and workflow if you use a GUI, such as SourceTree. The main difference is the GUI will have buttons you can use (with the same labels as the commands) that will run the commands behind the scenes, to do the same things described, making it a little easier for the user. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Local vs. Remote\n",
    "\n",
    "For basic use, what git is mainly doing is keeping two versions of the same repository (folder) consistent. Typically, this is the local copy - a copy of the repository on your computer - and a remote copy - a copy of the repository on Github. Git automatically checks of all the files in each copy of the repository, tracks any changes that happen, and takes note of the differences between the two copies, and provides tools for you to synchronize between them. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Cloning\n",
    "\n",
    "To copy a Github repository to your computer, use the clone command with the URL to the repository.\n",
    "- git clone 'repo_url'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Stages in git - Add, Commit, Push\n",
    "\n",
    "Git has multiple 'levels'. \n",
    "\n",
    "First, in a local git repository, you make some changes to a file, or perhaps many files. You can now add that file to staging. \n",
    "- git add 'f_name'\n",
    "\n",
    "This file is now in the staging area. You can add multiple files to the staging file. To take a snapshot, and save the status of these files, use commit. \n",
    "- git commit -m 'Commit message'\n",
    "\n",
    "^ You should add an informative commit message about what has changed. Commiting often, with detailed messages means that your Github log can serve as a history for your project, keeping track of what you've done. This also allows you  to step back to an older version of the code if everything suddenly breaks.\n",
    "\n",
    "Commiting a change is still only in your local copy. To update the remote repostory, you have to push. \n",
    "- git push\n",
    "\n",
    "^ Git push can push many commits at once. Once you do this, you will see your updates reflected on Github. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Updating the local branch\n",
    "\n",
    "If there are changes on the remote branch, use git pull to update your local copy to match the remote.\n",
    "\n",
    "- git pull"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Git Cheatsheet\n",
    "This is not all the git functions, but includes the main (most common) ones\n",
    "\n",
    "- git status\n",
    "    - Check the status of a git repository\n",
    "- git add 'file'\n",
    "    - Add a file to staging area\n",
    "- git commit -m 'message'\n",
    "    - Log a 'save point' of all changes in the staging area.\n",
    "- git push\n",
    "    - Copy commits to remote\n",
    "- git diff 'file'\n",
    "    - Check what has changed in file since last commit\n",
    "- git clone 'repo'\n",
    "    - Create a local copy of a git repository\n",
    "- git pull\n",
    "    - Update your local copy of a git repository from the remote"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Advanced Git: Branching & Merging\n",
    "\n",
    "Git has many other functionalities, including [branching](https://git-scm.com/book/en/v1/Git-Branching) and [merging](https://git-scm.com/docs/git-merge), that are worth exploring as you get used to using git, and work on larger projects."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## External Resources and Tutorials\n",
    "<br>\n",
    "<div class=\"alert alert-info\">\n",
    "About version control: [Wikipedia](https://en.wikipedia.org/wiki/Version_control) and/or [git docs](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control)\n",
    "</div>\n",
    "<div class=\"alert alert-info\">\n",
    "Github has an interactive tutorial to learn git: https://try.github.io/levels/1/challenges/1\n",
    "</div>\n",
    "<div class=\"alert alert-info\">\n",
    "Github also has a 'Hello World' tutorial for starting with git: https://guides.github.com/activities/hello-world/\n",
    "</div>\n",
    "<div class=\"alert alert-info\">\n",
    "Lifehacker has a fairly in depth introduction and tutorial: http://lifehacker.com/5983680/how-the-heck-do-i-use-github\n",
    "</div>\n",
    "<div class=\"alert alert-info\">\n",
    "Atlassian (who make SourceTree) have a series of tutorials: https://www.atlassian.com/git/tutorials\n",
    "</div>\n",
    "\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "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.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}