Appendix B — Setting up Git and GitHub

Published

November 6, 2024

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.4.1 2024-06-14, Race for Your Life (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 20 August 2024, that was 4.3.18.
  • Scroll down to find the “Assets” at the bottom and click on the first line, Homebrew-4-3-18.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: 2024.04.2 build 764 (June 2024) 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 and Configure 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.43.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.45.2, then re-install Git to update it

B.3.2 Install/Update Git

To download or update Git for Mac or Windows, go to Git Downloads and choose your operating system. Follow the instructions on the page and below.

B.3.2.1 Mac

If you have a Mac and use HomeBrew (you should), you can also use brew install git or brew upgrade git as appropriate in a terminal window. When prompted for a password, use the password for your computer.

Important

If you are using homebrew, at the end of a successful install of Git it will tell you to add the new directory to your system path.

To do this, go to a terminal window and enter the following and hit enter.

  • echo "export PATH=/opt/homebrew/bin:$PATH" >> ~/.bash_profile && source ~/.bash_profile

This will allow a terminal window to find the Homebrew version of Git on your computer. Otherwise it will default to the operating system version which is probably older.

  • Use which git and git --version in the terminal pane to confirm what RStudio is using for git.
  • Check your RStudio Tools/Global Options for Git/SVN.
    • Make sure the box is checked for “Enable version control interface for RStudio Projects.”
    • Check your path for “Git Executable”. It may start with ./usr/ or /opt.
    • If it starts with /usr/ and you are using an Intel Mac that is fine.
    • If you are using an Apple Silicon “M” Mac, depending on how you installed it, RStudio may have trouble finding the latest version of Git. If which git and git --version do not show the latest version from Homebrew, you may need change it to the homebrew install location as follows.
    • Click ‘Browse’ next to the path. This will open a Finder window.
    • Use the Finder command Go/Go to Folder or CMD+SHIFT+G to open a Find a Folder window.
    • Enter /opt/homebrew/bin/git.
    • Your pane should look something like Figure B.1 where RStudio has inserted the version in the path alias.
    • Select Apply and then close and restart RStudio.
Image of RStudio Global Options Git/SVN pane.
Figure B.1: Check RStudio Global Options for Git/SVN

B.3.2.2 Windows

Go to the Git for Windows download page: http://git-scm.com/download/win.

  • Download the Installer and open it to start the install process.
    • Choose the default components plus adding a Git bash profile to the Windows Terminal
    • Consider installing Notepad++ for a text editor, then choose it for the default editor.
    • Recommend Override the default branch name to “main”.
    • Select the Git from command line and also from 3rd-party software (the recommended option).
    • Select the default Use bundled OpenSSH unless your work environment requires something else.
    • Select the default Use the OpenSSL library
    • For line endings, select the default Checkout Windows-style, commit Unix-style line endings
    • For terminal emulator, select the default Use MinTTY
    • For git pull, select the Default (fast forward or merge)
    • For credential helper, select the default Git Credential Manager
    • Select the defaults for Configure extra options
    • Do not select any experimental options
    • Select Install.
    • Once the installation is complete, select Launch Git Bash, then click Finish.
  • You should now see a MINGW64 terminal pane that you can use for Bash and Git commands.
  • The standard Windows Command Prompt terminal pane does not recognize all the Bash commands.

Also check that your RStudio Tools/Global Options/Git/SVN has the box checked for “Enable version control interface for RStudio Projects.”

B.3.3 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.3.3.1 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.
##| code-fold: false
##| echo: true
##| eval: false
    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.3.3.2 Windows Users and BASH

  • Ensure Bash is set as the default scripting language for the RStudio Terminal pane.
    1. Go to RStudio main menu Tools/Global Options.../ Terminal.
    2. For New terminals open with: select Bash.
    3. Close the Terminal pane
    4. Restart RStudio.

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

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

  • 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.3.3.4 Mac Users

  • The Mac operating system will create a .DS_Store file for every directory accessed by Finder (see [What is A DS_Store File (How to Open,Hide,Delete & Disable)])(https://iboysoft.com/wiki/ds-store.html) for more about them.
  • These are tiny and normal hidden but they can show up in your RStudio Git Pane.
  • To have Git ignore these files, you can create a .gitignore_global with .DS_Store in it and add that file in your .gitconfig with the following two lines.
    • echo .DS_Store >> ~/.gitignore_global
    • git config --global core.excludesfile ~/.gitignore_global

B.4 Check Your Git Settings

  • 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 the 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 local 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 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 (Optional) Set the Git Text Editor

  • The default editor for Git is Vim. There are newer text editors that may be easier to use.
  • If you have a Windows machine and chose Notepad++ during the install of Git for Windows you are okay. You could also use Visual Studio Code.
  • Mac or Windows users may prefer to switch to a different default editor for Git.
    • See here for commands for using different editors.
  • Recommend Visual Studio (VS) Code as it is also popular with Python and has an extension for Quarto.
    • Download Visual Studio Code
    • Use the commands in your terminal pane to update your hidden .git config file in your home directory.
    • As an example, to use VS Code enter $ git config --global core.editor "code --wait"

B.8 Summary

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

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