Setting up GitHub, and Git

ENV 872 - EDA   |   Spring 2024   |   Instructors: Luana Lima,  John Fay  |  

All the lessons, data, and assignments are kept in a GitHub repository. We tend to make changes to these materials as the semester progresses, but GitHub makes it easy to ensure these updates get propagated to everyone in the class. You may disagree with just how “easy “this process is, but at the very least, it gives you experience working with GitHub :smiley:.

The steps below outline the process of creating your own copy of the class materials and integrating this copy with your RStudio session where you’ll do your data analysis. A few importing things to note:

  • You’ll need to do this on a machine (or container) with R, RStudio, and Git installed.
  • If you are using multiple machines to do your work (e.g. bouncing across different NSOE lab machines), you’ll need to repeat a number of these configuration steps. These are marked with a red diamond (:diamonds:).

A thorough guide to using Git & GitHub with R is provided here: https://happygitwithr.com, and we recommend you at least skim this site to see what’s there. Below, however, we’ve streamlined the process needed to get you up and running.

Step 1. Register a GitHub account

Briefly, GitHub is a cloud service that allows you to store project-related files (e.g., R code and related data). These project files are organized as repositories, which you can think of as project workspaces. You’ll learn more about what makes GitHub different from cloud storage services like Box or Dropbox in due time.

To use this resource, you’ll need to create a GitHub account, if you don’t have one already.

  • Before creating an account, consider these tips provided on the Happy Git with R site on selecting a user name.
  • Navigate to https://github.com and click the Sign Up button.

The Git application that we installed previously is designed, among other things, to send files back and forth between your local machine and your GitHub account in the cloud. To enable communication between local machine and GitHub, we first need to tell your local machine about your GitHub account. This is done by storing your GitHub username and email locally as Git global variables. (A more in-depth discussion on this is available here in the Happy Git with R site.)

:diamonds: Because this setting is stored locally, you’ll need to perform this step once on each new machine you work with. So if you move to a different NSOE machine you’ve never been on before, you’ll need to repeat this step. However, if you are using a personal machine, container, or virtual machine, you should only have to do this once.

  1. Open RStudio.

  2. In RStudio, open up the terminal window.

    :point_right: Note the terminal is different than the console ; The terminal should have a $ as the prompt, not a >. If you don’t see a Terminal tab in RStudio (in the lower left quadrant), you can open a new terminal via the Tools>Terminal>New Terminal menu. The difference between the console and the terminal is that you issue R commands at the console, and you issue operating system commands (including Git commands) at the terminal.

  3. Ensure that Git is happy by typing the following in the terminal:

    $ git --version

    This should return the version of Git installed on your machine, e.g. git version 2.39.0.

    If you get an error here, contact an instructor as your Git software is not operational.

  4. Next, you want to tell Git who you are so that Git can connect to our GitHub account. Again in the terminal, run the following commands (using the GitHub name and email you used when setting up your GitHub account, of course…).

    $ git config --global user.name 'Jane Doe'
$ git config --global user.email 'jane@example.com'
$ git config --global --list

    That last line reports what you saved as your global user name and user email variables. If you entered them incorrectly, just run the command again with the corrected info.

Step 3. Allow your local Git session secure access to your GitHub account

Git now knows about your GitHub account in the cloud, but it still lacks the authority to write to your GitHub account. For that, we need to create a special kind of password – called a Personal Access Token – on GitHub and then provide that password to our local machine. Here are the steps involved in this procedure, again discussed in greater detail on the Happy Git with R site (here).

3.1 Creating the Personal Access Token

  • Log into GitHub in your browser.
  • Under your profile icon/picture in the upper right, expand the menu and select Settings.
  • From the list on the right side, select Developer settings at the very bottom.
  • On the page that appears, select Personal access tokens (using the “classic” option).
  • Generate a new token (again, using the “classic” option).
    • Assign a note with this token, perhaps “ENV872”, to remind you what this token is for.
    • Set the token to expire sometime after the end of the semester (e.g. May 31st).
    • For scopes, click the boxes next to:
      • repo
      • workflow
      • user
      • gist
  • Finally, click Generate token,
  • Copy the token somewhere you’ll be able to find again as you’ll need this string to link any new RStudio session to your GitHub account. (I find sending myself a Slack message with this token to be pretty good.)

3.2 Storing your Personal Access Token on your local machine

  • Open RStudio

  • In the console (not the terminal), inter the R command:

    gitcreds::gitcreds_set()

    :rotating_light: If you get the error “Error in loadNamespace(x) : there is no package called ‘gitcreds’”, then you need to install the R package containing the command. To do this run the following at the R console prompt:
    install.packages("usethis")

    Then try the
    gitcreds::gitcreds_set()
    command again.

  • At the prompt, enter your personal access token.


More info on Personal Access Tokens

:diamonds: Your personal access token is stored only on the machine you applied the gitcreds::gitcreds_set() command. If you migrate to a different machine you haven’t previously authenticated; you’ll have to run this command on that machined, again providing your personal access token.

► If you do not run the gitcreds::gitgreds_set() command you can still interact with GitHub; you’ll simply be prompted for your Git username and password. When this happens provide your Personal Access Token as the password (not your GitHub account password).

► If you have run the gitcreds::gitcreds_set() command, and Git still asks for you username and password, check this section on Happy Git with R for tips on how to debug or contact an instructor or TA.

:point_right: For those using R containers

The version of RStudio on the containers stores credentials slightly differently than desktop versions of RStudio. We thus need to run a few additional steps to save our personal access tokens (PATs).

  1. From the terminal, run the command: git config --global credential.helper 'cache --timeout=10000000'.

  2. Then, back in the R console, run gitcreds::gitcreds_set() and provide your token. Run it again to see that it has taken.

For more information see: https://happygitwithr.com/https-pat.html#pat-doesnt-persist-on-linux