diff --git a/schedule/handouts/lab00-git.qmd b/schedule/handouts/lab00-git.qmd index 043b285..4525c59 100644 --- a/schedule/handouts/lab00-git.qmd +++ b/schedule/handouts/lab00-git.qmd @@ -1,93 +1,61 @@ --- title: "Lab 00 Git" -date: "Last updated - 8 September 2023" +date: "September 5, 2024" --- # Prework -1. Check your -[Canvas profile settings](https://community.canvaslms.com/t5/Student-Guide/How-do-I-add-contact-methods-to-receive-Canvas-notifications-as/ta-p/516) -to ensure the email associated with your Canvas account is correct. -1. Review your -[Canvas notification settings](https://community.canvaslms.com/t5/Student-Guide/How-do-I-set-my-Canvas-notification-preferences-as-a-student/ta-p/434) -and decide what you want to be notified about. -1. Visit the [Course website](/index.qmd). In -particular, as you might expect, this course requires computing. We will use R -and RStudio as well as Git and GitHub. See the -[Computing](/computing/) tab. -1. If you have never used GitHub before, go to create an -account. You should be aware that this data is stored on US servers. Please -exercise caution whenever using personal information. You may wish to use a -pseudonym to protect your privacy if you have concerns. - -If you haven't already, visit [Computing](/computing/) -and follow the instructions to set up your computer. - -* Clone your `labs-` repo. - 1. Navigate to the Course GitHub using the link in the Navbar. - 2. Then go to your `labs-` - 3. Click the Green "Code" button, and copy the url by clicking the two overlapping squares. - 4. Then in RStudio, choose "New project" > "Version Control" > "Git" and paste the address. - 5. Choose a location on your machine where you want all your labs to be. - 6. Select "Create Project". +1. Check your [Canvas profile settings](https://community.canvaslms.com/t5/Student-Guide/How-do-I-add-contact-methods-to-receive-Canvas-notifications-as/ta-p/516) to ensure the email associated with your Canvas account is correct. +1. Review your [Canvas notification settings](https://community.canvaslms.com/t5/Student-Guide/How-do-I-set-my-Canvas-notification-preferences-as-a-student/ta-p/434) and decide what you want to be notified about. +1. Visit the [Course website](https://ubc-stat.github.io/stat-406/). In particular, as you might expect, this course requires computing. We will use R and RStudio as well as Git and GitHub. See the [Computing](https://ubc-stat.github.io/stat-406/computing/) tab. +1. If you have never used GitHub before, go to create an account. You should be aware that this data is stored on US servers. Please exercise caution whenever using personal information. You may wish to use a pseudonym to protect your privacy if you have concerns. +k_asking_for_help/). + +If you haven't already, visit and follow the instructions to set up your computer. + +Now we have to clone your `labs-` repo. + +1. Navigate to the Course Github using the link at the top of the [Course Website](https://ubc-stat.github.io/stat-406/) or from Canvas. +2. Then go to your `labs-`. +3. Click the Green "Code" button, and copy the url by clicking the two overlapping squares. +4. Then in RStudio, choose "New project" > "Version Control" > "Git" and paste the address. +5. Choose a location on your machine where you want all your labs to be. +6. Select "Create Project". # Lab overview -If you followed all the steps above, you should have an RStudio project for all -the labs for this course. You will never have to do any of those steps again -(except the Cloning, once, for your Homework). +If you followed all the steps above, you should have an RStudio project for all the labs for this course. You will never have to do any of those steps again (except the Cloning, once, for your Homework). -In this lab, we'll do two things. The first is to demonstrate the "correct" way -to do a lab or assignment and submit it. So we'll get this unfinished lab all -ready for submission. +In this lab, we'll do two things. The first is to demonstrate the "correct" way to do a lab or assignment and submit it. So we'll get this unfinished lab all ready for submission. -The second thing is to explore Git just a little. Specifically, we'll pretend -like we're doing another submission and mess everything up. Then we'll fix it. -Finally, we'll submit the whole lab. +The second thing is to explore Git just a little. Specifically, we'll pretend like we're doing another submission and mess everything up. Then we'll fix it. Finally, we'll submit the whole lab. # The right way Beginning a new Lab or homework assignment always starts out like this. -1. In the upper right quadrant of RStudio, you should see a number of tabs. -Click the one that says "Git". +1. In the upper right quadrant of RStudio, you should see a number of tabs. Click the one that says "Git". 1. On the right side it should say `main`. This is the branch you're on. 1. ALWAYS, start from `main`. -1. Click ⬇️ Pull. This will make sure that your machine has everything on the remote. If I have to update something, this will get your stuff up-to-date. -1. Create a new branch by clicking the thing that looks like two purple squares -pointing at a diamond. -1. You can name your branch anything you like, but I'd suggest `lab00-git` to -denote the work that will happen here. +1. Create a new branch by clicking the thing that looks like two purple squares pointing at a diamond. +1. You can name your branch anything you like, but I'd suggest `lab00-git` to denote the work that will happen here. 1. Ensure that "Sync branch with remote" is checked and click "Create". -1. Now open `lab00-git.Rmd`. You'll see all the instructions you've been -looking at there in that document. -1. Try to click `Knit` or use `Cmd+Shift+K` (`Ctrl+Shift+K` on Windows/Linux). -To render the lab to `.pdf`. You should always do this first to make sure -everything works. -1. On the previous line, Delete the last sentence "You should always do this -first...". And Save. -1. Now, looking in the Git panel, you should see `lab00-git.Rmd` and -`lab00-git.pdf` with check boxes next to them. -1. Git "Stages" your changes when you click the check box. Click the box by -`lab00-git.Rmd`. -1. Commit your changes by clicking Commit. A message window will pop up. Type a -message about what you did. Something like "I hate verbose instructions". Click -`Commit`. - -The last two steps are the basic procedure you will always use. You save -regularly. Every so often (maybe each time you finish a section), you Stage + -Commit. For a lab to get full credit, you must have done this at least 3 times. - -Note, only files that are "Committed" will ever go to GitHub for grading. You -should only commit the `.Rmd` and the `.pdf`. If other things appear, you may -be doing something wrong. +1. Now open `lab00-git.Rmd`. You'll see all the instructions you've been looking at there in that document. +1. Try to click `Knit` or use `Cmd+Shift+K` (`Ctrl+Shift+K` on Windows/Linux). To render the lab to `.pdf`. You should always do this first to make sure everything works. +1. On the previous line, Delete the last sentence "You should always do this first...". And Save. +1. Now, looking in the Git panel, you should see `lab00-git.Rmd` and `lab00-git.pdf` with check boxes next to them. +1. Git "Stages" your changes when you click the check box. Click the box by `lab00-git.Rmd`. +1. Commit your changes by clicking Commit. A message window will pop up. Type a message about what you did. Something like "Edit Lab 0 instructions." Click `Commit`. + +The last two steps are the basic procedure you will always use. You save regularly. Every so often (maybe each time you finish a section), you Stage + Commit. For a lab to get full credit, you must have done this at least twice. + +Note, only files that are "Committed" will ever go to Github for grading. You should only commit the `.Rmd` and the `.pdf`. If other things appear, you may be doing something wrong. So at this point you've made one commit. ---- -### Aside {.unnumbered} +### Aside In other labs and homework, you'll see something that looks like @@ -99,41 +67,23 @@ some dumb text ::: ``` -It's called `.solbox` because that's where your solutions will go. It makes it -easier for the TAs to find your answers. So don't delete this. You should safely -put code and markdown text inside, and it will all "work". - -But watch out. It **MUST** contain text. That's why it starts with text in it. -If you delete it, resulting in an empty box, your document won't Knit. +It's called `.solbox` because that's where your solutions will go. It makes it easier for the TAs to find your answers. So don't delete this. You should safely put code and markdown text inside, and it will all "work". -### End Aside {.unnumbered} +But watch out. It **MUST** contain text. That's why it starts with text in it. If you delete it, resulting in an empty box, your document won't Knit. ---- +### End Aside -Let's pretend, now that we're _Done With The Lab_. You may still see the -unstaged `.pdf` file in that window. If so, don't worry, ignore that for the -moment. Click the Green Up Arrow ⬆️. +Let's pretend, now that we're _Done With The Lab_. You may still see the unstaged `.pdf` file in that window. If so, don't worry, ignore that for the moment. Click the Green Up Arrow. -That "Pushes" your changes to GitHub. There, the TAs can see what you've done. -Go back to your Browser and take a look. You may need to refresh the page. +That "Pushes" your changes to Github. There, the TAs can see what you've done. Go back to your Browser and take a look. You may need to refresh the page. -You should see a Yellow bar that says something like "`lab00-git` had recent -pushes" and a Green Button that says "Compare & pull request". Click that -button! +You should see a Yellow bar that says something like "`lab00-git` had recent pushes" and a Green Button that says "Compare & pull request". Click that button! -Now you can write notes to the TA that will review your work. You give it a -title like "Submission of Lab 00". There are also some prompts for you to -address. Go ahead and answer all the questions. While you're there, scroll down -and examine the changes you've made. You should only see a small modification -to 1 file. Go ahead and click the Green Button that says "Create pull request". +Now you can write notes to the TA that will review your work. You give it a title like "Submission of Lab 00". There are also some prompts for you to address. Go ahead and answer all the questions. While you're there, scroll down and examine the changes you've made. You should only see a small modification to 1 file. Go ahead and click the Green Button that says "Create pull request".
-At this point, you would be done (kinda). The TAs will automatically be -triggered to review your work. They can comment on what you've done and leave -the grade. But we're not done. That's OK Even though you've opened the Pull -Request (PR), you can still push more changes to the branch. So that's what -we'll do. +At this point, you would be done (kinda). The TAs will automatically be triggered to review your work. They can comment on what you've done and leave the grade. But we're not done. That's OK Even though you've opened the Pull Request (PR), you can still push more changes to the branch. So that's what we'll do. In General, you would `for (i in niters) {` @@ -143,22 +93,19 @@ In General, you would `}` -3. Push your work to GitHub. +3. Push your work to Github. -When done, go to GitHub and open a PR. +When done, go to Github and open a PR. Request review from the TAs. -> To avoid future headaches: use the dropdown menu in RStudio to go back to -> `main`. +> To avoid future headaches: use the dropdown menu to go back to `main`. # The wrong way(s) ## Scenario 1. You do work on the wrong branch. -Make sure that you are on `main`. Remember that the actual submission is on the -`lab00-git` branch. +Make sure that you are on `main`. Remember that the actual submission is on the `lab00-git` branch. -In the R code chunk below, fit a linear model to the data and print the -estimated coefficients, rounded to 2 decimal places. +In the R code chunk below, fit a linear model to the data and print the estimated coefficients, rounded to 2 decimal places. ```{r garbage-model-coefs, message=FALSE, warning=FALSE} library(tibble) @@ -166,9 +113,8 @@ set.seed(12345) dat <- tibble( x1 = rnorm(100), x2 = rnorm(100), - y = 2 + 3 * x1 - x2 + rnorm(100) + y = 2 + 3*x1 - x2 + rnorm(100) ) - ``` Now, stage the `.Rmd`. Commit with the message "on the wrong branch" and push. @@ -178,11 +124,9 @@ You likely see an error like: remote: error: GH006: Protected branch update failed for refs/heads/main. ``` -That's because you're on `main`. Ugh! But I did some work, and now I need to be -on a different branch! +That's because you're on `main`. Ugh! But I did some work, and now I need to be on a different branch! -So let's fix it. We want the stuff we just did on `main` to be on `lab00-git`. -Note that everything you did is saved! Here are the steps: +So let's fix it. We want the stuff we just did on `main` to be on `lab00-git`. Note that everything you did is saved! Here are the steps: **Get our changes onto the correct branch** @@ -190,8 +134,7 @@ Note that everything you did is saved! Here are the steps: 1. Go to the Terminal (next to console). 1. Type `git merge main`. -That should copy all your changes in the `.Rmd` that you made on `main` into -the correct place. Did it? +That should copy all your changes in the `.Rmd` that you made on `main` into the correct place. Did it? If you do this and you ever see stuff like @@ -206,65 +149,105 @@ You have to decide for me. >>>>>>> new_branch_for_merge_conflict ``` -This means that there were conflicts between the two versions. The stuff above -`======` was in your current branch. The stuff below is what you're trying to -merge in. You decide what to keep, the top, the bottom, or both (or neither). -Just be sure to delete the junk lines with `<`, `>`, or `=`. +This means that there were conflicts between the two versions. The stuff above `======` was in your current branch. The stuff below is what you're trying to merge in. You decide what to keep, the top, the bottom, or both (or neither). Just be sure to delete the junk lines with `<`, `>`, or `=`. + +Once you've resolved conflicts (and committed the conflict changes), double check the following: + +* You are on the correct branch (`lab00-git`) +* You have no files with uncommitted changes in the "Git" tab +* Your changes to the R chunk above exist (on this branch) + +Another way you can check for your changes is by running the `git log` commmand. +You should see something like the following: + +``` +commit 1efefd8473c2cc81893dd2a5ded929978d9ee2aa (HEAD -> lab00-git, main) +Author: Geoff Pleiss <824157+gpleiss@users.noreply.github.com> +Date: Fri Aug 30 16:41:58 2024 -0700 + + on the wrong branch + +commit 328436d60d8153db7f5b8caef56919b69a5448a2 (origin/main) +Author: Geoff Pleiss <824157+gpleiss@users.noreply.github.com> +Date: Fri Aug 30 4:44:09 2024 -0700 + + Update git instructions + +commit bb21d0cc444e65be9d801c6b672ba7491509f030 +Author: Geoff Pleiss <824157+gpleiss@users.noreply.github.com> +Date: Fri Aug 30 10:59:12 2024 -0700 + + Init +``` + +There's a lot of information here, but you should (hopefully) see at the top +your latest commit with the message "on the wrong branch." +The long string at the start of the commit +(`1efefd8473c2cc81893dd2a5ded929978d9ee2aa`) +is the *hash*. It is a unique identifier of the commit, +which can be useful if you want to reference a specific commit with other commands. + +Type `q` to exit the log viewer.
-OK. So now we have our changes in the right spot. Commit and Push the `.Rmd` -(only). Let's clean up `main` so we don't have problems later. Switch back to -`main`. +Ok. So now we have our changes in the right spot. Commit and Push the `.Rmd` (only). Let's clean up `main` so we don't have problems later. Switch back to `main`. **Undo mistakes on the wrong branch.** -In the Terminal, type `git log`. You should see some commits, one with the -message "on the wrong branch". There's a bunch of other text that I won't try -to explain, but look at the stuff _before_ (meaning below) that message. That's -the commit from before you did work on the wrong branch. You should see -something like: +In the terminal, type the following two commands: + ``` -commit 1851c738984690b039a79a04e070f766e19993d5 +git fetch +git reset --hard origin/main ``` -That long string is what we're after. It's called a hash, and it uniquely -identifies the commit. Take note of the first characters (like 5). That's -usually enough to get away with. -Type `q` to exit the log viewer.` +There's a lot to unpack in these two commands, but here's the high level idea: +we want to make sure that our `main` branch matches what's on Github's remote +`main` branch. +The second command resets our local `main` branch so that it has exactly the same +commits as Github's remote `main` branch. +(The first command makes sure that our local computer knows about the latest changes +on Github's remote branches.) -Now type `git reset --hard 1851c` (replacing `1851c` with the numbers from your -unique hash). This command will undo any changes after that commmit, but only -for this branch. +If you now type `git log`, you should now see -To recap, now the work we want is in the right place (on the other branch), and -the mess on `main` is cleaned up. Boom. +``` +commit 328436d60d8153db7f5b8caef56919b69a5448a2 (HEAD -> main, origin/main) +Author: Geoff Pleiss <824157+gpleiss@users.noreply.github.com> +Date: Fri Aug 30 4:44:09 2024 -0700 + + Update git instructions + +commit bb21d0cc444e65be9d801c6b672ba7491509f030 +Author: Geoff Pleiss <824157+gpleiss@users.noreply.github.com> +Date: Fri Aug 30 10:59:12 2024 -0700 + + Init +``` + +So our local `main` branch matches what's on Github, and no longer contains +the "on the wrong branch" commit. You can also verify that your changes to the +R code on this branch are now gone. + +To recap, now the work we want is in the right place (on the other branch), and the mess on `main` is cleaned up. Boom. ## Scenario 2. You did something you shouldn't have Switch your branch back to `lab00-git` (or whatever you named it). -Open the file `lab01.Rmd`. Select everything after `# Instructions` and delete -it. Save. Then Knit (producing a pdf). Commit both files with a message "did -the wrong lab, and built a pdf". Push your commits with the Green up arrow. +Open the file `lab01.Rmd`. Select everything after `# Instructions` and delete it. Save. Then Knit (producing a pdf). Commit both files with a message "did the wrong lab, and built a pdf". Push your commits with the Green up arrow. -Take a look at the PR on GitHub now. There's a bunch of crud that shouldn't be -there. +Take a look at the PR on Github now. There's a bunch of crud that shouldn't be there. We've done 3 things here that we shouldn't have. -1. We built a `.pdf` that we don't want at all. It needs to go away. -1. We bollixed up the `lab01.Rmd` file. We don't want that or it will screw up -the lab next week. +1. We built a pdf that we don't want at all. It needs to go away. +1. We bollixed up the `lab01.Rmd` file. We don't want that or it will screw up the lab next week. 1. We pushed it all into our submission for this week. -The first instinct is to Delete both files, commit, and push. This is **VERY** -**BAD**. That will further screw up everything. Basically, you're telling git -"I don't want these files at all" when you mean "I don't want changes to these -files in this branch". The difference is subtle but important. Because you DO -want these files (without the changes) at some point, but you don't want them -here. +The first instinct is to Delete both files, commit, and push. This is **VERY BAD**. That will further screw up everything. Basically, you're telling git "I don't want these files at all" when you mean "I don't want changes to these files in this branch". The difference is subtle but important. Because you DO want these files (without the changes) at some point, but you don't want them here. Let's fix these issues. @@ -274,78 +257,42 @@ First, we want to "get rid of" the pdf. In the Terminal type ``` git reset HEAD^ -- lab01.pdf ``` -Click the little "Refresh" arrow ↩️ in the Git panel. You should now see -`lab01.pdf` twice, once with a red D that is checked and once with two yellow -question marks that is NOT checked. This is what we want. Don't click any -other boxes. +Click the little "Refresh" arrow in the Git panel. You should now see `lab01.pdf` twice, once with a red D that is checked and once with two yellow question marks that is NOT checked. This is what we want. -Commit exactly as is. Use a message like "remove the stray pdf" and Push. Now, -take a look at the PR on GitHub. It should be gone from the list of files in -the PR. +Commit exactly as is. Use a message like "remove the stray pdf" and Push. Now, take a look at the PR on Github. It should be gone from the list of files in the PR. -There's still that annoying two-yellow-question-mark version in the Git panel. -Don't click the check box (that will just redo everything we undid). Instead, -highlight the file by clicking the file name, click the Gear Icon Dropdown ⛭, -and then select "Revert". Now it's gone, and the pdf should disappear from your -filesystem. +There's still that annoying two-yellow-question-mark version in the Git panel. Don't click the check box (that will just redo everything we undid). Instead, highlight the file by clicking the file name, click the Gear Icon Dropdown, and then select "Revert". Now it's gone, and the pdf should disappear from your filesystem.
-Second, let's "undo" the deletion in the `.Rmd`. This is easy, and a useful -pattern to remember. +Second, let's "undo" the deletion in the `.Rmd`. This is easy, and a useful pattern to remember. In the Terminal, type ``` git checkout main -- lab01.Rmd ``` -What this does is grabs the version on `main` that isn't messed up and puts it -here, overwriting your changes. This isn't the only way to fix your problem -(you could have done the same thing we did with the pdf), but it's pretty easy. +What this does is grabs the version on `main` that isn't messed up and puts it here, overwriting your changes. This isn't the only way to fix your problem (you could have done the same thing we did with the pdf), but it's pretty easy. -Stage, commit, and push. Now look at the PR on GitHub. Even though you made two -changes (one deleting everything, and one restoring everything) to the -`lab01.Rmd`, it should be "gone" from the PR now. That's because the version on -this branch looks just like the version on `main`, so there are no changes to -be made into the `main` branch. This is just what we want. +Stage commit and push. Now look at the PR on Github. Even though you made two changes (one deleting everything, and one restoring everything) to the `lab01.Rmd`, it should be "gone" from the PR now. That's because the version on this branch looks just like the version on `main`, so there are no changes to be made into the `main` branch. This is just what we want.
-Now we've also fixed the third error already. None of those bogus changes to -`lab01` are in our PR for this week anymore. +Now we've also fixed the third error already. None of those bogus changes to `lab01` are in our PR for this week anymore. # Finish up -Your Git panel should be empty. Take this opportunity to change your branch to -`main`. This will avoid issues when you start Lab 01 next week. - -We're now done with this lab. This all probably seems a bit painful, but our -goal is to avoid all these things in the future. If you're careful, in this -class, you won't have to do any of this junk again. In real life, if you work -in Data Science or Software Development or Machine Learning, you definitely -will. +Your Git panel should be empty. Take this opportunity to change your branch to `main`. This will avoid issues when you start Lab 01 next week. -## Let's just recap THE RIGHT WAY. +We're now done with this lab. This all probably seems a bit painful, but our goal is to avoid all these things in the future. If you're careful, in this class, you won't have to do any of this junk again. In real life, if you work in Data Science or Software Development or Machine Learning, you might. Let's just recap THE RIGHT WAY. 1. For HW or Labs, always start on `main`. -1. Pull in the remote ⬇️ just to be sure everything is up-to-date. -1. Create a branch for your HW/Lab and switch to it. The name doesn't matter, -but it's good practice to name in something meaningful (rather than something -like `stat406-lab-1` when you're doing lab 4). +1. Create a branch for your HW/Lab and switch to it. The name doesn't matter, but it's good practice to name in something meaningful (rather than something like `stat406-lab-1` when you're doing lab 4). 1. Open the HW/Lab `.Rmd` and click Knit. Make sure it works. -1. Do the work, saving regularly. When you complete a section, Commit the file -with a useful message (Push or Not). -1. Once you're done, make sure that you have done the minimum number of -Commits, push ⬆️ your `.Rmd` and the knitted `.pdf`. -1. Open a PR on GitHub and respond to the questions. -1. Make sure that only the `.Rmd` and the `.pdf` for this HW/Lab are there. And -Create Pull Request. -1. On your machine, switch the branch to `main` to prepare for the next HW/Lab. - - -If the TA asks for changes, just switch to the branch for this assignment, and -make the requested changes. It's all on your machine (even if the pdf -disappears when you switch). - - +1. Do the work, saving regularly. When you complete a section, Commit the file with a useful message (Push or Not). +1. Once you're done, make sure that you have done the minimum number of Commits, push your `.Rmd` and the knitted `.pdf`. +1. Open a PR and respond to the questions. +1. Make sure that only the `.Rmd` and the `.pdf` for this HW/Lab are there. And Create Pull Request. +1. On your machine, switch the branch to `main` to prepare for the next HW/Lab. And click the Blue Pull button to sync your `main` with the one on Github. +If the TA asks for changes, just switch to the branch for this assignment, and make the requested changes. It's all on your machine (even if the pdf disappears when you switch).