Easy setup towards version control with Git

Author

Affiliation

A. Stamm

Department of Mathematics Jean Leray, UMR CNRS 6629, Nantes University

Required R packages

Reference guide: https://happygitwithr.com/.

Visual Editor and Git

The YAML header of this document looks like this:

---
title: "Easy setup towards version control with Git"
format: html
editor:
  markdown:
    wrap: 72
    canonical: true
---

Canonical option

When collaborating on documents using version control, different authors might use either the Visual Editor or the Source Code mode.

Setting canonical: true ensures that markdown output is identical regardless of which mode was used to make edits.

More details at https://quarto.org/docs/visual-editor/options.html.

Install Git (for Windows users mostly)

Follow https://happygitwithr.com/install-git

Create a GitHub account

Go to https://github.com and create a free account.

Introduce yourself to Git

Reference: https://happygitwithr.com/hello-git

Either from the terminal:

git config --global user.name "Jane Doe"
git config --global user.email "jane@example.com"
git config --global --list

Or directly from R:

## install if needed (do this exactly once):
## install.packages("usethis")

usethis::use_git_config(
  user.name = "Jane Doe", 
  user.email = "jane@example.org"
)

E-mail

Make sure to use the same email address as the one used to create your account on GitHub.

Personal access tokens (PAT)

You need to grant RStudio or Positron permissions to act on the behalf of your GitHub account. To do this, the recommended way nowadays is to create a personal access token (PAT) on GitHub and register it in RStudio/Positron.

While you can create it directly from the GitHub interface online and then register it manually, it is somewhat painful to remember something you only need to do occasionally (typically on a monthly basis).

I recommend you use:

usethis::create_github_token()

This command then requests to open a web browser page for PAT creation with appropriate options already checked.

Proceed with creating the PAT.
Copy the PAT to clipboard with the button.

Then, back in RStudio/Positron, do:

gitcreds::gitcreds_set()

Follow the instructions, paste the PAT and validate. You are all set!

Work with projects

Structure your work

For each of your data science project, take the habit of creating a dedicated folder and open this folder in either RStudio or Positron to set it up as working directory.

Then you can initialize version control on that folder with:

usethis::use_git()

In RStudio, this activates the Git pane in the upper-right panel upon restarting RStudio. The output looks something like:

> use_git()
✔ Setting active project to "/Users/stamm-a/Downloads/test_git".
✔ Initialising Git repo.
✔ Adding ".Rproj.user", ".Rhistory", ".RData", ".httr-oauth", ".DS_Store", and ".quarto" to
  .gitignore.
ℹ There are 5 uncommitted files:
• .gitignore
• git_files/
• git.html
• git.qmd
• test_git.Rproj
! Is it ok to commit them?

1: No
2: Yup
3: Absolutely not

Selection: 2
✔ Adding files.
✔ Making a commit with message "Initial commit".
A restart of RStudio is required to activate the Git pane.
Restart now?

1: No way
2: No
3: Absolutely

Selection: 3

In Positron, you can now access the Git pane in the left sidebar.

Then you can push the local version-controlled project in your GitHub account to have a remote copy there:

usethis::use_github()

Live demo

--- title: "Easy setup towards version control with Git" format: html: code-tools: true code-link: true editor: markdown: wrap: 72 canonical: true --- ## Required R packages - [{usethis}](https://usethis.r-lib.org) - [{gitcreds}](https://gitcreds.r-lib.org) **Reference guide:** <https://happygitwithr.com/>. ## Visual Editor and Git The YAML header of this document looks like this: ``` yaml --- title: "Easy setup towards version control with Git" format: html editor: markdown: wrap: 72 canonical: true --- ``` ::: {.callout-note title="Canonical option"} When collaborating on documents using version control, different authors might use either the Visual Editor or the Source Code mode. Setting `canonical: true` ensures that markdown output is identical regardless of which mode was used to make edits. ::: More details at <https://quarto.org/docs/visual-editor/options.html>. ## Install Git (for Windows users mostly) Follow <https://happygitwithr.com/install-git> ## Create a GitHub account Go to <https://github.com> and create a free account. ## Introduce yourself to Git **Reference:** <https://happygitwithr.com/hello-git> Either from the terminal: ``` bash git config --global user.name "Jane Doe" git config --global user.email "jane@example.com" git config --global --list ``` Or directly from R: ``` r ## install if needed (do this exactly once): ## install.packages("usethis") usethis::use_git_config( user.name = "Jane Doe", user.email = "jane@example.org" ) ``` ::: {.callout-warning title="E-mail"} Make sure to use the same email address as the one used to create your account on GitHub. ::: ## Personal access tokens (PAT) You need to grant RStudio or Positron permissions to act on the behalf of your GitHub account. To do this, the recommended way nowadays is to create a personal access token (PAT) on GitHub and register it in RStudio/Positron. While you can create it directly from the GitHub interface online and then register it manually, it is somewhat painful to remember something you only need to do occasionally (typically on a monthly basis). I recommend you use: ``` r usethis::create_github_token() ``` This command then requests to open a web browser page for PAT creation with appropriate options already checked. - Proceed with creating the PAT. - Copy the PAT to clipboard with the button. Then, back in RStudio/Positron, do: ``` r gitcreds::gitcreds_set() ``` Follow the instructions, paste the PAT and validate. You are all set! ## Work with projects ::: {.callout-tip title="Structure your work"} For each of your data science project, take the habit of creating a dedicated folder and open this folder in either RStudio or Positron to set it up as working directory. ::: Then you can initialize version control on that folder with: ``` r usethis::use_git() ``` In RStudio, this activates the Git pane in the upper-right panel upon restarting RStudio. The output looks something like: ``` r > use_git() ✔ Setting active project to "/Users/stamm-a/Downloads/test_git". ✔ Initialising Git repo. ✔ Adding ".Rproj.user", ".Rhistory", ".RData", ".httr-oauth", ".DS_Store", and ".quarto" to .gitignore. ℹ There are 5 uncommitted files: • .gitignore • git_files/ • git.html • git.qmd • test_git.Rproj ! Is it ok to commit them? 1: No 2: Yup 3: Absolutely not Selection: 2 ✔ Adding files. ✔ Making a commit with message "Initial commit". A restart of RStudio is required to activate the Git pane. Restart now? 1: No way 2: No 3: Absolutely Selection: 3 ``` In Positron, you can now access the Git pane in the left sidebar. Then you can push the **local version-controlled project** in your GitHub account to have a remote copy there: ``` r usethis::use_github() ``` ## Live demo