Git and GitHub with RStudio: Installing and Connecting

A one-off setup, with no command line afterwards

NoteWhat this tutorial is for

Getting Git onto your computer and connecting RStudio to your GitHub account, so that version control becomes a set of buttons in RStudio rather than commands in a terminal.

Allow about half an hour. You do this once per computer and then never again.

It assumes R and RStudio are already installed and working.

This tutorial does not cover the common workflows associated with using Git and Github. I will add a post on this shortly.

1 The three things you need

Three names that are easy to confuse, and worth separating before you install anything.

Git	A program on your computer that records the history of a folder. It has nothing to do with the internet.
GitHub	A website that stores copies of such folders, so they survive your laptop and can be shared.
RStudio	An IDE for R. It has buttons that operate Git for you, once Git is installed.

You can think of it like this: Git is the engine, GitHub is the garage, and RStudio is the steering wheel. You install the first, register for the second, and connect the third. But you should be aware that the best way to use Git is via the command line (your terminal). But since this might feel a bit quirky in the beginning, using the Git integration from RStudio works very well for the beginning!

NoteWhy the names look so similar

GitHub is named after Git and was built to host Git repositories. It is, however, not made by the same people who are responsible for Git. Moreover, there are competitors — GitLab, Bitbucket, Codeberg — that do the same job as Github. By the way: Git works perfectly well without none of them. You would simply have no copy anywhere but your own machine, and you couldn’t use the great collaboration features of these platforms.

2 Step 1 — Register at GitHub

If you have not already: go to github.com and create a free account.

Two pieces of advice that are easier to follow now than to fix later:

• Use your university email address. It is what lets you claim the GitHub Student Developer Pack, which is free and includes things worth having.
• Choose a username you would not mind a future employer seeing. This one is a professional profile more often than students expect. Your name, or something close to it, is the safe choice.

TipNote the email you used

You will need it again in Section 5, and it has to match, or GitHub will not connect your commits to your account.

3 Step 2 — Install Git

Git is a separate program from R and RStudio, and this is the only part of the setup that differs by operating system.

Windows

1. Go to git-scm.com/download/win
2. The download starts by itself — a file called something like Git-2.xx.x-64-bit.exe
3. Run it. Accept every default by clicking Next through all the screens, then Install.

The installer asks a lot of questions, several of them about things you have no opinion on. The defaults are correct for our purposes and there is nothing to decide that would matter a lot.

NoteThe one screen that looks alarming

One page asks you to choose a default editor and offers Vim. It does not matter what you pick — RStudio never uses it — but if you leave it on Vim and some other program later opens it, you will be in a text editor with no visible way out. Pick Notepad if it is offered, and the question never arises.

macOS

Apple ships Git as part of its developer tools, which are not installed by default. There is one command involved, and after it a normal graphical installer takes over.

1. Open Terminal (⌘-Space, type Terminal, Enter)

2. Type this, and press Enter:

   git --version

3. One of two things happens:

   • A window appears offering to install the command line developer tools. Click Install, agree to the licence, and wait — it is a large download.
   • Or it simply prints something like git version 2.39.5, in which case Git is already there and you are done with this step.

NoteThis is the only time you use the Terminal

Everything after this happens in RStudio and in your browser. You are using the Terminal here for one line, because it is the thing that triggers Apple’s installer — not because Git needs it.

WarningIf the developer tools installation fails

It sometimes does, usually with a vague network error, and usually on a slow connection. Two alternatives:

• Try again later. It fails intermittently more often than it fails permanently.
• Install Xcode from the App Store instead. It contains the same tools. It is also very large (well over 10 GB), so this is a last resort rather than a first choice.

If neither works, ask for help rather than spending an evening on it.

Check RStudio can see it

Restart RStudio, then look at Tools → Global Options → Git/SVN.

The Git executable field should show a path — something ending in git.exe on Windows, or /usr/bin/git on macOS. If it is empty, RStudio has not found Git: restart the computer, not just RStudio, and look again. If it still fails, try to locate Git yourself and add the path. If it still fails, install Git again. If it then still fails, ask for help!

4 Step 3 — Install the usethis package

In the RStudio console:

install.packages("usethis")

This is what makes the rest of the setup four lines instead of a page of terminal commands. It also brings in gitcreds, which you use in Section 6, so you do not need to install that separately.

5 Step 4 — Tell Git who you are

Every change Git records is signed with a name and an email address. Set them once:

usethis::use_git_config(
  user.name  = "Anna Musterfrau",
  user.email = "anna.musterfrau@stud.uni-flensburg.de"
)

Replace both with your own. Two rules:

• The name should be your real name, as you would want it to appear on your work. It is not a username or a nickname.
• The email must be one registered on your GitHub account — normally the one you signed up with. This is how GitHub knows that a recorded change is yours.

There is no output. Nothing appears to happen, which is correct.

6 Step 5 — Prove to GitHub that you are you

GitHub stopped accepting passwords from programs in 2021. Instead you create a personal access token — a long string that acts as a password for software only.

Create the token

usethis::create_github_token()

Your browser opens on a GitHub form that is already filled in correctly: the right permissions are ticked and a description is set. You do not need to change anything.

1. Optionally set Expiration to a longer period — a semester, or No expiration. The default is 30 days, which will expire in the middle of your work.
2. Scroll to the bottom and click Generate token
3. Copy the string that appears. It starts with ghp_.

ImportantYou see the token exactly once

Leave that page without copying it and it is gone for good — you cannot look it up, only generate a new one. That is a two-minute annoyance, so do not panic if it happens.

Store the token

Back in the RStudio console:

gitcreds::gitcreds_set()

It asks you to paste the token. Paste it and press Enter. It is stored in your operating system’s password manager — the Keychain on macOS, the Credential Manager on Windows — which is why you only do this once.

WarningTreat the token as a password, because it is one

• Never put it in a script, a .qmd, or any other file
• Never commit it, and never paste it into a chat or an email
• If it ever ends up somewhere public, delete it on GitHub and make a new one

Storing a password inside a project that gets uploaded is the single most common serious mistake people make with Git. gitcreds_set() exists so that you never have to write it down.

7 Step 6 — Check that it all worked

usethis::git_sitrep()

This prints a long report. Four lines are important:

── Git global (user)
• Name: "Anna Musterfrau"
• Email: "anna.musterfrau@stud.uni-flensburg.de"

── GitHub user
• Personal access token for "https://github.com": <discovered>
• GitHub user: "amusterfrau"

If the name and email are right and the token line says <discovered>, your setup is complete.

NoteIt prints more than you need, including your token’s permissions

git_sitrep() is a diagnostic, so it reports everything it can find — including which permissions your token carries and which email addresses GitHub holds for you. None of it is secret, but it is not something to show on a shared screen or paste into a public forum.

If you need help and want to send the output to somebody, remove the GitHub section first.

8 What you can do now

Your computer is set up. From here on, in any RStudio project:

usethis::use_git_ignore(c("*.html", "*_files/"))  # first
usethis::use_git()                                # then
usethis::use_github()                             # then

Three lines, once per project, and a Git tab appears in RStudio. Everything after that is clicking: Pull, tick a box, Commit, Push.

ImportantThe order of those three matters

use_git() makes your first recorded snapshot. Anything in the folder at that moment goes into the history, and telling Git to ignore a file afterwards does not remove it.

So if your project already contains rendered output — an .html file, a _files/ folder — deal with that first, with use_git_ignore(). Getting it back out later requires the command line.

NoteIf your course uses a GitHub organisation

Courses often collect work in a shared organisation, so that the teaching staff can see it. In that case use_github() takes an extra argument:

usethis::use_github(organisation = "the-organisation-name")

Note the British spelling, organisation. Without the argument you get a repository in your own account instead, which is easy to fix afterwards but easier to get right first time.

You have to be a member of the organisation before this works. If your course sent you an invitation by email, accept it before you try.

9 When something goes wrong

The five failures that account for nearly everything, and what each one means.

What you see	What is wrong	What to do
No Git tab in RStudio	Git not installed, or no restart, or this folder has no repository	Section 7, then restart RStudio
Git executable field empty	RStudio cannot find Git	Restart the computer; reinstall Git if it persists
Authentication failed	Token missing, expired, or mistyped	gitcreds::gitcreds_set() with a fresh token
Personal access token: <unset>	The token was never stored	Section 6 again
Push rejected, fetch first	The copy on GitHub has changes yours does not	Click Pull, then Push

TipThe most common one, by a wide margin

You opened the .qmd file instead of the project. Git in RStudio attaches to a project, so the Git tab is missing whenever the project is not open.

Close everything, open the .Rproj file, and look again.

NoteReading a Git error message

Git messages are written for people who already know Git, and they tend to explain the situation rather than the fix. Two habits make them usable:

Read the last line first. Git often prints the diagnosis at the bottom, and frequently the actual instruction is on a line beginning hint:.

Your Git may not be in English. If your system is in German, so is Git — Schwerwiegend: Ihr aktueller Branch 'main' hat noch keine Commits. The wording differs, the meaning does not. Find the file name and the verb and ignore the rest.

10 Where to read more

• Happy Git and GitHub for the useR — the standard reference for this exact setup: R users, RStudio, no prior command line assumed. The chapters matching this tutorial, step for step: ch. 4 Register a GitHub account · ch. 6 Install Git · ch. 9 Personal access token for HTTPS · ch. 11 Connect to GitHub
• The usethis setup article — what the four commands above actually do
• GitHub’s own guide to personal access tokens