This document is a compilation of NCEAS training material on version control to create a 45-60 min crash course on getting started with version control for RStudio users. You will learn:

how to setup git on your machine
how to create repository on GitHub
git basic workflow an manipulations using RStudio
Collaborating using git and GitHub

1 Introduction to Version Control Concepts

Version control is a system that helps you to manage the version of your files. It will help you to never have to duplicate files using save as as a way to keep different versions of a file (see below). Version control help you to create a timeline of snapshots containing different versions of a file. Bonus: you can add a short description to remember what each specific version is about.

For scientists, version control is a useful tool to help you to track changes you make to your scripts and enable you to share your code with your collaborators. For example, if you break your code, git can help you revert to an earlier working version. Another example could be that you want one of your collaborators to add a new feature to your code to improve your analysis. Version control can help you to do so in a smooth and organized manner, tracking who changed what in the script.

2 git

This training material focuses on the code versioning system called Git. Note that there are others, such as Mercurial or svn for example.

Git is a free and open source distributed version control system. It has many functionalities and was originally geared towards software development and production environment. In fact, Git was initially designed and developed in 2005 by Linux kernel developers (including Linus Torvalds) to track the development of the Linux kernel. Here is a fun video of Linus Torvalds touting Git to Google.

2.1 How does it work?

Git can be enabled on a specific folder/directory on your file system to version files within that directory (including sub-directories). In git (and other version control systems) terms, this “tracked folder” is called a repository (which formally is a specific data structure storing versioning information).

3 What git is not

Git is not a backup per se
Git is not good at versioning large files (there are workarounds) => not meant for data

4 Setting up git on your computer

MacOSX and Linux computers all come with git pre-installed, but it is not always directly usable. The best way to test if git is ready to use is at the command line:

git --version

## git version 2.17.2 (Apple Git-113)

It should return something like above. If you get an error, you will have to install git

Windows users will have to install a software called git bash before being able to use git.

4.1 Installing git

You can download a copy of git here: https://git-scm.com/downloads and follow the instructions.

4.1.1 Windows

You can keep the options to default during the installation, until you reach Configuring the terminal emulator to use with Git Bash -> be sure Use MinTTY is selected. This will install both git and a set of useful command-line tools using a trimmed down Bash shell.

4.1.2 Mac OSX

Depending on the version, you might have to run a few commands from the terminal. Please refer to the README.txt that comes with the download regarding the exact steps to follow.

4.2 Setting up your `git` identity

Before you start using git on any computer, you will have to set your identity on your system, as every snapshot of files is associated with the user whom implemented the modifications to the file(s).

Open the Terminal or git bash and then type the following commands.

4.2.1 Setup your profile

Your name and email:

git config --global user.name "your Full Name"
git config --global user.email "your Email"

4.2.2 Optional

Check that everything is correct:

git config --global --list

Modify everything at the same time:

git config --global --edit

Set your text editor:

git config --system core.editor nano

Here nano is used as example; you can choose most of the text editor you might have installed on your computer (atom, sublime, notepad++ …).

Problem with any of those steps? Check out Jenny Brian Happy git trouble shooting section

4.3 Linking git and RStudio

In most of the cases, RStudio should automatically detect git when it is installed on your computer. The best way to check this is to go to the Tools menu -> Global Options and click on git/SVN

If git is properly setup, the window should look like this:

Click OK.

Note: if git was not enabled, you might be asked to restart RStudio to enable it.

5 First Repository

Although there many ways to start a new repository, GitHub (or any other cloud solutions, such as GitLab) provide among the most convenient way of starting a repository.

5.1 GitHub

Let’s distinguish between git and GitHub:

git: version control software used to track files in a folder (a repository)
- git creates the versioned history of a repository
GitHub: web site that allows users to store their git repositories and share them with others

GitHub is a company that hosts git repositories online and provides several collaboration features (among which forking). GitHub fosters a great user community and has built a nice web interface to git, also adding great visualization/rendering capacities of your data.

GitHub.com: https://github.com
A user account: https://github.com/brunj7
An organization account: https://github.com/nceas
NCEAS GitHub instance: https://github.nceas.ucsb.edu/

5.2 Let’s look at a GitHub repository

This screen shows the copy of a repository stored on GitHub, with its list of files, when the files and directories were last modified, and some information on who made the most recent changes.

If we drill into the “commits” for the repository, we can see the history of changes made to all of the files. Looks like kellijohnson and seananderson were fixing things in June and July:

And finally, if we drill into the changes made on June 13, we can see exactly what was changed in each file:

Getting starting with git and GitHub using RStudio

NCEAS