From fd0b94b6b80c0c33dbad03338f5498d1bcd14dd3 Mon Sep 17 00:00:00 2001 From: Geoff Pleiss <824157+gpleiss@users.noreply.github.com> Date: Mon, 2 Sep 2024 11:05:06 -0700 Subject: [PATCH] Include freeze --- .../slides/00-version-control/execute-results/html.json | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/_freeze/schedule/slides/00-version-control/execute-results/html.json b/_freeze/schedule/slides/00-version-control/execute-results/html.json index 12c2e22..8efe355 100644 --- a/_freeze/schedule/slides/00-version-control/execute-results/html.json +++ b/_freeze/schedule/slides/00-version-control/execute-results/html.json @@ -1,9 +1,11 @@ { - "hash": "a6a9261ddb9d0467139893cb9b434552", + "hash": "a703931234f1dd3916ec9d0ffb8ea6a7", "result": { "engine": "knitr", - "markdown": "---\nlecture: \"00 Git, Github, and Slack\"\nformat: revealjs\nmetadata-files: \n - _metadata.yml\n---\n\n\n## {{< meta lecture >}} {.large background-image=\"gfx/smooths.svg\" background-opacity=\"0.3\"}\n\n[Stat 406]{.secondary}\n\n[{{< meta author >}}]{.secondary}\n\nLast modified -- 29 August 2024\n\n\n\n\n\n$$\n\\DeclareMathOperator*{\\argmin}{argmin}\n\\DeclareMathOperator*{\\argmax}{argmax}\n\\DeclareMathOperator*{\\minimize}{minimize}\n\\DeclareMathOperator*{\\maximize}{maximize}\n\\DeclareMathOperator*{\\find}{find}\n\\DeclareMathOperator{\\st}{subject\\,\\,to}\n\\newcommand{\\E}{E}\n\\newcommand{\\Expect}[1]{\\E\\left[ #1 \\right]}\n\\newcommand{\\Var}[1]{\\mathrm{Var}\\left[ #1 \\right]}\n\\newcommand{\\Cov}[2]{\\mathrm{Cov}\\left[#1,\\ #2\\right]}\n\\newcommand{\\given}{\\ \\vert\\ }\n\\newcommand{\\X}{\\mathbf{X}}\n\\newcommand{\\x}{\\mathbf{x}}\n\\newcommand{\\y}{\\mathbf{y}}\n\\newcommand{\\P}{\\mathcal{P}}\n\\newcommand{\\R}{\\mathbb{R}}\n\\newcommand{\\norm}[1]{\\left\\lVert #1 \\right\\rVert}\n\\newcommand{\\snorm}[1]{\\lVert #1 \\rVert}\n\\newcommand{\\tr}[1]{\\mbox{tr}(#1)}\n\\newcommand{\\brt}{\\widehat{\\beta}^R_{s}}\n\\newcommand{\\brl}{\\widehat{\\beta}^R_{\\lambda}}\n\\newcommand{\\bls}{\\widehat{\\beta}_{ols}}\n\\newcommand{\\blt}{\\widehat{\\beta}^L_{s}}\n\\newcommand{\\bll}{\\widehat{\\beta}^L_{\\lambda}}\n\\newcommand{\\U}{\\mathbf{U}}\n\\newcommand{\\D}{\\mathbf{D}}\n\\newcommand{\\V}{\\mathbf{V}}\n$$\n\n\n\n\n\n## Course communication\n\n### Website:\n\n\n\n* Hosted on Github.\n\n* Links to slides and all materials\n\n* Syllabus is there. Be sure to read it.\n\n\n## Course communication\n\n### Slack:\n\n* Link to join on Canvas. This is our discussion board.\n\n* Note that this data is hosted on servers outside of Canada. You may wish to use a pseudonym to protect your privacy.\n\n* Anything super important will be posted to Slack and Canvas. \n\n* Be sure you get Canvas email.\n\n\n## Course communication\n\n### GitHub organization\n\n* Linked from the website.\n\n* This is where you complete / submit assignments / projects / in-class-work\n\n* This is also hosted on Servers outside Canada \n\n\n\n## Why these?\n\n* Yes, some data is hosted on servers in the US.\n\n* But in the real world, no one uses Canvas / Piazza, so why not learn things they do use?\n\n* Much easier to communicate, \"mark\" or comment on your work\n\n* Much more DS friendly\n\n* Note that MDS uses both of these, the Stat and CS departments use both, many faculty use them, Google / Amazon / Meta use things like these, etc.\n\n. . .\n\nSlack help from MDS [features](https://ubc-mds.github.io/resources_pages/slack/) and [rules](https://ubc-mds.github.io/resources_pages/slack_asking_for_help/)\n\n# Git and GitHub\n\n## Why version control?\n\n\n![](http://www.phdcomics.com/comics/archive/phd101212s.gif){fig-align=\"center\"}\n\n\n[Much of this lecture is based on material from Colin Rundel and Karl Broman]{.smallest}\n\n\n## Why version control?\n\n* Simple formal system for tracking all changes to a project\n* Time machine for your projects\n + Track blame and/or praise\n + Remove the fear of breaking things\n* Learning curve is steep, but when you need it you [REALLY]{.secondary} need it\n\n::: {.callout-tip icon=false}\n## When you get really good\n\nVersion control can act as a living lab notebook\n:::\n\n\n## Why Git\n\n::: flex\n::: w-60\n* You could use something like Box or Dropbox\n* Git is much more appropriate\n* It works with large groups\n* It's very fast\n* It's much better at fixing mistakes\n* Tech companies use it (so it's in your interest to have some experience)\n:::\n\n::: w-40\n![](https://imgs.xkcd.com/comics/git.png){fig-align=\"center\"}\n:::\n:::\n\n. . .\n\n::: {.callout-important appearance=\"simple\"}\nThis will hurt, but what doesn't kill you, makes you stronger.\n:::\n\n## Overview\n\n* `git` is a command line program that lives on your machine\n* If you want to track changes in a directory, you type `git init`\n* This creates a (hidden) directory called `.git`\n* The `.git` directory contains a history of all changes made to \"versioned\" files\n* This top directory is referred to as a \"repository\" or \"repo\"\n* is a service that hosts a repo remotely and has other features: issues, project boards, pull requests, renders `.ipynb` & `.md`\n* Some IDEs (pycharm, RStudio, VScode) have built in `git`\n* `git`/GitHub is broad and complicated. Here, just what you [need]{.secondary}\n\n## Aside on \"Built-in\" & \"Command line\" {background-color=\"#97D4E9\"}\n\n:::{.callout-tip}\nFirst things first, RStudio and the Terminal\n:::\n\n\n* Command line is the \"old\" type of computing. You type commands at a prompt and the computer \"does stuff\". \n\n* You may not have seen where this is. RStudio has one built in called \"Terminal\"\n\n* The Mac System version is also called \"Terminal\". If you have a Linux machine, this should all be familiar.\n\n* Windows is not great at this.\n\n* To get the most out of Git, you have to use the command line.\n\n\n## Typical workflow {.smaller}\n\n\n1. Download a repo from Github\n```{{bash}}\ngit clone https://github.com/stat550-2021/lecture-slides.git\n```\n2. Create a **branch**\n```{{bash}}\ngit branch \n```\n3. Make changes to your files.\n4. Add your changes to be tracked (\"stage\" them)\n```{{bash}}\ngit add \n```\n5. Commit your changes\n```{{bash}}\ngit commit -m \"Some explanatory message\"\n```\n\n**Repeat 3--5 as needed. Once you're satisfied**\n\n* Push to GitHub\n```{{bash}}\ngit push\ngit push -u origin \n```\n\n---\n\n![](gfx/git-clone.png){fig-align=\"center\"}\n\n## Commit messages should be meaningful\n![](gfx/late_night_commits.png){fig-align=\"center\" fig-alt=\"Bad commit messages\" height=\"500px\"}\n\nInstead, try \"Update linear model in Question 1.2\"\n\n## What should be tracked?\n\n
\n\nDefinitely\n: code, markdown documentation, tex files, bash scripts/makefiles, ...\n\n
\n\nPossibly\n: jupyter notebooks, images (that won’t change), ...\n\n
\n\nQuestionable\n: processed data, static pdfs, ...\n\n
\n\nDefinitely not\n: full data, continually updated pdfs, other things compiled from source code, logs...\n\n\n## What should be tracked?\n\n
\n\n:::center\n**TLDR**\n\nAny file that [YOU]{.secondary} edit should be tracked \\\nAny file that's [computer generated]{.secondary} should PROBABLY NOT be tracked\n:::\n\n. . .\n\n\nA file called `.gitignore` tells `git` files or types to never track\n\n```{{bash}}\n# History files\n.Rhistory\n.Rapp.history\n\n# Session Data files\n.RData\n\n# User-specific files\n.Ruserdata\n\n# Compiled junk\n*.o\n*.so\n*.DS_Store\n```\n\n## What should be tracked?\n\n
\n\nShortcut to track everything (use carefully):\n\n```{{bash}}\ngit add .\n```\n\n## Rules\n\n### Homework and Labs\n\n* You each have your own repo\n\n* You make a branch\n\n* [DO NOT]{.secondary} rename files\n\n* Make enough commits (3 for labs, 5 for HW).\n\n* Push your changes (at anytime) and make a PR against `main` when done.\n\n* TAs review your work.\n\n* On HW, if you want to revise, make changes in response to feedback and push\nto the same branch. Then \"re-request review\".\n\n\n## What's a PR?\n\n* This exists on GitHub (not git)\n* Demonstration\n\n. . .\n\n![](gfx/pr1.png)\n\n## What's a PR?\n\n* This exists on GitHub (not git)\n* Demonstration\n\n\n![](gfx/pr2.png)\n\n\n## Some things to be aware of\n\n* `master` vs `main`\n* If you think you did something wrong, stop and ask for help\n* There are guardrails in place. But those won't stop a bulldozer.\n* The hardest part is the initial setup. Then, this should all be rinse-and-repeat.\n* This book is great: [Happy Git with R](https://happygitwithr.com)\n 1. See Chapter 6 if you have install problems.\n 1. See Chapter 9 for credential caching (avoid typing a password all the time)\n 1. See Chapter 13 if RStudio can't find `git`\n \n## If you know all this already...\n\n
\n\n:::center\nCheck out my [\"How To Be a Git Wizard\"](https://geoffpleiss.com/git_wizard.pdf) slides to take your git game to the next level. \\\nI guarantee (with 99% confidence) that you will learn an amazing new command.\n:::\n \n\n\n## Protection\n\n* Typical for your PR to trigger tests to make sure you don't break things\n\n* Typical for team members or supervisors to review your PR for compliance\n\n\n## Guardrails\n\n* The `.github` directory contains interactions with GitHub\n\n 1. Actions: On push / PR / other GitHub does something on their server (builds a website, runs tests on code)\n 1. PR templates: Little admonitions when you open a PR\n 1. Branch protection: prevent you from doing stuff\n \n* In this course, we protect `main` so that you can't push there\n\n::: {.callout-warning}\nIf you try to push to `main`, it will give an error like\n```{{bash}}\nremote: error: GH006: Protected branch update failed for refs/heads/main.\n```\n\nThe fix is: make a new branch, then push that.\n:::\n\n---\n\n* I also use a PR template. It gives you some instructions that you should follow\n\n\n::: {.callout-important}\nRead the PR template!!\n:::\n\n## Operations in Rstudio \n\n::: flex\n::: w-50\n\n1. Stage\n1. Commit\n1. Push\n1. Pull\n1. Create a branch\n\n\n\n[Covers:]{.secondary}\n\n* Everything to do your HW / Project if you're careful\n* Plus most other things you \"want to do\"\n\n:::\n\n::: w-50\n\n\nCommand line versions (of the same)\n\n```{{bash}}\ngit add \n\ngit commit -m \"some useful message\"\n\ngit push\n\ngit pull\n\ngit checkout -b \n```\n\n:::\n:::\n\n## Other useful stuff (but command line only)\n\n::: flex\n::: w-50\nInitializing\n```{{bash}}\ngit config user.name --global \"Geoff Pleiss\"\ngit config user.email --global \"geoff.pleiss@stat.ubc.ca\"\ngit config core.editor --global nano \n# or emacs or ... (Geoff loves vim and you should too!)\n```\n\n\nStaging\n```{{bash}}\ngit add name/of/file # stage 1 file\ngit add . # stage all\n```\n\nCommitting\n```{{bash}}\n# stage/commit simultaneously\ngit commit -am \"message\" \n\n# open editor to write long commit message\ngit commit \n```\n\nPushing\n```{{bash}}\n# If branchname doesn't exist\n# on remote, create it and push\ngit push -u origin branchname\n```\n:::\n\n::: w-50\nBranching\n```{{bash}}\n# switch to branchname, error if uncommitted changes\ngit checkout branchname \n# switch to a previous commit\ngit checkout aec356\n\n# create a new branch\ngit branch newbranchname\n# create a new branch and check it out\ngit checkout -b newbranchname\n\n# merge changes in branch2 onto branch1\ngit checkout branch1\ngit merge branch2\n\n# grab a file from branch2 and put it on current\ngit checkout branch2 -- name/of/file\n\ngit branch -v # list all branches\n```\n\nCheck the status\n```{{bash}}\ngit status\ngit remote -v # list remotes\ngit log # show recent commits, msgs\n```\n:::\n:::\n\n## Conflicts\n\n* Sometimes you merge things and \"conflicts\" happen.\n\n* Meaning that changes on one branch would overwrite changes on a different branch.\n\n::: flex\n::: w-50\n\n* They look like this:\n\n```\nHere are lines that are either unchanged from\nthe common ancestor, or cleanly resolved \nbecause only one side changed.\n\nBut below we have some troubles\n<<<<<<< yours:sample.txt\nConflict resolution is hard;\nlet's go shopping.\n=======\nGit makes conflict resolution easy.\n>>>>>>> theirs:sample.txt\n\nAnd here is another line that is cleanly \nresolved or unmodified.\n```\n\n:::\n\n::: w-50\n\nYou get to decide, do you want to keep\n\n1. Your changes (above `======`)\n2. Their changes (below `======`)\n3. Both.\n4. Neither.\n\nBut always delete the `<<<<<`, `======`, and `>>>>>` lines.\n\nOnce you're satisfied, committing resolves the conflict.\n\n:::\n:::\n\n## Some other pointers\n\n* Commits have long names: `32b252c854c45d2f8dfda1076078eae8d5d7c81f`\n * If you want to use it, you need \"enough to be unique\": `32b25`\n\n* Online help uses directed graphs in ways different from statistics:\n * In stats, arrows point from cause to effect, forward in time\n * In `git` docs, it's reversed, they point to the thing on which they depend\n \n \n### Cheat sheet\n\n\n\n\n## How to undo in 3 scenarios\n\n* Suppose we're concerned about a file named `README.md`\n* Often, `git status` will give some of these as suggestions\n\n::: flex\n::: w-50\n\n[1. Saved but not staged]{.secondary}\n\n* In RStudio, select the file and click ``{=html} ``{=html} then select ``{=html} Revert...\n```{{bash}}\n# grab the previously committed version\ngit checkout -- README.md \n```\n\n[2. Staged but not committed]{.secondary}\n\n* In RStudio, uncheck the box by the file, then use the method above.\n```{{bash}}\n# unstage\ngit reset HEAD README.md\ngit checkout -- README.md\n```\n:::\n\n::: w-50\n\n[3. Committed]{.secondary}\n\n* Not easy to do in RStudio...\n```{{bash}}\n# check the log to see where you made the chg, \ngit log\n# go one step before that (eg to 32b252)\n# and grab that earlier version\ngit checkout 32b252 -- README.md\n```\n\n
\n\n```{{bash}}\n# alternatively\n# if it happens to also be on another branch\ngit checkout otherbranch -- README.md\n```\n:::\n:::\n\n## Recovering from things\n\n1. Accidentally did work on main, Tried to Push but got refused\n```{{bash}}\n# make a new branch with everything, but stay on main\ngit branch newbranch\n# find out where to go to\ngit log\n# undo everything after ace2193\ngit reset --hard ace2193\ngit checkout newbranch\n```\n\n2. Made a branch, did lots of work, realized it's trash, and you want to burn it\n```{{bash}}\ngit checkout main\ngit branch -d badbranch\n```\n\n3. Anything more complicated, either post to Slack or LMGTFY\n\n\n\n4. In the Lab next week, you'll practice \n * Doing it right.\n * Recovering from some mistakes.\n \n\n# Example of setting up labs\n\n::: {.notes}\n* Cloning your repo.\n\n* Creating a branch.\n\n* Knitting the Rmd.\n\n* Where to put answers.\n:::\n\n", - "supporting": [], + "markdown": "---\nlecture: \"00 Git, Github, and Slack\"\nformat: revealjs\nmetadata-files: \n - _metadata.yml\n---\n\n\n\n## {{< meta lecture >}} {.large background-image=\"gfx/smooths.svg\" background-opacity=\"0.3\"}\n\n[Stat 406]{.secondary}\n\n[{{< meta author >}}]{.secondary}\n\nLast modified -- 02 September 2024\n\n\n\n\n\n\n\n$$\n\\DeclareMathOperator*{\\argmin}{argmin}\n\\DeclareMathOperator*{\\argmax}{argmax}\n\\DeclareMathOperator*{\\minimize}{minimize}\n\\DeclareMathOperator*{\\maximize}{maximize}\n\\DeclareMathOperator*{\\find}{find}\n\\DeclareMathOperator{\\st}{subject\\,\\,to}\n\\newcommand{\\E}{E}\n\\newcommand{\\Expect}[1]{\\E\\left[ #1 \\right]}\n\\newcommand{\\Var}[1]{\\mathrm{Var}\\left[ #1 \\right]}\n\\newcommand{\\Cov}[2]{\\mathrm{Cov}\\left[#1,\\ #2\\right]}\n\\newcommand{\\given}{\\ \\vert\\ }\n\\newcommand{\\X}{\\mathbf{X}}\n\\newcommand{\\x}{\\mathbf{x}}\n\\newcommand{\\y}{\\mathbf{y}}\n\\newcommand{\\P}{\\mathcal{P}}\n\\newcommand{\\R}{\\mathbb{R}}\n\\newcommand{\\norm}[1]{\\left\\lVert #1 \\right\\rVert}\n\\newcommand{\\snorm}[1]{\\lVert #1 \\rVert}\n\\newcommand{\\tr}[1]{\\mbox{tr}(#1)}\n\\newcommand{\\brt}{\\widehat{\\beta}^R_{s}}\n\\newcommand{\\brl}{\\widehat{\\beta}^R_{\\lambda}}\n\\newcommand{\\bls}{\\widehat{\\beta}_{ols}}\n\\newcommand{\\blt}{\\widehat{\\beta}^L_{s}}\n\\newcommand{\\bll}{\\widehat{\\beta}^L_{\\lambda}}\n\\newcommand{\\U}{\\mathbf{U}}\n\\newcommand{\\D}{\\mathbf{D}}\n\\newcommand{\\V}{\\mathbf{V}}\n$$\n\n\n\n\n\n## Course communication\n\n### Website:\n\n\n\n* Hosted on Github.\n\n* Links to slides and all materials\n\n* Syllabus is there. Be sure to read it.\n\n\n## Course communication\n\n### Slack:\n\n* Link to join on Canvas. This is our discussion board.\n\n* Note that this data is hosted on servers outside of Canada. You may wish to use a pseudonym to protect your privacy.\n\n* Anything super important will be posted to Slack and Canvas. \n\n* Be sure you get Canvas email.\n\n\n## Course communication\n\n### GitHub organization\n\n* Linked from the website.\n\n* This is where you complete / submit assignments / projects / in-class-work\n\n* This is also hosted on Servers outside Canada \n\n\n\n## Why these?\n\n* Yes, some data is hosted on servers in the US.\n\n* But in the real world, no one uses Canvas / Piazza, so why not learn things they do use?\n\n* Much easier to communicate, \"mark\" or comment on your work\n\n* Much more DS friendly\n\n* Note that MDS uses both of these, the Stat and CS departments use both, many faculty use them, Google / Amazon / Meta use things like these, etc.\n\n. . .\n\nSlack help from MDS [features](https://ubc-mds.github.io/resources_pages/slack/) and [rules](https://ubc-mds.github.io/resources_pages/slack_asking_for_help/)\n\n# Git and GitHub\n\n------\n\n*But I already know how to use git/Github...*\n\nAre you sure?\n\n* Have you used git/Github in a professional team context?\n* Do you follow a proper pull request workflow?\n* Do you know what files to track and not to track?\n* Can you get yourself unstuck from common problems?\n\n. . .\n\n
\n\n*Yes. I really know how to use git/Github.*\n\nThen pull out your laptop and read my [\"How To Be a Git Wizard\"](https://geoffpleiss.com/git_wizard.pdf) slides. \\\nI guarantee (with 99% confidence) that you will learn a new command.\n\n## Why version control?\n\n\n![](http://www.phdcomics.com/comics/archive/phd101212s.gif){fig-align=\"center\"}\n\n\n[Much of this lecture is based on material from Colin Rundel and Karl Broman]{.smallest}\n\n\n## Why version control?\n\n* Simple formal system for tracking all changes to a project\n* Time machine for your projects\n + Track blame and/or praise\n + Remove the fear of breaking things\n* Learning curve is steep, but when you need it you [REALLY]{.secondary} need it\n\n::: {.callout-tip icon=false}\n## When you get really good\n\nVersion control can act as a living lab notebook\n:::\n\n\n## Why Git\n\n::: flex\n::: w-60\n* You could use something like Box or Dropbox\n* Git is much more appropriate\n* It works with large groups\n* It's very fast\n* It's much better at fixing mistakes\n* Tech companies use it (so it's in your interest to have some experience)\n:::\n\n::: w-40\n![](https://imgs.xkcd.com/comics/git.png){fig-align=\"center\"}\n:::\n:::\n\n. . .\n\n::: {.callout-important appearance=\"simple\"}\nThis will hurt, but what doesn't kill you, makes you stronger.\n:::\n\n## Overview\n\n* `git` is a command line program that lives on your machine\n* If you want to track changes in a directory, you type `git init`\n* This creates a (hidden) directory called `.git`\n* The `.git` directory contains a history of all changes made to \"versioned\" files\n* This top directory is referred to as a \"repository\" or \"repo\"\n* is a service that hosts a repo remotely and has other features: issues, project boards, pull requests, renders `.ipynb` & `.md`\n* Some IDEs (pycharm, RStudio, VScode) have built in `git`\n* `git`/GitHub is broad and complicated. Here, just what you [need]{.secondary}\n\n## Aside on \"Built-in\" & \"Command line\" {background-color=\"#97D4E9\"}\n\n:::{.callout-tip}\nFirst things first, RStudio and the Terminal\n:::\n\n\n* Command line is the \"old\" type of computing. You type commands at a prompt and the computer \"does stuff\". \n\n* You may not have seen where this is. RStudio has one built in called \"Terminal\"\n\n* The Mac System version is also called \"Terminal\". If you have a Linux machine, this should all be familiar.\n\n* Windows is not great at this.\n\n* To get the most out of Git, you have to use the command line.\n\n\n## Typical workflow {.smaller}\n\n\n1. Download a repo from Github\n```{{bash}}\ngit clone https://github.com/stat550-2021/lecture-slides.git\n```\n2. Create a **branch**\n```{{bash}}\ngit branch \n```\n3. Make changes to your files.\n4. Add your changes to be tracked (\"stage\" them)\n```{{bash}}\ngit add \n```\n5. Commit your changes\n```{{bash}}\ngit commit -m \"Some explanatory message\"\n```\n\n**Repeat 3--5 as needed. Once you're satisfied**\n\n* Push to GitHub\n```{{bash}}\ngit push\ngit push -u origin \n```\n\n---\n\n![](gfx/git-clone.png){fig-align=\"center\"}\n\n## Commit messages should be meaningful\n![](gfx/late_night_commits.png){fig-align=\"center\" fig-alt=\"Bad commit messages\" height=\"500px\"}\n\nInstead, try \"Update linear model in Question 1.2\"\n\n## What should be tracked?\n\n
\n\nDefinitely\n: code, markdown documentation, tex files, bash scripts/makefiles, ...\n\n
\n\nPossibly\n: jupyter notebooks, images (that won’t change), ...\n\n
\n\nQuestionable\n: processed data, static pdfs, ...\n\n
\n\nDefinitely not\n: full data, continually updated pdfs, other things compiled from source code, logs...\n\n\n## What should be tracked?\n\n
\n\n:::center\n**TLDR**\n\nAny file that [YOU]{.secondary} edit should be tracked \\\nAny file that's [computer generated]{.secondary} should PROBABLY NOT be tracked\n\n[However, in this course you will track rendered PDFs of your homeworks/labs.\n This makes it easier for the graders.]{.small}\n:::\n\n\n\n## What should be tracked?\n\nA file called `.gitignore` tells `git` files or types to never track\n\n```{{bash}}\n# History files\n.Rhistory\n.Rapp.history\n\n# Session Data files\n.RData\n\n# User-specific files\n.Ruserdata\n\n# Compiled junk\n*.o\n*.so\n*.DS_Store\n```\n\nShortcut to track everything (use carefully):\n\n```{{bash}}\ngit add .\n```\n\n## Rules\n\n### Homework and Labs\n\n* You each have your own repo\n\n* You make a branch\n\n* [DO NOT]{.secondary} rename files\n\n* Make enough commits (3 for labs, 5 for HW).\n\n* Push your changes (at anytime) and make a PR against `main` when done.\n\n* TAs review your work.\n\n* On HW, if you want to revise, make changes in response to feedback and push\nto the same branch. Then \"re-request review\".\n\n\n## What's a PR?\n\n* This exists on GitHub (not git)\n* Demonstration\n\n. . .\n\n![](gfx/pr1.png)\n\n## What's a PR?\n\n* This exists on GitHub (not git)\n* Demonstration\n\n\n![](gfx/pr2.png)\n\n\n## Some things to be aware of\n\n* `master` vs `main`\n* If you think you did something wrong, stop and ask for help\n* There are guardrails in place. But those won't stop a bulldozer.\n* The hardest part is the initial setup. Then, this should all be rinse-and-repeat.\n* This book is great: [Happy Git with R](https://happygitwithr.com)\n 1. See Chapter 6 if you have install problems.\n 1. See Chapter 9 for credential caching (avoid typing a password all the time)\n 1. See Chapter 13 if RStudio can't find `git`\n \n\n\n## Protection\n\n* Typical for your PR to trigger tests to make sure you don't break things\n\n* Typical for team members or supervisors to review your PR for compliance\n\n\n## Guardrails\n\n* The `.github` directory contains interactions with GitHub\n\n 1. Actions: On push / PR / other GitHub does something on their server (builds a website, runs tests on code)\n 1. PR templates: Little admonitions when you open a PR\n 1. Branch protection: prevent you from doing stuff\n\n\n## Guardrails\n\n* Real-world repos often protect `main` so that you can't push there\n\n::: {.callout-warning}\nYou'd see an error like this:\n```{{bash}}\nremote: error: GH006: Protected branch update failed for refs/heads/main.\n```\n\nThe fix is: make a new branch, then push that.\n:::\n\n. . .\n\n* Unfortunately, we can't set up those protections for this course.\n Github recently put these protections behind a paywall :(\n \n* So now it's your responsibility. Please don't push to `main`!\n\n## Guardrails\n\n:::flex\n:::w-40\n* We have a PR template on the homework and lab repos. It gives you some instructions that you should follow\n\n\n::: {.callout-important}\nRead the PR template!!\n:::\n:::\n\n:::w-60\n![](gfx/pr_template.png){fig-align=\"center\" fig-alt=\"PR Template\"}\n:::\n:::\n\n## Operations in Rstudio \n\n::: flex\n::: w-50\n\n1. Stage\n1. Commit\n1. Push\n1. Pull\n1. Create a branch\n\n\n\n[Covers:]{.secondary}\n\n* Everything to do your HW / Project if you're careful\n* Plus most other things you \"want to do\"\n\n:::\n\n::: w-50\n\n\nCommand line versions (of the same)\n\n```{{bash}}\ngit add \n\ngit commit -m \"some useful message\"\n\ngit push\n\ngit pull\n\ngit checkout -b \n```\n\n:::\n:::\n\n## Other useful stuff (but command line only)\n\n::: flex\n::: w-50\nInitializing\n```{{bash}}\ngit config user.name --global \"Geoff Pleiss\"\ngit config user.email --global \"geoff.pleiss@stat.ubc.ca\"\ngit config core.editor --global nano \n# or emacs or ... (Geoff loves vim and you should too!)\n```\n\n\nStaging\n```{{bash}}\ngit add name/of/file # stage 1 file\ngit add . # stage all\n```\n\nCommitting\n```{{bash}}\n# stage/commit simultaneously\ngit commit -am \"message\" \n\n# open editor to write long commit message\ngit commit \n```\n\nPushing\n```{{bash}}\n# If branchname doesn't exist\n# on remote, create it and push\ngit push -u origin branchname\n```\n:::\n\n::: w-50\nBranching\n```{{bash}}\n# switch to branchname, error if uncommitted changes\ngit checkout branchname \n# switch to a previous commit\ngit checkout aec356\n\n# create a new branch\ngit branch newbranchname\n# create a new branch and check it out\ngit checkout -b newbranchname\n\n# merge changes in branch2 onto branch1\ngit checkout branch1\ngit merge branch2\n\n# grab a file from branch2 and put it on current\ngit checkout branch2 -- name/of/file\n\ngit branch -v # list all branches\n```\n\nCheck the status\n```{{bash}}\ngit status\ngit remote -v # list remotes\ngit log # show recent commits, msgs\n```\n:::\n:::\n\n## Conflicts\n\n* Sometimes you merge things and \"conflicts\" happen.\n\n* Meaning that changes on one branch would overwrite changes on a different branch.\n\n::: flex\n::: w-50\n\n* They look like this:\n\n```\nHere are lines that are either unchanged from\nthe common ancestor, or cleanly resolved \nbecause only one side changed.\n\nBut below we have some troubles\n<<<<<<< yours:sample.txt\nConflict resolution is hard;\nlet's go shopping.\n=======\nGit makes conflict resolution easy.\n>>>>>>> theirs:sample.txt\n\nAnd here is another line that is cleanly \nresolved or unmodified.\n```\n\n:::\n\n::: w-50\n\nYou get to decide, do you want to keep\n\n1. Your changes (above `======`)\n2. Their changes (below `======`)\n3. Both.\n4. Neither.\n\nBut always delete the `<<<<<`, `======`, and `>>>>>` lines.\n\nOnce you're satisfied, committing resolves the conflict.\n\n:::\n:::\n\n## Some other pointers\n\n* Commits have long names: `32b252c854c45d2f8dfda1076078eae8d5d7c81f`\n * If you want to use it, you need \"enough to be unique\": `32b25`\n\n* Online help uses directed graphs in ways different from statistics:\n * In stats, arrows point from cause to effect, forward in time\n * In `git` docs, it's reversed, they point to the thing on which they depend\n \n \n### Cheat sheet\n\n\n\n\n## How to undo in 3 scenarios\n\n* Suppose we're concerned about a file named `README.md`\n* Often, `git status` will give some of these as suggestions\n\n::: flex\n::: w-50\n\n[1. Saved but not staged]{.secondary}\n\n* In RStudio, select the file and click ``{=html} ``{=html} then select ``{=html} Revert...\n```{{bash}}\n# grab the previously committed version\ngit checkout -- README.md \n```\n\n[2. Staged but not committed]{.secondary}\n\n* In RStudio, uncheck the box by the file, then use the method above.\n```{{bash}}\n# unstage\ngit reset HEAD README.md\ngit checkout -- README.md\n```\n:::\n\n::: w-50\n\n[3. Committed]{.secondary}\n\n* Not easy to do in RStudio...\n```{{bash}}\n# check the log to see where you made the chg, \ngit log\n# go one step before that (eg to 32b252)\n# and grab that earlier version\ngit checkout 32b252 -- README.md\n```\n\n
\n\n```{{bash}}\n# alternatively\n# if it happens to also be on another branch\ngit checkout otherbranch -- README.md\n```\n:::\n:::\n\n## Recovering from things\n\n1. Accidentally did work on main (locally), but didn't push to Github\n```{{bash}}\ngit branch newbranch # make a new branch with everything, but stay on main\ngit fetch && git reset --hard origin/main # undo everything up to the last commit on Github's main branch\ngit checkout newbranch # switch to new branch\n```\n\n2. Accidentally did work on main (locally), and pushed to Github\\\n[(PLEASE PLEASE PLEASE don't do this, but if you do...)]{.small}\n```{{bash}}\ngit branch newbranch # make a new branch with everything, but stay on main\n# NOTE: we can't use reset, because the commits are already published!\n# You can't delete commits from Github once they've been pushed.\n# We instead have to create and push a series of \"reverse\" commits\n# that undo the commits we pushed, and then push those undo commits\ngit fetch && git revert origin/main..HEAD # note the different command here!\ngit push origin main\n# Now we can go to the new branch (without the undo commits)\ngit checkout newbranch # Switch to new branch\n```\n\n## Recovering from things\n\n3. Made a branch, did lots of work, realized it's trash, and you want to burn it\n```{{bash}}\ngit checkout main\ngit branch -D badbranch\n```\n\n4. Anything more complicated, post to Slack or come to office hours\n\n5. In the Lab next week, you'll practice \n * Doing it right.\n * Recovering from some mistakes.\n \n\n# Example of setting up labs\n\n::: {.notes}\n* Cloning your repo.\n\n* Creating a branch.\n\n* Knitting the Rmd.\n\n* Where to put answers.\n:::\n\n", + "supporting": [ + "00-version-control_files" + ], "filters": [ "rmarkdown/pagebreak.lua" ],