Introduction to Git and GitHub

with RStudio

Julien Martin

BIO 8940 - Lecture 3

2024-09-19

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

Getting started

You need:

  • RStudio or VS Code

  • R

  • a github account

  • git software

  • R packages:

    • usethis
    • gitcreds

Workflow

Rings a bell?

Is your workflow…

Why reproducible science?

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

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 🤩

Version Control

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.

Getting started with Git and GitHub

  1. Create an account on GitHub
  • You set your username, email and password here
  1. 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
  1. You might need to restart you computer

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

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

Configure git & GitHub

to be done only once

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")

Configure GitHub authentication

Get GITHUB Personal Authorisation Token

usethis::create_github_token()

Need scopes repo, users, workflows at least

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

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()

  1. Accept the commit and restart R

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

usethis::use_github()
usethis::git_vaccinate()
  1. Check on github that the repos is there

et voila

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"
  1. In R, to create github repo and link it
usethis::use_github()
usethis::git_vaccinate()
  1. Check on github that the repos is there

et voila

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=".")
  1. Check that your folder has been created where you want it

et voila

Integrated graphical user interface

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

Git RStudio workflow

1.view file status

2.stage files

3.commit changes

Share on GitHub

1. Create repo

usethis::use_github(protocol = "https")

Share on GitHub

2. Push further changes

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()

GitHub issues

use GitHub issues to plan, record and discuss tasks.

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

Branching and merging

This the true Power of git

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

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

Virtuous research cycle

BIO 8940 - Lecture 3