Git and GitHub for R users

Dr Nicola Rennie

Welcome!

Who am I?

Lecturer in Health Data Science within Centre for Health Informatics, Computing, and Statistics.


Academic background in statistics, with experience in data science consultancy and training.


Using R for over 10 years, and author of multiple R packages.

CHICAS logo

Workshop outline

  • 13:00 - 13:30: Introduction to Git and GitHub for R
  • 13:30 - 14:15: Cloning and committing
  • 14:15 - 14:30: BREAK
  • 14:30 - 15:00: Branching and handling conflicts
  • 15:00 - 15:45: Sharing and reviewing
  • 15:45 - 16:00: Discussion

What to expect during this workshop

  • Combines slides, live coding examples, and exercises for you to participate in.

  • Ask questions throughout!

  • I hope you end up with more questions than answers after this workshop!


Stranger Things questions gif

Source: giphy.com

Workshop resources

Course website: nrennie.rbind.io/training-git-r

Screenshot of course website

Introduction to Git and GitHub for R

Sharing code with other people

Imagine:

  • You’ve written some code, and you want me to review it so you email a file called code.R.
  • I add some comments or changes, and email you code back in a file called code_Nicola_comments.R.
  • You apply changes and add some more code, and ask for a review the next week. You email me a file called code_v2.R.
  • I add some comments or changes, and email you code back in a file called code_v2_Nicola_comments.R.
  • and so on…

Sharing code with other people

  • Git: a free, open source version control tool that you install on your laptop.

  • GitHub / GitLab / BitBucket: a place to host online Git repositories, which allows people in different locations to work together on the code.



Sharing code with other people

GitHub* allows you to:

  • Keep track of different versions, and history, of files without keeping multiple copies.
  • Keep track of changes, even after they are accepted.
  • Ask someone to review your code, and they can add comments, ask questions, or suggest changes.
  • Make issues, and set deadlines (i.e. use it as a project management tool).
  • Add automatic code checks e.g. linting.
  • Use it on your own, or with other people.

*or other online repository hosting services

Sharing code with the world

  • GitHub repositories can be private or public:

    • Develop in private (or public)
    • Make public when submitting to journal

  • Add a license file to explain how other people can use your code

  • Use .gitignore and GitHub secrets to make sure you never accidentally upload data or sensitive information like passwords.

Using Git and GitHub with RStudio

What you need:

  • R, RStudio, and Git installed on your laptop

  • A GitHub account

  • GitHub credentials

Optional (but strongly recommended):

Live Demo!

  • Make sure git is talking to R

  • Create a token

  • Set the token

Exercise 1

  1. Create a GitHub account if you don’t already have one, and make sure you have Git installed on your laptop.

  2. Install and load the usethis and gitcreds packages.

  3. Configure git then run create_github_token(), and follow the instructions to generate a token.

  4. Run gitcreds_set() and paste in the token when prompted.

Hint: Open happygitwithr.com/https-pat!

10:00

Creating and cloning a repository

Local and Remote Repositories

Image: allisonhorst.com/git-github

Live Demo!

  • Create a GitHub repository

  • Create a new R project

  • Clone the repository

Exercise 2

  1. Create a GitHub repository.

  2. Create a new R project, and clone the repository.

10:00

Committing and pushing changes

Committing files

Image: Openscapes blog GitHub for supporting, contributing, and failing safely by Allison Horst and Julia Lowndes.

Committing files

Image: Openscapes blog GitHub for supporting, contributing, and failing safely by Allison Horst and Julia Lowndes.

Committing files


Commit often

Make frequent commits. Otherwise, if you make a mistake, it’s harder to roll back to the version that works.

Pushing changes

Image: allisonhorst.com/git-github

Live Demo

  • Committing changes

  • .gitignore files

  • Push changes

Exercise 3

  1. Commit the initial files created when making a project.

  2. Download the Hypoxia.csv file above and save it into a folder called data in your git project. Download the analysis.R file and it to the project as well.

  3. Add the data folder to your .gitignore file.

  4. Commit and push your changes, and view them on GitHub.

10:00

Working in branches

Multiple people making changes

Image: Openscapes blog GitHub for supporting, contributing, and failing safely by Allison Horst and Julia Lowndes.

What are branches?

Image: www.nobledesktop.com/learn/git/git-branches

Good practices for branching

  • Use descriptive branch names

  • Branches should be for a specific feature (not person!)

  • Regularly sync with the main branch

  • Delete merged branches

Live Demo!

  • Creating a branch

  • Making and committing changes

  • Pushing changes to a remote branch

  • Making a pull request

Exercise 4

  1. Create a new branch from RStudio.

  2. Make an edit to your R script and commit the changes.

  3. Push your new branch to GitHub and open a pull request.

10:00

Handling git conflicts

What are conflicts?

Image: allisonhorst.com/git-github

Live Demo!

  • Creating a conflict

  • Pulling changes request

  • Fixing merge conflicts

  • Merging pull requests

Exercise 5

  1. Use the web editor to make a change on main.

  2. Return to your pull request and fix any merge conflicts.

  3. Merge the pull request and delete the new branch.

10:00

Sharing and reviewing

Before you share

Write a README.md file!

A README file is a documentation file that provides an overview of a project. It typically includes key information such as:

  • Project title and description
  • Usage instructions e.g. version of R, packages required
  • Contribution guidelines
  • Contact details or links to further resources

Make a pull request and ask for review

See jcken95.github.io/projects/code_review.html for some good advice!

Live Demo!

  • README.md files

  • Create a branch and commit some changes

  • Create a pull request

  • Request a review

  • Adding contributors

Exercise 6

  1. Create a new branch and edit your R script in some way (e.g. add some code or comments)

  2. Commit your changes, open a pull request, and describe the changes.

  3. Request a review from someone else in the room (and vice versa).

Note: you may need to add them as a collaborator to the repository. (You can remove them afterwards.)

  1. Review someone else’s code - leave comments and decide whether to approve.

  2. Bonus: add a README.md file to your repository, with a brief summary of the project and stating what packages and version of R you have used.

10:00

Other useful GitHub features

  • GitHub Issues/Discussions

  • GitHub profile README

  • GitHub Pages

  • GitHub Actions

Workshop resources

Course website: nrennie.rbind.io/training-git-r

Screenshot of course website

Feedback



Feedback form: forms.gle/2dJqkMw9E5cazBRJ7


nrennie.rbind.io

nicola-rennie

nrennie

nrennie.github.io/training-git-r