Intro_to_git_and_github.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "8a28a735-1e0a-4174-a755-2896f661bf8a",
   "metadata": {},
   "source": [
    "# Intro to git and GitHub\n",
    "\n",
    "This notebook is meant to provide a brief overview of git and GitHub."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8a7c07bf-b4e2-4f45-a674-c95f55892e1b",
   "metadata": {},
   "source": [
    "## What is git?\n",
    "\n",
    "`Git` is a tool for versioning of files. It is commonly used in programming, but can actually be used to version control any files! \n",
    "\n",
    "What is version control? You may be familiar with the problem of naming and renaming documents when you think you have a final version. E.g. \"final_paper.doc\" but then you find another typo so you save the new one as \"final_paper2.doc\", but then your advisor suggests you add a new paragraph so you have another file named \"FINAL_paper.doc\", and so on. 🙃\n",
    "\n",
    "`Git` (and other version control) allows you to keep the same saved name of your file, but saves the changes that you make. So you can create checkpoints while working on a document such that you cannot lose your progress. This means that `git` can also help with recovery of files! If you commit your file to git and then accidentally delete your whole document, you can revive your document from any of the previous checkpoints you made.\n",
    "\n",
    "Let's see how this works in action. There are a couple of ways to use `git`, but I tend to use it through the terminal. 👉 \n",
    "\n",
    "A couple tips:\n",
    "- in general, do not include data in your git repository\n",
    "   - typically, data is not a good candidate for git. Data can be large and usually don't change much, so it's best to leave data out.\n",
    "- you can use git from any server! You can use it on your local computer or here on the Hub!\n",
    "- \"repo\" (short for \"repository\" is essentially a folder. It is used to indicate a folder that has git enabled, and is also used to mean a specific entity on GitHub.\n",
    "\n",
    "## Installing Git\n",
    "\n",
    "If you use Windows, you will need to download git [here](https://git-scm.com). If you use Linux or Mac, then git is pre-installed."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "de5f0cfe-5507-4c03-a919-eb6cbd920c64",
   "metadata": {},
   "source": [
    "## What is GitHub?\n",
    "\n",
    "GitHub is a website that allows developers to store and share code, as well as many other useful features. It can be used as a backup storage place for your code, or can be used as a collaborative tool. GitHub has a lot of great benefits! \n",
    "\n",
    "Note that a GitHub repo can be public or private. NEVER upload sensitive information (e.g. passwords) to GitHub, as it is publicly accessible!\n",
    "\n",
    "#### `git` vs GitHub\n",
    "- `git` is an open-source versioning tool in your local folder that is not shared with anyone\n",
    "- GitHub is a website that allows you to upload and share your code using git tools\n",
    "\n",
    "Let's take a look at [GitHub](https://github.com) to understand more. 👉 "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "18057ba8-e536-4aa0-a5bf-0b50a6e5b571",
   "metadata": {},
   "source": [
    "## Common vocabulary\n",
    "- `repo`\n",
    "   - short for repository\n",
    "   - a specific entity on GitHub\n",
    "- `local`\n",
    "   - term used to refer to your personal computer (or any repo that is *not* on GitHub)\n",
    "- `fork`\n",
    "   - you can `fork` any public GitHub repo \n",
    "   - this creates a copy of the specified repo stored in your own user account\n",
    "- `origin`\n",
    "   - usually refers to the original repo (e.g. if you run `git clone` then your \"origin\" is the GitHub version of the repo\n",
    "- `upstream`\n",
    "   - if you are working on a software package, then `upstream` is the main, public repo, while you might have \"forked\" a version to your own GitHub account, which would then be your `origin`\n",
    "- `issue`\n",
    "   - this is where you can raise bugs or desired features for a specific repo or package\n",
    "- `pull request`\n",
    "   - this is where you can \"request\" that maintainers of the repo you are in can review a new code addition that you have written\n",
    "\n",
    "## Common `git` commands \n",
    "\n",
    "- `git status`\n",
    "   - tells you the current state of your git repository\n",
    "- `git init`\n",
    "   - intiatlize a git repo in your current folder\n",
    "- `git clone <GitHub-URL-to-repo>`\n",
    "   - copy a repo from GitHub to your local computer\n",
    "- `git add <file-name>`\n",
    "   - add your files to git\n",
    "- `git commit -m \"<message>`\n",
    "   - create a versioning checkpoint for all files that you have added\n",
    "- `git pull <URL-to-origin-or-upstream>`\n",
    "   - term used to copy all content from a specific GitHub repo\n",
    "- `git push`\n",
    "   - term used to send your files that have been committed to a GitHub repo"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ede8a1a7-8daa-408f-af67-a06c033e2c72",
   "metadata": {},
   "source": [
    "## Should I sign up for GitHub?\n",
    "\n",
    "If you would like to write more code or help develop software, then starting a GitHub account is a great idea. However, know that git and GitHub is a bit of a learning curve! Many of using it for years still don't understand how it all works!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9cf652ab-0702-4ffb-9f28-bdb66ca5a3b2",
   "metadata": {},
   "source": [
    "## GitHub as a collaborative tool\n",
    "\n",
    "GitHub has a lot of useful features for working collaboratively! This could be mean working with others, but it also means working with yourself! For instance, if you have a computer at work and at home, you can easily use GitHub to make sure you always have access to your most recent code.\n",
    "\n",
    "More than just storing files and facilitating version control, GitHub has other features that can support a collaborative workflow. This includes:\n",
    "- Issues\n",
    "   - Issues can be used to plan events in addition to flagging code bugs.\n",
    "   - They log all discussion in a linear fashion, and you can tag people, include code, and images.\n",
    "   - They can be closed when done.\n",
    "- Projects\n",
    "   - Project boards can help keep track of which tasks are ongoing and who is working on them. \n",
    "   - These help avoid duplication of work.\n",
    "   \n",
    "## GitHub as a personal website!\n",
    "\n",
    "You can use GitHub to host a free personal website (assuming you don't mind using the GitHub domain name). Below are a couple of resources to help you get started on your own website:\n",
    "- [blog from \"towarddatascience.com\"](https://towardsdatascience.com/how-to-create-a-stunning-personal-portfolio-website-for-free-50ec15b059dd)\n",
    "- [GitHub Pages documentation](https://pages.github.com)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0fa87819-3683-4571-9ee4-dd88562f1b43",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.9.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}