Credits

• Many slides from Anna Krystalli

Rings a bell?

Version Control

What is it?

The management of changes to documents, computer programs, websites, etc...

Git

Free to use version control software

If Dropbox and the "Track changes" feature in MS Word had a baby, that would be Git (Alexa Fredston)

GitHub

A website (https://github.com/) to store your Git repositories online and makes it easy to collaborate with others

You do not need GitHub to use Git, just like you do not need RStudio to run R (Alexa Fredston)

Why use version control?

Git, Github & RStudio

Before: Git only through the terminal 😢

Now RStudio allows using Git & GitHub 🤩

Configure Git & GitHub

Configure Git

Check your configuration

usethis::git_sitrep()

Set your configuration

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

usethis::use_git_config(
    user.name = "oliviergimenez",
    user.email = "olivier.gimenez@cefe.cnrs.fr")

Configure GitHub authentication

Get GITHUB Personal Authorisation Token

usethis::create_github_token()

Store in .Renviron file

usethis::edit_r_environ()

RStudio Projects

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

Initialise git

Initialise RStudio project with Git by just checking a box!

It's now a repository

Git panel

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 with the repository on it)

Git RStudio workflow

Share on GitHub

Create repo

Via GitHub or using package usethis w/ usethis::use_github(protocol = "https")

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 MIT: usethis::use_mit_license(name = "Olivier Gimenez")
  • ?licenses: details of functions available to generate licenses
  • https://choosealicense.com/ help on choosing a licence.

Anatomy of a GitHub repo

• 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 so-called issues to plan, record and discuss tasks

Why using a remote like GitHub ?

• A backup of your repository

• Keep track of all changes, and possibility to rollback to a previous state

• Increase your visibility

• Easy distribution of packages (without CRAN submissions)

• Work with others (not [fully] covered)

• Increase interactions with users (issues, pull requests)

Working with others

• Use issues to talk to repo holders: propose changes, report bugs, etc...

• If you're a collaborator, clone the repo, do modifications and push them

• If you're not a collaborator, fork, clone then use pull requests

• Branches allow playing around without messing around with the main line of development

  • Allow exploring several versions of an idea, and switching between them
  • A branch should correspond to a bug fix, a new feature, etc.
  • Useful when unsure when/if some modifications will be included

• Resolving conflicts: see practical

Further reading

• The bible: Happy Git and GitHub for the useR

• See also: Hadley Wickham R packages book

• And in French: Travailler avec Git via RStudio et versionner son code

My two-cent workflow

Create a new repository on GitHub

Name and Public/Private

Copy https

In RStudio, File/New Project

Select Version Control

Select Git

Clone your repo (remote to local)

Stage, commit and push

Alternative is to go local first

• Step 1: Use RStudio projects (possibility to create a project from an existing directory)

• Step 2: usethis::use_git() and follow instructions

• Step 3: usethis::use_github() and follow instructions