{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 4.0 Introduction to version control"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Estimated time to complete this notebook: 10 minutes*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What's version control?\n",
    "\n",
    "Version control is a tool for __managing changes__ to a set of files.\n",
    "\n",
    "There are many different __version control systems__:\n",
    "\n",
    "- Git\n",
    "- Mercurial (`hg`)\n",
    "- CVS\n",
    "- Subversion (`svn`)\n",
    "- ..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Why use version control?\n",
    "\n",
    "- Better kind of __backup__.\n",
    "- Review __history__ (\"When did I introduce this bug?\").\n",
    "- Restore older __code versions__.\n",
    "- Ability to __undo mistakes__.\n",
    "- Maintain __several versions__ of the code at a time."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Git is also a __collaborative__ tool:\n",
    "\n",
    "- \"How can I share my code?\"\n",
    "- \"How can I submit a change to someone else's code?\"\n",
    "- \"How can I merge my work with Sue's?\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Git != GitHub\n",
    "\n",
    "- __Git__: version control system tool to manage source code history.\n",
    "- __GitHub__: hosting service for Git repositories."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How do we use version control?\n",
    "\n",
    "Do some programming, then commit our work:\n",
    "\n",
    "`my_vcs commit`\n",
    "\n",
    "Program some more.\n",
    "\n",
    "Spot a mistake:\n",
    "\n",
    "`my_vcs rollback`\n",
    "\n",
    "Mistake is undone."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## What is version control? (Team version)\n",
    "\n",
    "Sue                | James\n",
    "------------------ |------\n",
    "`my_vcs commit`    | ...\n",
    "...                | Join the team\n",
    "...                | `my_vcs checkout`\n",
    "...                | Do some programming\n",
    "...                | `my_vcs commit`\n",
    "`my_vcs update`    | ...\n",
    "Do some programming|Do some programming\n",
    "`my_vcs commit`    | ...\n",
    "`my_vcs update`    | ...\n",
    "`my_vcs merge`     | ...\n",
    "`my_vcs commit`    | ..."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Scope\n",
    "\n",
    "This course will use the `git` version control system, but much of what you learn will be valid with other version control tools you may encounter, including subversion (`svn`) and mercurial (`hg`)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 4.0.1 Practising with Git"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example Exercise\n",
    "\n",
    "In this course, we will use, as an example, the development of a few text files containing a description of a topic of your choice.\n",
    "\n",
    "This could be your research, a hobby, or something else. In the end, we will show you how to display the content of these files as a very simple website. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Programming and documents\n",
    "\n",
    "The purpose of this exercise is to learn how to use Git to manage program code you write, not simple text website content, but we'll just use these text files instead of code for now, so as not to confuse matters with trying to learn version control while thinking about programming too.\n",
    "\n",
    "In later parts of the course, you will use the version control tools you learn today with actual Python code."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Markdown\n",
    "\n",
    "The text files we create will use a simple \"wiki\" markup style called [markdown](http://daringfireball.net/projects/markdown/basics) to show formatting.\n",
    "This is the convention used in this file, too.\n",
    "\n",
    "You can view the content of this file in the way Markdown renders it by looking on the [web](https://alan-turing-institute.github.io/rse-course/html/module04_version_control_with_git/04_00_introduction.html), and compare the [raw text](https://raw.githubusercontent.com/alan-turing-institute/rse-course/main/module04_version_control_with_git/04_00_introduction.ipynb)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Displaying Text in this Tutorial\n",
    "\n",
    "This tutorial is based on use of the Git command line. So you'll be typing commands in the shell."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To make it easy for me to edit, I've built it using Jupyter notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Commands you can type will look like this, using the %%bash \"magic\" for the notebook.\n",
    "\n",
    "If you are running the notebook on windows you'll have to use %%cmd."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "attributes": {
     "classes": [
      " Bash"
     ],
     "id": ""
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "some output\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "echo some output"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "with the results you should see below. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this document, we will show the new content of an edited document like this:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Overwriting somefile.md\n"
     ]
    }
   ],
   "source": [
    "%%writefile somefile.md\n",
    "Some content here"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "But if you are following along, you should edit the file using a [text editor](https://alan-turing-institute.github.io/rse-course/html/course_prerequisites/03_editor.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setting up somewhere to work"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "attributes": {
     "classes": [
      " Bash"
     ],
     "id": ""
    }
   },
   "outputs": [],
   "source": [
    "%%bash\n",
    "rm -rf learning_git/git_example # Just in case it's left over from a previous class; you won't need this\n",
    "mkdir -p learning_git/git_example\n",
    "cd learning_git/git_example"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "I just need to move this Jupyter notebook's current directory as well:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'/home/turingdev/research-software/rse-course/module04_version_control_with_git'"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import os\n",
    "\n",
    "top_dir = os.getcwd()\n",
    "top_dir"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'/home/turingdev/research-software/rse-course/module04_version_control_with_git/learning_git'"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "git_dir = os.path.join(top_dir, \"learning_git\")\n",
    "git_dir"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "working_dir = os.path.join(git_dir, \"git_example\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "os.chdir(working_dir)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 4.0.2 Solo work\n",
    "\n",
    "## Configuring Git with your name and email\n",
    "\n",
    "First, we should configure Git to know our name and email address:\n",
    "\n",
    "```bash\n",
    "git config --global user.name \"YOUR NAME HERE\"\n",
    "git config --global user.email \"yourname@example.com\"\n",
    "```\n",
    "\n",
    "Note that by using the `--global` flag, we are setting these options for all projects. To set them just for this project, use `--local` instead."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now check that this worked"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "attributes": {
     "classes": [
      " Bash"
     ],
     "id": ""
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Turing Developer\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "git config --get user.name"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "developer@example.com\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "git config --get user.email"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Initialising the repository\n",
    "\n",
    "Now, we will tell Git to track the content of this folder as a git \"repository\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "attributes": {
     "classes": [
      " Bash"
     ],
     "id": ""
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "/home/turingdev/research-software/rse-course/module04_version_control_with_git/learning_git/git_example\n",
      "Initialized empty Git repository in /home/turingdev/research-software/rse-course/module04_version_control_with_git/learning_git/git_example/.git/\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "pwd # Note where we are standing-- MAKE SURE YOU INITIALISE THE RIGHT FOLDER\n",
    "git init --initial-branch=main"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As yet, this repository contains no files:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%bash\n",
    "ls"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "attributes": {
     "classes": [
      " Bash"
     ],
     "id": ""
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "On branch main\n",
      "\n",
      "No commits yet\n",
      "\n",
      "nothing to commit (create/copy files and use \"git add\" to track)\n"
     ]
    }
   ],
   "source": [
    "%%bash\n",
    "git status"
   ]
  }
 ],
 "metadata": {
  "jekyll": {
   "display_name": "Introduction to Version Control"
  },
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.8.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}