Appendix B — Setting up Git and GitHub

Published

January 8, 2026

B.1 Learning Outcomes

  • Install and Configure Git Version Control System on your computer.
  • Establish a GitHub account
  • Authenticate between the Git on your computer and your GitHub account using the GitHub Credential Manager.

References

B.2 Update R, RStudio, and your R Packages

B.2.1 Update Your Version of R.

Check your version of R when you start RStudio by looking at the Console pane start up message or entering R.Version().

  • It should be at least R version 4.5.2 2025-10-31, “[Not] Part in a Rumble” (or higher).
  • If not, go to CRAN and get the latest version for your OS.
  • If you had to update to a major new release you may have to re-install your packages to go with the new version.

B.2.2 Optional Downloads If You Are Using a Mac …

B.2.2.1 Recommend Installing Homebrew

Homebrew is a general package manager for the Mac OS (and Linux) to enable you to install/update a wide variety of developer-type software not generally available in the Mac App Store.

  • The Brew Project helps developers write scripts to ease the installation of their applications using a standard structure called a “Formula” or a “Cask”. See brew cask VS brew formula.

Go to Homebrew Installation and install in the default location.

An easier installation might be to select the link for “try our new .pkg installer. Download it from Homebrew’s latest GitHub release.”

  • This will take you to the GitHub to the page with the newest release.
  • As of 06 January 2026, that was 5.0.9.
  • Scroll down to find the “Assets” and click on the first line, Homebrew-5.0.9.pkg (or a later version number).
  • This will download the install package which you can open and install as with other Mac applications.

Homebrew installs in different locations based on the type of chip in the Mac so you must add it to your path.

  • If you are not sure of your chip, click on the top left Apple icon and select About this Mac. If it is a newer Mac, the Chip name should have an M in it which is an “Apple Silicon” Mac. Older Macs should say “Intel”.

To add Homebrew to your PATH, run the the appropriate line below in the terminal pane to add your shell profile:

  • Apple Silicon: eval "$(/opt/homebrew/bin/brew shellenv)"
  • Older Apple Intel: eval "$(/usr/local/bin/brew shellenv)"

Run brew help for basic information.

Installing Homebrew could take a few minutes but it can save you a lot of time later on.

B.2.2.2 Consider Downloading XQuartz

Per the Mac OS release notes, the default install of R includes Tcl/Tk 8.6.12 X11 libraries which are optional (in case someone plans on doing specialized coding using TclTk which is not required in this course).

To use {tcltk} requires as a Tcl/Tk Interface requires downloading the XQuartz app.

  • Should be at least version 2.8.5 which was released on 2023-01-26 for Mac OS 10.9 and later.

B.2.2.3 Consider Downloading XCode and the GNU Fortran Compiler.

Per the Mac OS release notes R code and some packages use Xcode 14.2/14.3 and GNU Fortran 12.2 in their development and compilation.

If you want to compile R packages from binary (not required for this course) you will need to have these installed.

  • You can install the complete Xcode Developer Tools through the Apple store (which takes a while).
  • For more details, see R for macOS Developers Tools

B.2.3 Update Your Version of RStudio

Check your version of RStudio using Help - About RStudio or Check for Updates.

  • Your version should be at least Version: 2026.01.0 build 392 (January 2026) or higher.
  • If not, go to RStudio Desktop to download the latest version.
  • Install and restart RStudio

B.2.4 Update Your R Packages

Select the Packages pane in RStudio and click on Update.

  • You can Select All or choose individual packages to update. Be sure to check any tidyverse packages.
  • If asked “Do you want to install from sources the packages which need compilation?” enter No.
  • Restart R.

B.3 Install or Update Git

Git is a version control system for managing changes across multiple versions of documents/code in a repository you have created.

B.3.1 Check if Git is Already Installed

Git is commonly installed on many computers as part of the operating system.

  • To check if you have Git installed.
    • Go to the Terminal pane in RStudio (next to Console) or open a new one with Tools/Terminal/New Terminal
    • Enter git --version in the terminal pane.
    • If Git is installed, you will get a version number such as 2.52.0.
  • If the response is blank or something like git: command not found, then install Git as below.
  • If the Version number is lower than 2.52, then re-install Git to update it

B.3.2 Install/Update Git

To download or update Git for macOS or Windows, go to: https://git-scm.com/downloads

Choose your operating system and follow the instructions on the page, along with the guidance below.

  1. Install or update Git using Homebrew by using the terminal:
brew install git
# or
brew upgrade git

When prompted for a password, use your computer login password.

Important

On current versions of macOS, the default shell is zsh, not bash.
On Apple Silicon Macs, Homebrew installs binaries under:

/opt/homebrew/bin

This directory must be on your computer’s PATH for the Homebrew version of Git to be used.

After an install Homebrew may instruct you to add its binary directory to your PATH. To do so, run the following commands in a terminal:

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

This ensures:

  • Homebrew’s version of Git is found first
  • The change persists across terminal sessions
  • The change is applied immediately
  1. Verify Git in RStudio by using the Terminal pane to run:
which git
git --version
  1. Check RStudio Git Settings in Tools → Global Options → Git/SVN

Confirm the following:

  • Enable version control interface for RStudio Projects is checked
  • The Git executable path is populated

Path guidance:

  • /opt/homebrew/bin/git — Homebrew on Apple Silicon
  • /usr/bin/git — acceptable on Intel Macs
  • /usr/local/bin/git — Homebrew on Intel Macs
  1. Install Git for Windows by downloading it from: https://git-scm.com/download/win

Installer recommendations:

  • Use default components
  • Add Git Bash to Windows Terminal
  • Consider installing Notepad++ (you can change later)
  • Override default branch name to main
  • Select Git from command line and 3rd-party software
  • Use bundled OpenSSH
  • Use OpenSSL
  • Checkout Windows-style, commit Unix-style line endings
  • Use MinTTY
  • Use default git pull behavior
  • Use Git Credential Manager
  • Do not enable experimental options
  1. Verify Git in RStudio by using the Terminal pane to run:
which git
git --version

Typical paths:

C:/Program Files/Git/bin/git.exe
C:/Program Files/Git/cmd/git.exe
  1. Check RStudio Git Settings at Tools → Global Options → Git/SVN

Confirm:

  • Enable version control interface for RStudio Projects is checked
  • A Git executable path is present

B.3.3 Summary

  • Use official Git downloads or Homebrew on macOS
  • Verify Git with which git and git --version
  • Ensure RStudio Git/SVN options are enabled
  • Apple Silicon Macs typically require /opt/homebrew/bin/git
  • Windows users should rely on Git for Windows defaults
  • Restart RStudio after changing Git paths

B.4 Update your Git Configuration using Git

Git uses a global config file that is hidden in your home directory to track many configuration settings (on a Mac the home directory is typically ~\Users\username).

B.4.1 Set Your Name and Email to “sign” commits

  • To configure Git to use your name and email address, open up a terminal pane in RStudio and enter each of lines below (replacing the text with your actual name and email address).
Important

Be sure to use the same email address you will use to sign up for GitHub!

  • You can always adjust your configuration later as Git and GitHub must use the same email so you and others can see your Git activity on GitHub.
git config --global user.name "YOUR FULL NAME"
git config --global user.email "YOUR EMAIL ADDRESS"
  • If you are worried about email privacy, follow GitHub’s instructions here.

B.4.2 Confirm Your Terminal Scripting Language

By default, modern versions of macOS use zsh (Z shell) rather than Bash. To ensure consistent behavior between the system shell and the RStudio Terminal, zsh should be selected as the default shell.

To configure zsh as the default scripting language for the RStudio Terminal:

1.  Open RStudio
2.  Go to Tools → Global Options… → Terminal
3.  For New terminals open with, select zsh
4.  Close the Terminal pane
5.  Restart RStudio

After restarting, all new terminal sessions opened within RStudio will use zsh, matching the default macOS shell environment.

On Windows, RStudio may be configured to use PowerShell or another shell by default. For Git workflows, it is strongly recommended to use Bash, which provides consistent behavior with Git documentation and examples.

To set Bash as the default shell for the RStudio Terminal:

1.  Open RStudio
2.  Go to Tools → Global Options… → Terminal
3.  Under New terminals open with, select Bash
4.  Close the Terminal pane
5.  Restart RStudio

After restarting, any new terminal opened in RStudio will use Bash, ensuring compatibility with Git commands and scripts used throughout this guide.

B.4.3 Add Color to your Git Responses in the terminal windows.

If you do not see a Terminal Window tab pane, use Tools/Terminal/New Terminal to open one.

  • Use git config --global color.ui auto to enable some color in the output from git commands.
  • Use git config --global color.ui false to turn off colors.

B.4.4 Set Default Branch Name to “main”

GitHub now defaults to “main” as the name for the top level branch in a repository but Git uses the historical name “master”

To avoid confusion and prevent mismatches in new repositories set the Git default name to “main” to align with GitHub.

git config --global init.defaultBranch main

This is now the standard practice.

B.4.5 Enable Helpful Status Information

Git is not known for producing clear or user-friendly output by default, especially for new users.

  • The git status command, while extremely important, can be verbose and difficult to scan quickly.

To make Git’s status output more informative and easier to read, you can enable the following options:

git config --global status.short true
git config --global status.branch true

This switches git status to a concise, two-column format

  • Displays each file on a single line
  • Uses short status codes (e.g., M, A, ??) instead of full sentences
  • Makes it much easier to scan changes in larger projects

You can revert to the default output at any time by setting either option to false.

B.4.8 Install and Configure VS Code as the Git Editor

Tip

Git frequently requires user input for actions such as writing commit messages, editing merge commits, or performing interactive rebases. When no editor is explicitly configured, Git falls back to a default editor that is often difficult for new or infrequent users.

  • On macOS and Linux, the default Git editor is typically Vim.
  • On Windows, the default may be Notepad, Vim, or Notepad++ (if selected during Git for Windows installation).

Unless you are already comfortable with Vim, it is strongly recommended to use Visual Studio Code (VS Code) as the Git editor.

VS Code is modern editor that is widely used to supplement IDEs for working with Git.

  • Visual Studio Code is not the same as the full Visual Studio IDE. VS Code is a lightweight, cross-platform editor that works extremely well with Git.

  1. Install Visual Studio Code by downloading for your platform from https://code.visualstudio.com/download.

  2. Enable the VS Code command-line launcher (one-time setup)

Open Visual Studio Code and then:

  • Open the Command Palette
    • macOS: Cmd + Shift + P
    • Windows: Ctrl + Shift + P
  • Run:
    Shell Command: Install ‘code’ command in PATH
  • Restart your terminal

Verify installation:

code --version
  1. Configure Git to use VS Code as its editor by running the following command in a terminal:
git config --global core.editor "code --wait"

Verify:

git config --global core.editor

You should see:

code --wait

B.4.8.1 When Will VS Code Open?

Once configured, VS Code will automatically open for Git operations that require text input, including:

  • Creating a commit without a message: git commit.
  • Editing the most recent commit message: git commit --amend
  • Performing an interactive rebase: git rebase -i HEAD~3
  • Writing merge commit messages
  • Squashing or rewording commits

B.4.8.3 Summary

  • VS Code provides a far better Git editing experience than Vim or nano for most users
  • It works consistently on macOS and Windows
  • It eliminates friction during commits, rebases, and merges
  • This configuration only needs to be done once

B.4.9 Check Your Git Configuration Settings in the Terminal Pane

  • To confirm your global settings, enter git config --global --list
  • To check all settings, enter git config --list --show-origin
    • Hit enter to scroll down till you get to the end.
    • If you are not in a repo, you will see the contents of the global .gitconfig file in your home directory.
    • If you are in a Git repo, you will see the contents of the .gitconfig file in your home directory and the contents of the .git/config file for the repo.
    • If you see a : at the bottom of your screen, hit Enter to scroll to see the next page.
    • When finished, Enter q to quit reading and get your terminal pane cursor back.

B.5 Create and Configure Access to GitHub

GitHub provides cloud-based support for storing and sharing Git repositories.

B.5.1 Create an Account on GitHub:

Go to https://github.com/, enter your email address and select Signup for GitHub.

  • Select a free plan.
  • If asked for a billing address, use the same email address you used to create your account (no charges will be billed).
  • Choose your GitHub ID or username,
    • “Choose Wisely” - you might use this for professional purposes.
    • Please include your initials or part of your name to start it (e.g., my AU account username is “rressler”).
    • I would recommend against something like “richard_awesome_granddad”.

B.5.2 GitHub Account Authentication

GitHub now requires Two-Factor Authentication (2FA) for contributing code to repositories. Your user name and password are not sufficient.

There are several options for Configuring two-factor authentication for GitHub.

  • GitHub recommends a time-based one-time password (TOTP) application. AU uses the Duo TOTP and you can add an account for GitHub on it. See Configuring 2FA using a TOTP app.
  • GitHub also accepts a Passkey. See Configuring 2FA using a passkey
  • If you use the GitHub mobile app you can also log in to use the app for 2FA as well.

These options will allow you to interact with GitHub.

However, you must also establish an authentication credential between your local Git on your computer and your remote GitHub account in the cloud.

B.6 Authenticating Between Git and GitHub

While you can go through 2FA each time you want to interact with GitHub, you can use your computer’s credential manager to streamline the interactions.

  • GitHub supports several security approaches. We will be using the GitHub HTTPS approach to authenticate with our remote repositories.

The Git Credential Manager (GCM) is a multi-platform tool to help Git users authenticate with GitHub through their local machine’s credential manager.

  • If you have a Windows machine, GCM is already included in Git for Windows. When you were installing Git for Windows, you should have selected GCM (it’s the default) as the Credential Helper

  • Mac users (and Windows users who are unsure) should go to the Git Credential Manager Install Instructions and follow the instructions for your platform.

  • If it asks for your password, use your local computer password.

Once GCM is installed, it will open when you first push code to GitHub so it can authenticate you and create the linkage with your local Credential Manger, e.g., KeyChain on a Mac.

  • When you next try to clone a repo from GitHub or upload code to a GitHub repository (a git push), a window will pop up asking you to authenticate using a browser or a code.
  • Choose the browser.
  • If you are not already logged into GitHub with the same email, it take you through the 2FA process you have established, e.g., ask for your Passkey.
  • Assuming success, the GCM will take care of future authentication for you.
Important

If you have not authenticated yet, when you try to clone or push, the terminal pane may ask for your GitHub username and password.

  • The terminal will allow you to enter them (the password will be concealed so it does not look like you are typing).
  • However, it will fail as the terminal does not support two-factor authentication.
  • If this happens, install (re-install) the Git Credential Manager and try again.

B.7 Checking Git and GitHub with Positron

If you have already completed the prior steps to update and configure Git and GitHub you should be ready to use them with Positron.

  1. Check your Git version and configuration by opening a terminal in Positron (bash or zsh) and entering
git --version
git config --global user.name
git config --global user.email

You should get the same responses you got previously.

  1. Confirm Positron recognizes a repository

Once you have created a Git repository, use Positron to

  1. Use the Explorer icon to open a folder that is a Git repo (has a .git/ directory). 2. Click Source Control (the Git branch icon). 3. You should see:
  • Changed files list
    • Staging area
    • Commit message box
    • Remotes/branch status

If Source Control shows “Initialize Repository” for a folder you believe is already a repo, you are likely not opened at the repo root (common student issue) or you opened the wrong folder.

Positron vs. RStudio: How Projects and Repositories Are Detected

RStudio is built around the concept of an RStudio Project (.Rproj). When you open a project, RStudio treats that directory as the authoritative root for your work. Git integration is anchored to the project root, and the Source Control GIT pane assumes the project directory corresponds to a single Git repository.

Positron takes a different approach. It does not use or rely on project files such as .Rproj to define the root of a project.

Instead, Positron determines context based on the folder you open and the presence of specific files or directories within that folder, most notably the .git/ directory that identifies the root of a Git repository.

As a result, Positron’s Source Control view is sensitive to which folder is opened:

  • If you open a sub-directory inside a repository rather than the repository root, Positron may not detect the existing Git repository and will instead offer “Initialize Repository.”
  • This does not mean the repository is missing; it usually indicates that the wrong folder level was opened.
  • This difference can trip up users who are accustomed to RStudio projects.

When working in Positron, use the Explorer icon to always open the repository’s top-level (root) folder, the directory that contains the .git/ folder, even if the file you want to edit is in a sub-folder such as analysis/ or data/.

  • Once the repository root folder is open, you can use the Explorer panel to navigate to any sub-folder and open the specific files you want to work on.

B.8 Summary

  • You should now have updated versions of R, RStudio, and your current packages.
  • You should have a version of Git (>= 2.52.0) on your computer that is configured for your use. Check the version with git --version in the terminal pane.
  • The RStudio Terminal Pane should be configured to open with Bash (Windows) or zsh (Mac OS).
  • You should have a working GitHub account and be able to store a credential in your computer’s credential manager.

Congratulations! You are ready to learn how to use Git and GitHub to manage and collaborate on your work.