lecture_01_git.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div style=\"text-align: center\">\n",
    "    <div style=\"font-size: xxx-large ; font-weight: 900 ; color: rgba(0 , 0 , 0 , 0.8) ; line-height: 100%\">\n",
    "        Git\n",
    "    </div>\n",
    "    <div style=\"font-size: x-large ; padding-top: 20px ; color: rgba(0 , 0 , 0 , 0.5)\">\n",
    "        Git + GitHub\n",
    "    </div>\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Version Control with Git & GitHub\n",
    "\n",
    "![](images/git_motivation.jpg)\n",
    "\n",
    "## What is version control?\n",
    "* A system that keeps records of your changes\n",
    "* Allows for collaborative development\n",
    "* Allows you to know who made what changes and when\n",
    "* Allows comparing changes over time\n",
    "* **Allows you to revert any changes and go back to a previous state in case of mistakes**\n",
    "* **If combined with an online storage, it is a back-up of all your code**\n",
    "\n",
    "## What is Git?\n",
    "* Git is a command line tool to track and save changes of files within a directory\n",
    "* Git is a version control protocol that implements the features mentioned above\n",
    "* Git is free and can be used without the need of a cloud storage provider or user account somewhere\n",
    "* Note: There are also many graphical tools available\n",
    "\n",
    "## How do I install it?\n",
    "\n",
    "If you have followed the instructions in the   [Setup](setup.ipynb) you should have already setup your terminal in either Windows or Linux.\n",
    "\n",
    "* If you have chosen Linux, you may have to run `sudo apt install git-all` in a terminal.\n",
    "* If you have chosen Windows, Git should already be installed.\n",
    "\n",
    "When you now enter `git` in your terminal and press `Enter` you should see something similar to:\n",
    "![](images/git-cmd.png)\n",
    "\n",
    "## What is GitHub?\n",
    "* GitHub is a cloud service offered by the inventors of Git\n",
    "* Local Code/Repositories can be uploaded to GitHub and shared with others\n",
    "* [GitHub.com](https://www.github.com) offers additional functionality on their webpage\n",
    "* You have to create a user on GitHub.com in order to upload repositories to GitHub. You DO NOT need an account to access and download public repositories!\n",
    "* GitHub.com is free of charge but more storage and other additional features require a paid subscription\n",
    "* Remember not to confuse Git with GitHub!\n",
    "    * Git is tool to track changes\n",
    "    * GitHub is a cloud storage provider for Git projects\n",
    "* Note: Several project left Github in 2019 (e.g. ObsPy and Pyrocko) in order to protest against the newly implemented geographical barrier: https://www.techspot.com/news/81187-github-confirms-has-blocked-developers-iran-syria-cuba.html\n",
    "* Other cloud services are available too. \n",
    "\n",
    "## Git and GitHub\n",
    "\n",
    "![](images/01_git_and_github.png)\n",
    "\n",
    "## Snapshots / Commits\n",
    "* The way git keeps track of your code history\n",
    "* Essentially records what all your files look like at a given point in time\n",
    "* You decide when to take a snapshot, and of what files\n",
    "* All your old snapshots will stay around\n",
    "* You have the ability to go back to any snapshot at any time\n",
    "\n",
    "## Repository\n",
    "* Collection of all files and the history of those files\n",
    "  * All your commits\n",
    "* Stored on your local machine or on a remote server (e.g. GitHub, GitLab, ...)\n",
    "* The act of copying a repository from a remote server to your local machine is called **cloning**\n",
    "* Cloning from a remote server allows teams to work together\n",
    "* The process of downloading commits that don’t exist on your machine from a remote repository is called **pulling**\n",
    "* The process of uploading your local changes to the remote/cloud repository is called **pushing**\n",
    "* **Remote Repository** is stored online, e.g. on GitHub\n",
    "* **Local Repository** is stored on your machine\n",
    "\n",
    "## Working on an existing GitHub project\n",
    "\n",
    "**Download code from an online git repository (only once)**\n",
    "```bash\n",
    "git clone <url>\n",
    "```\n",
    "\n",
    "<img src=\"images/01_git_workflow.png\" align=\"center\">\n",
    "\n",
    "**0. Update Local Repository with changes from the Remote Repository**\n",
    "```bash\n",
    "git pull\n",
    "```\n",
    "\n",
    "**1. Edit your files** -> Files are now in the **<span style=\"color: #f54d27\">Working Directory</span>**\n",
    "\n",
    "**2. Track changes in a single file** -> File is now in the **<span style=\"color: #cd9f00\">Staging Area</span>**\n",
    "```bash\n",
    "git add <my_file>\n",
    "```\n",
    "\n",
    "**2. Track changes in multiple files** -> Files are now in the **<span style=\"color: #cd9f00\">Staging Area</span>**\n",
    "```bash\n",
    "git add <my_file> <my_file_2>\n",
    "```\n",
    "\n",
    "**2. Track changes in all files in a directory** -> Files are now in the **<span style=\"color: #cd9f00\">Staging Area</span>**\n",
    "```bash\n",
    "git add .\n",
    "```\n",
    "\n",
    "**3. Create a commit/snapshot of your currently tracked/added files** -> All tracked files are now in the **<span style=\"color: #00909a\">Local Repository</span>**\n",
    "```bash\n",
    "git commit -m \"<This should describe very briefly what I did>\"\n",
    "```\n",
    "\n",
    "**4. Save your commits in the cloud so they don't get lost**\n",
    "\n",
    "Note: You can only push to a Remote Repositories if you have permission to do so.\n",
    "\n",
    "```bash\n",
    "git push\n",
    "```\n",
    "\n",
    "**5. Check out the project page on GitHub**\n",
    "\n",
    "![](images/01_existing_github_project.png)\n",
    "\n",
    "## Working on a new GitHub project\n",
    "1. Create directory on your file system: `mkdir Hekla`\n",
    "2. Navigate to the directory and initialize git file tracking `cd Hekla`   `git init`\n",
    "3. Create new files/directories in your working directory\n",
    "4. Do the steps 2-3 as in “Working on an existing GitHub project”\n",
    "5. Create a repository (public/private) on github at https://github.com/new\n",
    "6. Follow the steps on github at `...or push an existing repository from the command line`\n",
    "\n",
    "## When to Commit?\n",
    "\n",
    "- Don't accumulate lots of changes. Better to commit after few changes, i.e. a day of work.\n",
    "- Commit even if the version is still not working?\n",
    "  - Yes, but don't push it so that you don't break it for other people working on it.\n",
    "- If working on a project with more people don't push your local commit without testing the code and be sure that there are no critical bugs.\n",
    "\n",
    "## Possible Problems When Pulling or Pushing\n",
    "\n",
    "- If you are working with more people is common that you will fail to push your commits or pull due to “merge conflicts\". \n",
    "- This happens when a file you modified has also been changed by someone else in the project after your last synchronization (Pull). \n",
    "- In some cases, Git can't decide which version to keep and will ask you to solve the conflict. \n",
    "- There are multiple ways to solve it:\n",
    "    - Keep your local version of the file\n",
    "    - Keep the remote version of the file\n",
    "    - Manually resolve merge conflicts by editing the conflicts marked by <<< >>>\n",
    "\n",
    "## set up ssh keygen to clone data from github\n",
    "- in terminal type “ssh-keygen”, enter return\n",
    "- passphrase has to be set to use the key\n",
    "- dir .ssh, return contains new files: \"id_rsa\" and \"id_rsa.pub\" \n",
    "- type .ssh\\id_rsa.pub \n",
    "- copy public key in \"add new ssh key\" on github \n",
    "- now you can use in the terminal \"git clone git@github.com://foldername\"\n",
    "- insert passphrase locally to decipher the key once \n",
    "- a copy of the github folder should now have appeared on you local laptop"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Summary\n",
    "\n",
    "* You know what **version control** is.\n",
    "* You know the difference between **Git** and **GitHub**.\n",
    "* You know what a **repository** is.\n",
    "* You know what a **commit** is.\n",
    "* You know the basic workflow with a version control system: **clone**, **commit**, **push**."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Next lecture: [Python - The Basic Basics](lecture_02_python_intro.ipynb)"
   ]
  }
 ],
 "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.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}