session-setup.qmd

---
title: "Introduction to Git and GitHub"
title-slide-attributes: 
  data-background-color: "#43464B"
subtitle: "Session - Getting started with Git and GitHub"
author: "Zoë Turner"
format:
  revealjs:
    theme: [default, nhsr-quarto.scss]
    logo: https://raw.githubusercontent.com/nhs-r-community/assets/main/logo/nhsr-logo.svg
    code-link: true
    css: nhsr-quarto.scss
    preview-links: true
execute: 
  echo: true
  eval: false
embed-resources: true  
---

## Configure Git

Configure `user.name` and `user.email`

```{r}
library(usethis)
usethis::use_git_config(
  user.name = "github_name", # Make sure this matches your GitHub account
  user.email = "jane@example.com" # Use the email associated with GitHub account
)
```

## Check Git configuration

Ask for a **sit**uation **rep**ort.

```{r}
usethis::git_sitrep()
```

A lot of information will appear in the RStudio Console!

. . .

```
Git config (global)
• Name: <unset>
• Email: <unset>
• Global (user-level) gitignore file: <unset>
• Vaccinated: FALSE
ℹ See `?git_vaccinate` to learn more
ℹ Defaulting to 'https' Git protocol
• Default Git protocol: 'https'
• Default initial branch name: <unset>
GitHub
• Default GitHub host: 'https://github.com'
• Personal access token for 'https://github.com': <unset>
• To create a personal access token, call `create_github_token()`
• To store a token for current and future use, call `gitcreds::gitcreds_set()`
ℹ Read more in the 'Managing Git(Hub) Credentials' article:
  https://usethis.r-lib.org/articles/articles/git-credentials.html
Git repo for current project
• Active usethis project: '/cloud/project'
ℹ Active project is not a Git repo
```

## Vaccinate

```{r}
usethis::git_vaccinate()
```

. . .

Adds .DS_Store, .Rproj.user, .Rdata, .Rhistory, and .httr-oauth to your global (a.k.a. user-level) .gitignore. This is good practice as it decreases the chance that you will accidentally leak credentials to GitHub. git_vaccinate() also tries to detect and fix the situation where you have a global gitignore file, but it's missing from your global Git config.

## Personal access token

- Communicating with GitHub will require authentication

- Instead of typing in your username and password each time, use a **PAT** (personal access token)

## Create a PAT

- To amend/delete existing tokens go to: [https://github.com/settings/tokens](https://github.com/settings/tokens)
- Give the token a descriptive name like `connect-posit-github`
- Copy and also store this token somewhere (you won't be able to see it again!)

```{r}
usethis::create_github_token()
```

:::{.callout-warning collapse=false appearance='default' icon=true}
## PAT tokens on the cloud
- These will get deleted automatically at regular intervals
- For the purpose of the course this will need to be added a few times!
:::


## Store your PAT

When you use the following code you'll get a prompt, copy the token with no quotes.

```{r}
gitcreds::gitcreds_set()
```

:::{.callout-note collapse=false appearance='default' icon=true}
## Deleting a PAT
If you are using the Cloud or want to delete the PAT from your system use `gitcreds::gitcreds_delete()`
:::

## Starting Git from an existing project

To make our project a Git repository, or 'repo' on our local machine we use 

```{r}
usethis::use_git()
```

:::{.callout-note collapse=false appearance='default' icon=true}
## A word on R Projects
- Git needs to be in an R Project to work in RStudio (it's good practice to use them)

``` markdown
✔ Initialising Git repo
Error: Path 'C:/Users/zoe.turner/OneDrive - Midlands and Lancashire CSU/Documents/' does not appear to be inside a project or package.
Read more in the help for `proj_get()`.
```

- The Cloud workspace _is_ a project so already has the `.Rproj` file set up for Projects
:::

## Verbose feedback

```
√ Initialising Git repo
√ Adding '.Rdata', '.httr-oauth', '.DS_Store' to '.gitignore'
There are 2 uncommitted files:
• '.gitignore'
• 'git_project.Rproj'
Is it ok to commit them?

1: Yeah
2: Absolutely not
3: No
```

:::{.callout-note collapse=false appearance='default' icon=true}
## Changing selections
Choose the positive option (these change so might say `I agree` instead of `Yes`)
:::

## Initial commit

```
√ Adding files
√ Commit with message 'Initial commit'
• A restart of RStudio is required to activate the Git pane
Restart now?

1: Nope
2: Definitely
3: No
```

- Choose the positive option (which changes!)
- The save workspace option to `.Rdata` can be either no for this, more info at [intro-r course](https://intro-r-rstudio.nhsrcommunity.com/session-rstudio.html#/tools-options-workspace)
- A new file for `.gitignore` will appear in the Files pane

## Connect this to GitHub

To create a copy on GitHub 

```{r}
usethis::use_github()
```

This will open up the GitHub page in your default browser

## Message about ssh and https

If you get this:

```
✔ Checking that current branch is 'main'
Which git protocol to use? (enter 0 to exit) 
1: ssh   <-- presumes that you have set up ssh keys
2: https <-- choose this if you don't have ssh keys (or don't know if you do)
```

Choose 2 at the moment.

## GitHub connected message in RStudio

```
ℹ Defaulting to 'https' Git protocol
✔ Setting active project to '/cloud/project'
✔ Creating GitHub repository 'Lextuga007/project'
✔ Setting remote 'origin' to 'https://github.com/Lextuga007/project.git'
✔ Pushing 'master' branch to GitHub and setting 'origin/master' as upstream branch
✔ Opening URL 'https://github.com/Lextuga007/project'
```

## master or main?

The branch is called `master` here as default but conventionally people have moved to `main`
To rename this branch:

```{r}
usethis::git_default_branch_rename(from = "master", to = "main")
```

:::{.callout-note collapse=false appearance='default' icon=true}
## Details of where the change has occurred
- This function changes GitHub (on the web) not your local project
:::


## Changing the branch name locally

Repeat the code and a different message appears

```
✖ It's weird that the current default branch for your local repo and the source repo are different:
  'master' (local) != 'main' (source)
Are you sure you want to proceed?

1: yes
2: no
```

This is our first insight into how Git sees local and remote as two separate things!

## Set future default branches to main

This won't affect other projects in the cloud but is useful on a computer

```{r}
usethis::git_default_branch_configure()
```

## Updating historic repositories

If you want to update a lot of old repository default branches from `master` to `main` this can be done using a [Shiny app](https://www.garrickadenbuie.com/blog/branchmover/) built by Garrick Aden-Buie, Software Engineer for Shiny at Posit.


## End session

# Acknowledgements

These slides were designed by Mine Çetinkaya-Rundel and Emma Rand for the Forwards Package development module course

[Your first package](https://forwards.github.io/workshops/package-dev-modules/slides/03-your-first-package/your-first-package.html#1) and
[Setting up your system](https://forwards.github.io/workshops/package-dev-modules/slides/02-setting-up-system/setting-up-system.html#1)

CDU Data Science [Personal Access Tokens blog](https://cdu-data-science-team.github.io/team-blog/posts/2021-12-18-personal-access-tokens/)