git.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Version Control with Git\n",
    "\n",
    "[Git-scm](https://git-scm.com/) (aka git) is a very poweful tool for version control. Git is referred to as the \"stupid content tracker\" because it is so simple and lightweight. It gets its name from a British slang term for a stupid person, a git; and scm stands for source code management. It is very useful if you are developing a large code and want to play around with different ideas without hurting the working version (aka the master branch) of the code. It is ideal for multiple people working on the same code, but I don't use it like that. I only use it for myself, which makes things a little easier. Every time you make a significant change you \"commit\" it and Git will track it. So, if you make a change but later on find out that you want to do something different you can easily revert to a version of the code as it was before you made the change. Or, if you want to play around with a new idea you can create a new \"branch\" which you can do whatever you want to and it won't affect the master branch.\n",
    "\n",
    "I barely scratch the surface of git's potential and still find it incredibly useful. [Here](https://git-scm.com/videos \"Git tutorial\") are four short videos that explain Git (especially the third video, Get Going with Git), and [here](https://git-scm.com/docs/ \"List of Git commands\") is a list of Git commands with links to their own pages. Let's assume that you already have Git installed (if not, click [here](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)), and create our first git project."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Set your user name and email address\n",
    "\n",
    "If you haven't already, type\n",
    "\n",
    "`git config --global user.name \"My Name\"`\n",
    "\n",
    "This sets your username. It is just to track what changes you make. If you are working by yourself this doesn't mean much, but in collaborations it helps. Next enter your email address:\n",
    "\n",
    "`git config --global user.email EmailFemale@gmail.com`\n",
    "\n",
    "This sets your email address. It will appear in the log file (more on that later)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Making your own git project\n",
    "\n",
    "The default name for the base branch of new git repositories is `master`. To change that (for example, to `main`), type this and press enter: `git config --global init.defaultBranch main`\n",
    "\n",
    "Open up a terminal and `cd` to the Desktop. Next, type\n",
    "\n",
    "`git init myFirstGitProject`\n",
    "\n",
    "and press enter. Read about the `git init` command [here](https://git-scm.com/docs/git-init). You should see something like this in the terminal:\n",
    "\n",
    "`Initialized empty Git repository in /Users/sam/Desktop/myFirstGitProject/.git/`\n",
    "\n",
    "If you now `ls` you will see a folder called `myFirstGitProject`. `cd` into it. If you again do `ls` it will appear empty, like any other new folder. But, if you enter `ls -a` (which shows hidden files/folders) you should see a directory called `.git`. If you want to, you can `cd` into it and look around. You shouldn't ever have to be in there though unless something is going wrong."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Adding a file\n",
    "\n",
    "Okay, now that you're in `myFirstGitProject`, type\n",
    "\n",
    "`git status`\n",
    "\n",
    "and press enter. You should see something like this:\n",
    "\n",
    "`On branch main`\n",
    "\n",
    "`Initial commit`\n",
    "\n",
    "`nothing to commit (create/copy files and use \"git add\" to track)`\n",
    "\n",
    "The command `git status` tells you three things: which branch you are working on (in this case, `main`), the most recent commit message you entered (in this case, `Initial commit`), and finally, the status of the files in the current folder (in this case we haven't done anything so it isn't so useful). Read more about `git status` [here](https://git-scm.com/docs/git-status). Next, type\n",
    "\n",
    "`git log`\n",
    "\n",
    "and press enter. You should see something like this:\n",
    "\n",
    "`fatal: your current branch 'main' does not have any commits yet`\n",
    "\n",
    "This makes sense, because we haven't done anything yet. Now we're going to add a file to our project. Type this into your terminal:\n",
    "\n",
    "`nano forLoops.py`\n",
    "\n",
    "Next, type (or copy and paste) the following:\n",
    "\n",
    "```\n",
    "from time import time\n",
    "\n",
    "N = int( 1.0e5 )\n",
    "\n",
    "x = []\n",
    "\n",
    "start = time()\n",
    "\n",
    "for i in range( N ):\n",
    "    x.append(i)\n",
    "\n",
    "print( 'Traditional: {:.16e} seconds'.format(  time() - start ) )\n",
    "```\n",
    "\n",
    "Now, type `ctrl-x`, then press `y` to save, then press enter. Now that the file is saved, type `git status`. This time you should see:\n",
    "\n",
    "`On branch main`\n",
    "\n",
    "`Initial commit`\n",
    "\n",
    "`Untracked files:\n",
    "  (use \"git add <file>...\" to include in what will be committed)`\n",
    "  \n",
    "  \n",
    "<pre>     <font color='red'>forLoops.py</font></pre>\n",
    "\n",
    "`nothing added to commit but untracked files present (use \"git add\" to track)`\n",
    "\n",
    "What this tells you is that you have added a new file and that git does not know about it, aka it, and changes to it, will not be tracked by git's version control. Now we're going to add this file to git's version control. Type:\n",
    "\n",
    "`git add forLoops.py`\n",
    "\n",
    "Now the file has been added to the \"staging area\". This means that it is ready to be committed to version control. Type `git status` again. This time it should read:\n",
    "\n",
    "`On branch main`\n",
    "\n",
    "`Initial commit`\n",
    "\n",
    "`Changes to be committed:\n",
    "  (use \"git rm --cached <file>...\" to unstage)`\n",
    "\n",
    "<pre>    <font color='green'>new file:   forLoops.py</font></pre>\n",
    "\n",
    "This means that the file has been added to the staging area. Note that if you realize **at this point** that if you want to change something before committing, you can type (as the prompt tells you) `git rm --cached forLoops.py`. Now if you type `git status` you will get the same message as before, with the red text. Now you can modify the file, and `add` it again. At this point, type:\n",
    "\n",
    "`git commit -m \"First commit of forLoops.py\"`\n",
    "\n",
    "You should see something like this:\n",
    "\n",
    "`[main (root-commit) 1754e05] First commit of forLoops.py\n",
    " 1 file changed, 13 insertions(+)\n",
    " create mode 100644 forLoops.py`\n",
    "\n",
    "Now, type `git status` again (note the pattern here, basically always type `git status`), you should see\n",
    "\n",
    "`On branch main\n",
    "nothing to commit, working tree clean`\n",
    "\n",
    "This tells you that everything is good in the world. Specifically, git has tracked your change. To see this more clearly, type `git log`, and you should see something like this:\n",
    "\n",
    "`commit 1754e05abf7e36f7f8a6ebcbb79bf3db059641f6\n",
    "Author: Sam Dunham <samueljdunham@gmail.com>\n",
    "Date:   Sun Mar 4 18:26:57 2018 -0600`\n",
    "\n",
    "<pre>First commit of forLoops.py</pre>\n",
    "\n",
    "This is the log. It tracks your changes/commits."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Makes changes to files\n",
    "\n",
    "Now we're going to make some changes. Open the file again with `nano forLoops.py`. Add the following lines to the bottom of the script:\n",
    "\n",
    "```\n",
    "start = time()\n",
    "\n",
    "x = [ i for i in range( N ) ]\n",
    "\n",
    "print 'List Comprehension:' , time() - start, 'seconds'\n",
    "```\n",
    "\n",
    "Also, add seven spaces between the colon and the end quote for the traditional for loop to align the outputs. Save the file by typing `ctrl-x` and then `y` to save the changes. Typing `git status` gives:\n",
    "\n",
    "`On branch main\n",
    "Changes not staged for commit:\n",
    "  (use \"git add <file>...\" to update what will be committed)\n",
    "  (use \"git checkout -- <file>...\" to discard changes in working directory)`\n",
    "\n",
    "<pre>    <font color='red'>modified:   forLoops.py</font></pre>\n",
    "\n",
    "`no changes added to commit (use \"git add\" and/or \"git commit -a\")`\n",
    "\n",
    "The first line tells yo which branch you're on. The second line tells you that there are changes to the file that are not yet tracked by git. The third line tells you how to add the file to git (i.e. put it in the staging area). The fourth line tells you how to return to the original version of the code, before we put in the list comprehension stuff. The fifth line tells you which files were modified. And the last line tells you that the version control hasn't been changed yet (i.e. nothing new has been committed). Let's add this file to the version control by typing\n",
    "\n",
    "`git add forLoops.py`\n",
    "\n",
    "and pressing enter. Now, `git status` gives us:\n",
    "\n",
    "`On branch main\n",
    "Changes to be committed:\n",
    "  (use \"git reset HEAD <file>...\" to unstage)`\n",
    "\n",
    "<pre>    <font color='green'>modified:   forLoops.py</font></pre>\n",
    "\n",
    "Now the third line tells you how \"unstage\" your changes, i.e. \"un-add\" the file. Next, type\n",
    "\n",
    "`git commit -m \"Added list comprehension\"`\n",
    "\n",
    "and press enter. You should see something like this:\n",
    "\n",
    "`[main 49c979f] Added list comprehension\n",
    "1 file changed, 6 insertions(+), 1 deletion(-)`\n",
    "\n",
    "In the square brackets are the branch and commit number you are on. Next is the message you entered. The second line tells you how many files have been modified and what modifications were made (in terms of how many insertions and deletions). Typing `git status` now should tell you that everything is up-to-date (try it!). Next we'll start to see some of the advantages of using git. Type `git log`. You should see something like this:\n",
    "\n",
    "`commit 49c979fb42bfeec21e93edf0fde94b770f3fa808\n",
    "Author: Sam Dunham <samueljdunham@gmail.com>\n",
    "Date:   Mon Mar 5 06:10:26 2018 -0600`\n",
    "\n",
    "<pre> Added list comprehension</pre>\n",
    "\n",
    "`commit 1754e05abf7e36f7f8a6ebcbb79bf3db059641f6\n",
    "Author: Sam Dunham <samueljdunham@gmail.com>\n",
    "Date:   Sun Mar 4 18:26:57 2018 -0600`\n",
    "\n",
    "<pre> First commit of forLoops.py</pre"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Undoing a commit\n",
    "\n",
    "It will happen that you make a commit that you want to undo. The safe way to do that is the following:\n",
    "`git reset --soft HEAD~`,\n",
    "which will undo the most recent commit, but retain all the changes (that what's `--soft` does. Otherwise the changes will be lost). If you need to go further back in the log, you can do `git reset --soft HEAD^<N>`, where `<N>` is the number of commits back you want to go, e.g., `HEAD^1` is the same as `HEAD~`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Making a new branch\n",
    "\n",
    "Now we see two items, our original commit and our latest commit (most recent commit listed first). Now suppose that we want to see the old version of our code. There are a few ways to do this, but my current method is to create a new \"branch\". Think of the git structure like a tree. The \"main branch\" is like the trunk of the tree. Then you can create branches which can be modified, deleted, or whatever without affecting the main branch. To create a branch based off of the old code, copy the commit number of the old commit and type\n",
    "\n",
    "`git checkout -b old-branch 1754e05abf7e36f7f8a6ebcbb79bf3db059641f6`\n",
    "\n",
    "You should see something like this:\n",
    "\n",
    "`Switched to a new branch 'old-branch'`\n",
    "\n",
    "Now, type `git status`, you should see this:\n",
    "\n",
    "`On branch old-branch\n",
    "nothing to commit, working tree clean`\n",
    "\n",
    "Notice that \"main\" has changed to \"old-branch\". This tells us that we are on a different branch than the main branch. Now, type `nano forLoops.py`. You should see that it is the old version of the code, i.e. without the list comprehension stuff. As long as you are in the `old-branch` you can do anything you want to the file, i.e. edit, change, delete, whatever, and the main code will stay safe. Feel free to add a new print statement or something at the end of the file, `add` it, and `commit` it. Type `git status` and `git log` at every step and see how it changes. To switch back to the main branch, type\n",
    "\n",
    "`git checkout main`\n",
    "\n",
    "The terminal should say that you are now on the main branch."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Merging\n",
    "\n",
    "Often you will have at least two branches: a `main` branch and a `development` branch. You may have added a feature on `development` that you want to merge into `main`. This is accomplished with the `merge` command. `merge` can get messy, but in the simple case it's nice. You would `git checkout main`, and then `git merge development`. This will incorporate any changes on `development` into `main`. This works nicely if the code on `main` has not been changed since the creation of `development`. If `main` has been changed, you may get merge conflicts. These are by FAR the most annoying aspect of using git. Let's do an example."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Useful commands\n",
    "\n",
    "There are many other useful commands, such as\n",
    "\n",
    "* `git rm file`: just like `rm`, except git tracks it\n",
    "* `git mv file`: just like `mv`, except git tracks it\n",
    "* `git diff file`: outputs any differences of `file` between the current version and the version git has tracked (the most-recently committed version)\n",
    "* `git diff remoteBranch file` outputs any differences of `file` between the current version on your branch and the version on `remoteBranch`\n",
    "* `git checkout file`: replaces the current version of `file` on your machine with the version git has tracked\n",
    "* `git checkout remoteBranch file`: replaces the version of `file` on your branch with the version of `remoteBranch`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Keep playing!\n",
    "That is about all I know about git. But there are many more very useful utilities. You should explore these and let me know when you find something cool! Next I'll make a Jupyter Notebook about how to use git on a web-based server like Github."
   ]
  }
 ],
 "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.9.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}