Introduction to Git and GitHub

with RStudio

Author

Affiliation

Julien Martin

BIO 8940 - Lecture 3

0.1 Learning expectations

This won’t even touch the surface of git… But! Hopefully, you:

• Recognize the power of using version control

• Know the basic tools to get started using git

• Where to go for help

Credit: I borrowed slides from Olivier Gimenez

0.2 Getting started

You need:

• RStudio or VS Code

• R

• a github account

• git software

• R packages:

  • usethis
  • gitcreds

1 Workflow

1.1 Rings a bell?

1.2 Is your workflow…

1.3 Why reproducible science?

1.4 RStudio Projects

Use RStudio projects to keep materials associated with a particular analysis together

• Self contained and portable

• Working directory set to root of project on launch

• Fresh session everytime the project is launched

See Jenny Bryan’s post on project oriented workflows for more details

File > New Project > New Directory

1.5 Alternatives to RStudio Projects

So You don’t like RStudio 💔

Essentially a Rstudio Project:

• organise all the files within a given project folder

• set project folder as working directory

• ensure a fresh, clean session

simply, do the same without using RStudio 🤩

2 Version Control

2.1 What is it? 🤔

The management of changes to documents, computer programs, large web sites and other collections of information.

Git

Open source (free to use) Version control software.

GitHub

A website that allows you to store your Git repositories online and makes it easy to collaborate with others.

2.2 Getting started with Git and GitHub

1. Create an account on GitHub

• You set your username, email and password here

2. install git on your computer

• Windows: https://gitforwindows.org/
• MacOS: need Xcode tools. so shell/terminal: xcode-select --install
• Linux:
  • debian-based: sudo apt install git
  • Fedora, RedHat: dnf install git

3. You might need to restart you computer

For more details got to https://git-scm.com/downloads

2.3 Git, Github & IDE

Before git only through the terminal 😢

Now git can be used via multiple user-friendly interfaces

RStudio + usethis 📦 + gitcreds 📦 == ❤️ Git & GitHub 🤩

But When using VS Code

3 Configure git & GitHub

to be done only once

3.1 Configure git

To check your configuration

usethis::git_sitrep()

Set your configuration

Use your github username and and the email you used to sign-up on GitHub

usethis::use_git_config(
   user.name = "JulienGAMartin",
   user.email = "julien.martin@uottawa.ca")

3.2 Configure GitHub authentication

Get GITHUB Personal Authorisation Token

usethis::create_github_token()

Need scopes repo, users, workflows at least

3.3 Configure GitHub authentication

Store your git token with credentials

gitcreds::gitcreds_set()

Provide your github PAT token in the window

Restart RStudio and R

Git and github access should be configured now

3.4 First (or new) project with Rstudio

Might be problematic the first time you do it

1. create R project

2. initialise it for git

usethis::use_git()

3. Accept the commit and restart R

4. In R, to create github repo and link it

usethis::use_github()
usethis::git_vaccinate()

5. Check on github that the repos is there

et voila

3.5 New project and NOT Rstudio

Option 1

1. create new empty folder for your project(no space, no accent)

2. add at least one file in it (suggest README.md)

3. using terminal/shell

git init
git add .
git commit -a -m "first commit"

4. In R, to create github repo and link it

usethis::use_github()
usethis::git_vaccinate()

5. Check on github that the repos is there

et voila

3.6 New project using GitHub and NOT Rstudio

Option 2

1. Create new repository on github

2. Set R working directory where you want to save your project

3. To clone (and link) github repo to your computer

usethis::create_from_github(
  "https://github.com/your_github/your_repo.git",
  destdir=".")

4. Check that your folder has been created where you want it

et voila

3.7 Integrated graphical user interface

3.8 Git terms

• repository your project folder

• commit a snapshot of your repo

• push send commits to a remote

• pull get commits from a remote

• clone get the repository from the remote for the first time

• branch a movable label that points to a commit

• merge combining two branches

• remote a computer or server with the repository on it

3.9 Git RStudio workflow

1.view file status

2.stage files

3.commit changes

3.10 Share on GitHub

1. Create repo

usethis::use_github(protocol = "https")

3.11 Share on GitHub

2. Push further changes

3.12 Anatomy of a GitHub repo

• README. Explain what your project is, and how to use it.
  • usethis::use_readme_md()
  • usethis::use_readme_rmd()

• LICENSE. Without a licence, the contents of the repository are technically closed.
  • Examples licence CC-by: usethis::use_ccby_license(name = "Julien Martin")
  • ?licenses: details of functions available to generate licenses
  • https://choosealicense.com/ help on choosing a licence.

• CONTRIBUTING.md - guidelines for contributors.
  • usethis::use_tidy_contributing() provides a realtively strict but instructive template

• CODE_OF_CONDUCT.md set the tone for discourse between contributors.
  • use_code_of_conduct()

3.13 GitHub issues

use GitHub issues to plan, record and discuss tasks.

3.14 Why using a remote like GitHub ?

• A backup of your repository (Dropbox is NOT a backup)

• Work with others (not covered)

• Increase your visibility

• Increase interactions with users

• Easy distribution of R packages (without CRAN submissions)

one more time just in case Dropbox is NOT a backup

3.15 Branching and merging

This the true Power of git

3.16 Branching and merging

Branching in Rstudio

Pull request in Github

When you want to merge branches:

• create a pull request on Github

• check for incompatibilities

• then merge

3.17 Resources

Check out Happy Git and GitHub for the useR for more joy with git

The British Ecological Society has A Guide to Reproducible Code in Ecology and Evolution

4 Virtuous research cycle