slides.qmd

---
title: Using Git and GitHub with R
format:
  rfortherestofus-slides-revealjs:
    menu: false
    progress: false
    slide-number: true
    show-slide-number: print
    center: false
    incremental: true
    auto-animate: true
    slide-level: 4
execute: 
  message: false
  warning: false
  cache: false
title-slide-attributes:
  data-background-image: assets/rru-hex-bg-gradient-dark.svg
  data-background-size: cover
---

# Introduction to Using Git and GitHub with R {.inverse}

## Welcome to Using Git and GitHub with R {.inverse}

### Intro

- If you've used R for a while, you've probably wondered how to work with others
- This course will teach you how
- In the process, you'll learn to use Git and GitHub, which are great tools even if you are working solo on a project
- Git and GitHub have some incredibly confusing concepts but you don't need to understand internals/all details of git to use it
- In this course you'll be introduced to the concepts through animated videos

### Discuss Metaphor Video

- TidyBuild Studios
- Group of architects working together to create blueprints for a new housing development
- They use workflow that mirrors the git + GitHub workflow
- We'll use metaphors in the animated videos to make abstract git concepts more concrete

### Animated Video

Animated video will show overall architect/blueprint metaphor. Let's wait to work on it until the very end.

### Why you should learn to use Git and GitHub

1. complete history/backup
2. work on code with others efficiently
3. best way to do project management for code projects

## How the Course Works {.inverse}

### On Camera

#### Lesson structure

- I'll introduce concept
- Use animated video to see our friends at TidyBuild Studios do same thing
- I'll demonstrate concept in GitHub Desktop and RStudio
- Your Turn
- Learn More section

#### Tools we'll use

- Covers RStudio and GH Desktop early on, but only GH Desktop later
- I'll put links to command line equivalents in Learn More sections, but won't present on them

#### Why I use these tools

- For simple git stuff, RStudio is all you need
- If you want to do more complicated things, use GHD
- GHD lets you do the thing you want without worrying about esoteric terminal commands: <https://show.rfor.us/l9F8ZZNp>
- GHD is actually better per [Daniel Sjoberg quote](https://www.linkedin.com/feed/update/urn:li:activity:7238979946767900672?commentUrn=urn%3Ali%3Acomment%3A%28activity%3A7238979946767900672%2C7238998663769812992%29&replyUrn=urn%3Ali%3Acomment%3A%28activity%3A7238979946767900672%2C7239042170224058368%29&dashCommentUrn=urn%3Ali%3Afsd_comment%3A%287238998663769812992%2Curn%3Ali%3Aactivity%3A7238979946767900672%29&dashReplyUrn=urn%3Ali%3Afsd_comment%3A%287239042170224058368%2Curn%3Ali%3Aactivity%3A7238979946767900672%29)  
- Lots of uppity people talking about terminal, but as Jenny Bryan says: [no merit badges for git](https://happygitwithr.com/git-client#no-one-is-giving-out-git-nerd-merit-badges)

## Update Everything {.inverse}

### On Camera

### Animated Video

Animated video will show architect getting new tools (pens, paper, compass, protractor, drafting board, etc) before she actually starts working on blueprints.

### On Screen

- Update R
- Update RStudio

## Your Turn {.your-turn} 

1. Update R.
1. Update RStudio.
1. Reinstall packages if necessary.

# Git {.inverse}

## Install Git {.inverse}

### On Camera

### Animated Video

The animated video will show a portion of the architect's office being cleared out in order to make space for filing cabinets, which will be added in the Create a Local Git Repository lesson below.

### On Screen

- Install GitHub Desktop
- Show how to install git by itself if necessary
- Show git in RStudio
- Check git version

## Your Turn {.your-turn}

1. Install GitHub Desktop.
1. Install git separately (only if necessary).
1. Confirm git installed correctly by checking version using `git --version` in the terminal.

## Configure Git {.inverse}

### On Camera

### Animated Video

Animated video will show architect getting customized sticky notes printed with her name and email on them. The sticky notes will be used later on in the commits video. 

### On Screen

- In GHD
- In RStudio

## Your Turn {.your-turn}

1. Configure Git by adding a user name and email to your profile using GitHub Desktop.

## Create a Local Git Repository {.inverse}

### On Camera

### Animated Video

Animated video will show a filing cabinet being set up in the architect's. It should be a three-drawer cabinet (we'll use one drawer early on in the course, but later lessons will use multiple drawers when talking about branches). 

### On Screen

#### In RStudio and GHD

- When starting new project
- In RStudio, talk about it with usethis as well as when creating a new project
- When creating repo from existing project

#### Ignoring files

- RStudio does this by default; GH Desktop does this if you choose template
- Why would you ignore files?
- Make sure you don't include things by accident
- I'll show more about this in later lesson

## Your Turn {.your-turn}

1. Create a new Quarto website project in RStudio.
1. Make sure to create a git repo while creating your project.

## Commits {.inverse}

### On Camera

### Animated Video

Animated video will show the architect working for a while on their blueprint and then deciding it's time to save their work (i.e. make a commit). 

### On Screen

#### Working directory

- Working directory (basically same as repo) (see [here](https://medium.com/tech-journey-with-anna/git-question-what-is-the-difference-between-the-working-directory-aka-workspace-and-the-eeee15b7e4b3))
- "The working directory is like a work bench it is where you edit your files, add new files and delete files." - <https://arc.net/l/quote/pzezrgof>
- Working directory becomes a repository once we create local git repo

#### Other Terms

- Staging area: Talk about section of desk as staging area to decide which files to include. 
- Commit messages = sticky note attached to files that talk about what has changed. 
- Commit = add things in file folder and attach commit message. 
- Hash = unique identifier stamped on file folder as it goes through tubes.

#### Stage/staging area

- Choosing which files to include in repo

#### Committing

- Commit Message (like email subject line; no more than 50/72 characters): typically in present tense
- Commit description (like email body) but rarely used
- Make small commits

Show in GHD/RStudio


## Your Turn {.your-turn}

1. Change the title of your Quarto website by editing the `_quarto.yml` file.

. . .

Then, in GitHub Desktop or RStudio:

1. Add the `_quarto.yml` file in the staging area.
1. Add a commit message.
1. Make a commit.

## Commit History {.inverse}

### On Camera

### Animated Video

In this animated video, I want to show the filing cabinet with files in it, each representing one commit. The architect here could look through the filing cabinet in order to see the history of their work over time.

### On Screen

- View history of changes
- Diffs in GHD and RStudio

## Your Turn {.your-turn}

- View commit history in GitHub Desktop and/or RStudio.

# GitHub {.inverse}

## GitHub Repositories {.inverse}

### On Camera

### Animated Video

The animated video should show GitHub as a sort of HQ office for the architecture company. In the HQ, there are many filing cabinets, each representing a single repository. 

### On Screen

- There are other systems (GitLab, Bitbucket, etc)
- One repo per project in R

## Connect to GitHub {.inverse}

### On Camera

### Animated Video

The animated video should show the creation of some sort of pneumatic tube system (though maybe this isn't great because you can't put a whole file folder in it; perhaps it could be a factory line-style system that file folders go on; I'm open to your ideas here). Whatever system we use, the video should show it being built to connect the architect's office to HQ.

### On Screen


#### Connect to GitHub

- Sign up for GH
- In GH Desktop, sign into GitHub
- In RStudio, do PAT business
- Tell people to do RStudio PAT business because it will enable them to install repos (check if removing credentials means you can no longer install packages). See <https://arc.net/l/quote/aharrxyw>

## Your Turn {.your-turn}

- Connect to GitHub using GitHub Desktop.
- Connect to GitHub using RStudio.

## Publish Repository from Local to Remote {.inverse}

### On Camera


#### Local vs remote

- Local vs remote/origin (see <https://arc.net/l/quote/muqmphgn>)
- GitHub is your remote

### Animated Video

The animated video should show how the architect publishes a copy of all of their work on the project to HQ using the system set up in the previous lesson. One thing to note here is that pushing code to GitHub involves making a copy of it, as you still have the code locally as well. I wonder if we maybe show the blueprints being copied on an old-school copying machine first before they get sent to HQ. 

### On Screen

- In GH Desktop, publish to GH
- In RStudio, use `usethis::use_github()`
- Talk about public vs private repos

## Your Turn {.your-turn}

- Publish your website project to GitHub using GitHub Desktop or RStudio.

## Clone Repository from Remote to Local {.inverse}

### On Camera

### Animated Video

In the animated video, I would just show an existing filing cabinet in HQ being connected to the architect's office through a pneumatic tube (or other) system. It's the building of the connection between HQ and local office that is most important to show.

### On Screen

- Create new repo on GH and clone it locally
- Show how to do it with GHD and RStudio

## Your Turn {.your-turn}

- Create a repo on GitHub.

- Clone it using GitHub Desktop or RStudio.

## Keep Local and Remote Repositories in Sync {.inverse}

### On Camera

### Animated Video

The terms used to talk about this process are **push** (local to remote) and **pull** (remote to local). I wonder if we make this explicit in this video and previous ones by having the pneumatic tube (or other) system involve physical pushing and pulling. No matter how we show this, the animated video for this lesson should show the architect working on blueprints, making a commit (i.e. adding new file folders in the cabinet), and then pushing this commit to GitHub. Similarly, it should show the process of pulling updates when others have worked on the blueprints and pushed their changes to HQ. The slightly confusing thing here is that we haven't actually talked about collaboration, but I'll mention in my on-camera portion of the video that the next section of the course covers this.

### On Screen

#### Pushing

- Work locally
- Commit along way
- Push to GH
- Reminder about small commits

#### Pulling

- Show it in RStudio + GHD
- Fetch vs pull (Pull = fetch + merge) see https://arc.net/l/quote/vsndbbpg

### On Camera

- This is the last thing we'll do with RStudio
- Talk about how this has all been working by myself, but next section is about collaboration with others
- From here on out, just using GH Desktop

## Your Turn {.your-turn}

- Make a commit in your local repo.
- Push your commit to GitHub using GitHub Desktop or RStudio.
- Make a change on GitHub.
- Pull to get this commit using GitHub Desktop or RStudio.

# Collaboration with GitHub {.inverse}

## Why Use GitHub for Collaboration? {.inverse}

### On Camera

### Animated Video

No animated video, but maybe show animated pieces along the way as I talk. Do this after I've done everything else since it will incorporate elements from other videos.

### On Screen

#### Backup / able to view history

#### Collaboration

- With other tools, multiple people can't work on code at same time
- Explain what this would look like for working on blueprint

#### Project management built into GH

- Issues
- Branches/PRs

#### Automation

- Publish stuff online
- Automatically scheduling code to run through GH Actions (like blueprints being printed automatically)

## Set up GitHub Repositories for Collaboration {.inverse}

### On Camera

### Animated Video

For the animated video, I imagine architects in a meeting being assigned to a project and then getting filing cabinets rolled into their offices. 

### On Screen

- Personal vs Organization Accounts (show how to transfer repo)
- Adding People to Your Repo
- [Forks](https://stackoverflow.com/questions/3611256/forking-vs-branching-in-github) 

## Project Management with GitHub {.inverse}

### On Camera

### Animated Video

For the animated video, I imagine this being some kind of physical board where tasks are posted. I can imagine something where architects for the company come in each day and receive the tasks they are supposed to work on. They would be assigned to them on the board in some way and the architects would then take them on their way to their offices. 

### On Screen

#### Issues

- Reference changes with SHA
- Task lists
- Assigning people

#### Organize issues

- Labels for ongoing things
- Milestones for one-time things
- Projects to see all things visually
- Wiki
- Discussions

#### Notifications

- Do you want to get emails?
- You can respond to emails to post in GH issues
- How to see all notifications on issues/PRs/etc: https://github.com/notifications

#### Branches and pull requests

- We'll come back to them

## Your Turn {.your-turn}

1. Create an issue in your GitHub repository.
1. Solve the issue by working in your local project.
1. Make a commit and push to GitHub.
1. Add a comment in your issue, saying you completed the issue.
1. In your comment, use the SHA to reference the changes you made.
1. Close the issue.

## Branches {.inverse}

### On Camera

One of the major benefits of working with GitHub is that you can use branches. This is like making a copy of your code, working on it, and only if you decide you like it, you can then merge it back into the "main" branch of your project. 

### Animated Video

For the animated video, I envision branches as being like different drawers in the filing cabinet. The drawer that the architect has been working on so far in the videos is the "main" branch, but they can also use different branches to test.  I'm imaging something like the architect saying they want to test a new design for the living room so they create a branch. They work, creating commits in this branch. 

### On Screen

#### Why should you use them

- Test things and only merge back in if you like what you did
- Do PRs to get feedback
- Test things on live site

#### Linking issues to branches

#### Creating branches in GHD

## Your Turn {.your-turn}

1. Create an issue and linked branch on GitHub.
1. Use GitHub Desktop to switch to the branch you created.
1. Work in your branch to complete the issue.
1. Make a commit in your branch.
1. Push your commit to GitHub.
1. Make sure you can see the commit in the branch in your GitHub repo.

## Pull Requests {.inverse}

### On Camera

To get code from a branch back into the main branch, the usual approach is what's known as a pull request. This is a way for users to get others to review their code before merging it into the main branch. 

### Animated Video

In the animated video, I imagine the architect showing the work they did on the living room in a branch. The boss reviews the revisions and if she agrees that it should be included in the main branch, the pull request is merged into the main branch.

### On Screen

- Show merging without PR first and explain why it isn't ideal (use materials from previous course to show Alison Hill's tweet) 
- Show PR
- Dealing with merge conflicts in PRs (say that this will be discussed more in future lesson)
- Code reviews
- [Magic words for closing](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)

## Your Turn {.your-turn}

1. Create a pull request from GitHub Desktop.
1. Review the pull request on GitHub.
1. Merge your pull request.
1. Make sure your GitHub issue is also closed after the pull request is merged.

# Common Git Problems and Solutions {.inverse}

## Can't Pull from GitHub {.inverse}

### On Camera

### Animated Video

In the animated video, I imagine showing the original architect (we should probably give her a name) working on blueprints in her office. She hasn’t saved her changes but sees that someone else made changes and pushed them to HQ. She tries to pull the changes down but can’t because git doesn’t know if your local changes will conflict with changes someone else made. The solution is that you have to make a commit first and then you can pull.

### On Screen

- Need to commit changes locally first

#### Stashes etc

- Can use stashes: 
  - https://docs.github.com/en/desktop/making-changes-in-a-branch/stashing-changes-in-github-desktop
  - https://happygitwithr.com/pull-tricky
  - https://github.com/MikeMcQuaid/GitInPractice/blob/main/03-FilesystemInteractions.adoc#temporarily-stash-some-changes-git-stash
  - https://git-scm.com/book/en/v2/Git-Tools-Stashing-and-Cleaning
- Can also discard changes in GHD

Talk about why using stashes isn't that great: https://happygitwithr.com/pull-tricky#other-approaches

This is why branches are helpful

## Your Turn {.your-turn}

1. Make an edit to the `index.qmd` file on your website project locally but **don't commit changes**.
1. Make edit to `index.qmd` file on GitHub.com and save it.
1. Attempt to pull from GitHub. You should get a message about needing to commit changes before pulling.

## Your Turn {.your-turn}

4. Commit your local changes.
5. Pull again, making sure you can successfully bring in the changes from GitHub.

::: {.notes}
Heads up: you should get a message about a merge conflict. We’ll deal with this in the next lesson!
:::

## Merge Conflicts {.inverse}

### On Camera

- Merge conflicts are the scariest part of GitHub for many people: Please Let Me Merge Before I Start Crying
- Happen when you and someone else edit the same line
- You've experienced conflicts with Dropbox
- Git doesn't decide which version to keep

### Animated Video

For the animated video, I imagine one architect working on a file and another working on the same file. One pushes their code to GitHub. Then, when the second one tries to pull, there is a merge conflict because they edited the same part of the file. The video should then show the solution where one architect (the one who pulled) has to decide which version of the blueprints to keep.

### On Screen


#### Merge conflict markers etc

Show them

#### How to deal

- Deal with them in text editor locally
- Use GHD to deal with them by selecting which version to keep
- Deal with them on GitHub.com
- Show them when working in main branch

#### How to deal

From Deepansh Khurana PPT:

Resolve Conflicts Locally: When you resolve conflicts on DevOps, GitHub or GitLab, you commit before you test. When you resolve conflicts locally, you commit after you test. This helps you avoid unexpected and unintentional breakage in the code.

#### Merge conflicts in PRs

- Show them when working with PRs

#### Update branch from main

In PRs, update branch from main periodically in order to not get too far behind and avoid merge conflicts when submitting PR

## Your Turn {.your-turn}

. . .

You should have a merge conflict from last lesson.

1. Fix the merge conflict using RStudio.
1. Confirm in GitHub Desktop.
1. Push your code to GitHub.

## Can't Push Code to GitHub {.inverse}

### On Camera

### Animated Video

In the animated video, I imagine one architect has done work on blueprints, but hasn't yet pulled others' work from HQ. She gets stuck and then realizes she has to pull first and then push. 

### On Screen

## Your Turn {.your-turn}

1. Make an edit on GitHub.
1. Make an edit locally.
1. Attempt to push your changes from your local repository to GitHub (it should fail).
1. Pull in changes from GitHub.
1. Deal with any merge conflicts.
1. Push your changes to GitHub.

## Use gitignore to Keep Files Off of GitHub {.inverse}

### On Camera

### Animated Video

For the animated video, I imagine there being a set of files that get created when the various blueprints are combined. Since these files can be created by each architect on their own computer and would change all of the time, we don't want them tracked by git. In the video, we would show one architect adding files to the gitignore so they don't get tracked and we avoid conflicts.  

### On Screen

- Ignore things you never want added (better than unchecking them every commit)
- Ignore sensitive data (see lesson below)
- Ignore files that may be commonly overwritten

## Your Turn {.your-turn}

1. Add `_site` to gitignore.
1. Delete the `_site` folder.
1. Make a commit and push to GitHub.

## Best Practices for Using Git and GitHub {.inverse}

### On Camera

### Animated Video

### On Screen

Make small commits

[Nick Hodges 
quote](https://arc.net/l/quote/qxmekmfi)

Use descriptive commit messages

Push early and often

Use branches and pull requests

If necessary, [burn it all Down](https://happygitwithr.com/burn) 

# Common Git Techniques {.inverse}

## How to Work on Multiple Computers with Git and GitHub {.inverse}

### On Camera

- In this section, show common techniques you will need to do
- Imagine you work on a computer at office and at home

### Animated Video

For the animated video, I think we could show the architect working at the office and then going home and wanting to work a bit at night. In the video, we could show how you can set up a pneumatic tube system to connect from HQ to home as well as the system that connects office to HQ.

### On Screen

- Show working on Mac at work and Windows at home
- Set up computer at home to use git with same account
- Clone repo
- Work on repo
- Make commit
- Push to GH
- Back at office, pull from GH

::: {.notes}
Video for Hannah: https://show.rfor.us/Q94ng65p
:::

## Your Turn {.your-turn}

Nothing, but feel free to test this out if you work on multiple computers


## How to Avoid Putting Sensitive Information on GitHub {.inverse}

### On Camera

- Two types of sensitive info to avoid sharing: data and API keys

### Animated Video

For the animated video, I imagine an architect has a file that has a set of proprietary colors that the firm uses. Since they don't want this to ever get out, they have to come up with strategies to access it without including it in their GitHub repository. The way to show this is probably to put the file in special location outside of the repository and then pulling it onto their desk whenever they want to work with it.

### On Screen

Options:

- gitignore files and ensure everyone has data files in same place
- Put data in some other tool and access it with a package like googlesheets4/googledrive
- Use special location on network drive etc in code that only internal people can access
- Use environment variables for API keys

## Continuous Deployment {.inverse}

### On Camera

- We've created code for website, but not yet deployed it
- How can we do this?
- I'll show a way to deploy continuously so that any time you make changes, the website will update

### Animated Video

For the animated video, I'm imagining a scenario where the architect brings together all parts of the blueprints on her local system. Whenever she makes changes and pushes them to HQ, the final combined version of the blueprints is created in a location accessible to the builders of the house. This can be updated any time new blueprints are pushed to HQ.

### On Screen

- Use Netlify drop
- Unignore `_site`
- Show using Netlify
- Show using GH Pages

## Your Turn {.your-turn}

1. Unignore your `_site` folder.
1. Connect your GitHub repo to Netlify and deploy it as a website.
1. Make a change to your website and render it on your computer.
1. Push your changes to GitHub and ensure they show up on your website.

## Use GitHub Actions to Run Code Automatically {.inverse}

### On Camera


### Animated Video

This lesson takes the last lesson one step further. While in the last lesson the architect herself has to combine the blueprints into a single blueprint for the builders, with this technique, you can have the blueprints combine themselves any time you push to GitHub. This is done using [GitHub Actions](https://rfortherestofus.com/2023/05/github-actions).

In the animated video, I imagine the blueprints combining themselves into a single file every time an update is pushed to HQ.

### On Screen

- Set up GH Action
- Use existing actions
- GH pages
- Netlify
- How to install R packages (see https://github.com/rfortherestofus/cwp-dashboard/blob/main/.github/workflows/update-data.yml)

## Your Turn {.your-turn}

- Set up your website to deploy with GitHub Actions

# Wrapping Up {.inverse}

## A Git and GitHub Workflow in Action {.inverse}

::: {.notes}
Video: 
- show humming office with people working on issues in branches, submitting PRs, etc. 
- Redo initial video but add in specific git language.
:::

## Wrapping up Using Git and GitHub with R {.inverse}

::: {.notes}
Ask for testimonials
:::