version-control.ipynb

{
 "cells": [
  {
   "cell_type": "raw",
   "id": "819a51ba-5fb7-4595-a5f6-40ac6245f3d1",
   "metadata": {},
   "source": [
    "---\n",
    "title: \"Introduction to version control with Git\"\n",
    "author: \"Kyle Niemeyer\"\n",
    "date: \"8 January 2025\"\n",
    "institute: \"Oregon State University\"\n",
    "format:\n",
    "  revealjs:\n",
    "    output-file: version-control-revealjs.html\n",
    "    incremental: true\n",
    "  html: default\n",
    "jupyter: python3\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ea00c26c-3696-4904-b41f-335bf40b984e",
   "metadata": {},
   "source": [
    "# Introduction to version control\n",
    "\n",
    "## Where is version control needed?\n",
    "\n",
    "- Backing up changing files\n",
    "- Storing and accessing an annotated history of changes\n",
    "- Managing the merging of changes between different change sets\n",
    "\n",
    "## Why is this important?\n",
    "\n",
    "[![Image credit: Jorge Cham, PhD Comics](./images/phd-comics-versions.gif){fig-alt=\"Comic on file versions from PhD Comics https://phdcomics.com/comics/archive.php?comicid=1323\"}](http://phdcomics.com/comics/archive.php?comicid=1323)\n",
    "\n",
    "## Saving copies\n",
    "\n",
    "<p class=\"fragment\"><img src=\"./images/code-file.png\" height=\"50\" style=\"vertical-align:middle\"> <code>important_code.py</code></p>\n",
    "\n",
    "<p class=\"fragment\"><img src=\"./images/code-file.png\" height=\"50\" style=\"vertical-align:middle\"> <code>important_code-2.py</code></p>\n",
    "\n",
    "<p class=\"fragment\"><img src=\"./images/code-file.png\" height=\"50\" style=\"vertical-align:middle\"> <code>important_code-fix.py</code></p>\n",
    "\n",
    "<p class=\"fragment\"><img src=\"./images/code-file.png\" height=\"50\" style=\"vertical-align:middle\"> <code>important_code-final.py</code></p>\n",
    "\n",
    "<p class=\"fragment\"><img src=\"./images/code-file.png\" height=\"50\" style=\"vertical-align:middle\"> <code>important_code-final-4Apr.py</code></p>\n",
    "\n",
    "## Git commits \n",
    "\n",
    "<p class=\"fragment current-visible\"><img src=\"./images/code-file.png\" height=\"50\" style=\"vertical-align:middle\"> <code>important_code.py</code></p>\n",
    "\n",
    "<p class=\"fragment current-visible\"><img src=\"./images/code-file.png\" height=\"50\" style=\"vertical-align:middle\"> <code>important_code.py</code></p>\n",
    "\n",
    "<p class=\"fragment current-visible\"><img src=\"./images/code-file.png\" height=\"50\" style=\"vertical-align:middle\"> <code>important_code.py</code></p>\n",
    "\n",
    "<p class=\"fragment current-visible\"><img src=\"./images/code-file.png\" height=\"50\" style=\"vertical-align:middle\"> <code>important_code.py</code></p>\n",
    "\n",
    "<p class=\"fragment\"><img src=\"./images/code-file.png\" height=\"50\" style=\"vertical-align:middle\"> <code>important_code.py</code></p>\n",
    "\n",
    "\n",
    "## Types of version control\n",
    "\n",
    "::: {.fragment}\n",
    "Centralized:\n",
    ":::\n",
    "\n",
    "- Concurrent Version System (cvs)\n",
    "- Subversion (svn)\n",
    "- Perforce (p4)\n",
    "\n",
    "::: {.fragment}\n",
    "Distributed:\n",
    ":::\n",
    "\n",
    "- Decentralized CVS (dcvs)\n",
    "- mercurial (hg)\n",
    "- bazaar (bzr)\n",
    "- **Git (git)**\n",
    "\n",
    "## Git\n",
    "\n",
    "![](./images/giant-swiss-army-knife.jpg){width=60% fig-alt=\"giant Swiss Army knife with far too many tools\"}\n",
    "\n",
    "> Git is a knife whose handle is also a knife. – [Philip Guo](https://ixd.ucsd.edu/home/f16/index.php)\n",
    "\n",
    "---\n",
    "\n",
    "![Image credit: [xkcd](https://xkcd.com/1597/)](./images/xkcd-git.png){width=60% fig-alt=\"If that doesn't fix it, git.txt contains the phone number of a friend of mine who understands git. Just wait through a few minutes of 'It's really pretty simple, just think of branches as...' and eventually you'll learn the commands that will fix everything.\"}\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3ab1efb6-76bb-481d-9cbb-52a8ddcd55ab",
   "metadata": {},
   "source": [
    "# Getting started with Git\n",
    "\n",
    "---\n",
    "\n",
    "## {.center}\n",
    "\n",
    "```bash\n",
    "$ git --help\n",
    "\n",
    "$ git config --global user.name \"Kyle Niemeyer\"\n",
    "$ git config --global user.email \"kyle.niemeyer@oregonstate.edu\"\n",
    "$ git config --global core.editor \"vim\"\n",
    "```\n",
    "\n",
    "## {.center}\n",
    "\n",
    "```bash\n",
    "~ $ mkdir analysis_code\n",
    "~ $ cd analysis_code\n",
    "\n",
    "~/analysis_code $ git init\n",
    "Initialized empty Git repository in ~/analysis_code/.git/\n",
    "```\n",
    "\n",
    "## {.center}\n",
    "\n",
    "```bash\n",
    "~/analysis_code $ ls\n",
    "~/analysis_code $ ls -A\n",
    ".git\n",
    "\n",
    "~/analysis_code $ cd .git && ls -A\n",
    "HEAD    config    description    hooks    index    info    logs\n",
    "```\n",
    "\n",
    "::: {.callout-tip .fragment}\n",
    "Try this yourself.\n",
    ":::\n",
    "\n",
    "## Adding files {.center}\n",
    "\n",
    "```{.bash}\n",
    "~/analysis_code $ touch README.md\n",
    "~/analysis_code $ git add README.md\n",
    "~/analysis_code $ git status\n",
    "```\n",
    "\n",
    "::: {.callout-tip .fragment}\n",
    "Try this yourself.\n",
    ":::\n",
    "\n",
    "## Committing changes\n",
    "\n",
    "::: {.fragment}\n",
    "Snapshot of repository = **revision**\n",
    ":::\n",
    "\n",
    "::: {.fragment}\n",
    "Committing a revision:\n",
    ":::\n",
    "\n",
    "- Saves current state with a unique ID (hash)\n",
    "- Names you as the author\n",
    "- Allows you to add a message\n",
    "\n",
    "```{.bash .fragment}\n",
    "~/analysis_code $ git commit\n",
    "```\n",
    "::: {.callout-tip .fragment}\n",
    "Try this yourself.\n",
    ":::\n",
    "\n",
    "## Options to save time {.center}\n",
    "\n",
    "```{.bash .fragment}\n",
    "~/analysis_code $ git commit -m \"This is my message\"\n",
    "```\n",
    "\n",
    "```{.bash .fragment}\n",
    "~/analysis_code $ git commit -am \"This is my message \n",
    "                  committing all changes\"\n",
    "```\n",
    "\n",
    "## Commit messages {.center}\n",
    "\n",
    "::: {.fragment}\n",
    "Bad commit message:\n",
    ":::\n",
    "\n",
    "```{.text .fragment}\n",
    "Fixed bug\n",
    "```\n",
    "\n",
    "::: {.fragment}\n",
    "Better commit message:\n",
    ":::\n",
    "\n",
    "```{.text .fragment}\n",
    "Fixed bug in mass calculation\n",
    "\n",
    "Due to incorrect density value, mass was being calculated\n",
    "orders of magnitude larger than it should. The correct value\n",
    "of density fixed this problem.\n",
    "```\n",
    "\n",
    "---\n",
    "\n",
    "![Image credit: [xkcd](https://xkcd.com/1296/)](./images/xkcd-git_commit.png){width=50% fig-alt=\"Merge branch 'asdfasjkfdlas/alkdjf' into sdkjfls-final\"}\n",
    "\n",
    "## Viewing history and differences {.center}\n",
    "\n",
    "```{.bash .fragment}\n",
    "~/analysis_code $ git log\n",
    "```\n",
    "\n",
    "```{.bash .fragment}\n",
    "~/analysis_code $ git diff\n",
    "```\n",
    "\n",
    "## Undoing work {.center}\n",
    "\n",
    "::: {.fragment}\n",
    "Un-add a file that has been staged:\n",
    ":::\n",
    "\n",
    "```{.bash .fragment}\n",
    "~/analysis_code $ git restore --staged <filename>\n",
    "```\n",
    "\n",
    "::: {.fragment}\n",
    "Reset all tracked files to previous commit:\n",
    ":::\n",
    "\n",
    "```{.bash .fragment}\n",
    "~/analysis_code $ git reset [mode] [commit]\n",
    "```\n",
    "\n",
    "::: {.fragment}\n",
    "Remove uncommitted changes:\n",
    ":::\n",
    "\n",
    "```{.bash .fragment}\n",
    "~/analysis_code $ git checkout -- <filename>\n",
    "```\n",
    "\n",
    "## Branches\n",
    "\n",
    "```{.bash .fragment}\n",
    "~/analysis_code $ git branch\n",
    "* main\n",
    "\n",
    "~/analysis_code $ git branch experimental\n",
    "~/analysis_code $ git branch\n",
    "  experimental\n",
    "* main\n",
    "\n",
    "~/analysis_code $ git branch new\n",
    "~/analysis_code $ git branch\n",
    "  experimental\n",
    "* main\n",
    "  new\n",
    "\n",
    "~/analysis_code $ git branch -d new\n",
    "~/analysis_code $ git branch\n",
    "  experimental\n",
    "* main\n",
    "\n",
    "~/analysis_code $ git switch experimental\n",
    "~/analysis_code $ git branch\n",
    "* experimental\n",
    "  main\n",
    "```\n",
    "\n",
    "## Merging branches {.center}\n",
    "\n",
    "```{.bash .fragment}\n",
    "~/analysis_code $ git switch main\n",
    "~/analysis_code $ git merge experimental\n",
    "~/analysis_code $ git log\n",
    "```"
   ]
  }
 ],
 "metadata": {
  "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.13.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}