Git and GitHub Setup

TipLearning Objectives

After completing this session, you will be able to:

  • Explain what the Terminal is and how it’s relevant to Git setup tasks
  • Describe why it’s important to set a default merge strategy for Git
  • Paraphrase why a Personal Access Token (PAT) is necessary to interact with GitHub from your computer

1 Install Software First!

Important

Before starting this lesson, make sure you have followed all the setup instructions on the course home page!

2 Set Git’s Global Options

Before using Git, you need to tell it who you are, also known as setting the global options. You can do this either with command line code or with the R package usethis. For this lesson we will use the usethis package. However, you can also find the command line code to reference in the future.

NoteWhat’s the Terminal?

Technically, the “Terminal” is an interface for the shell, a computer program. We use the Terminal to directly tell a computer what to do outside of R. This is different from the “Console” in your IDE (Positron, RStudio), which interprets R code and returns a value.

The Terminal should be visible by default in your IDE, but if it is not, you can open it by clicking Terminal New Terminal

A Terminal tab should now be open right next to the Console tab.

TipDon’t Fear the Terminal!

Most of our Git operations will be done with R code, but there are some situations where you must work in the Terminal and use command line. It may be daunting to code in the Terminal, but as your comfort increases over time, you might find you prefer it. Either way, it’s beneficial to learn enough command line and to not be intimidated in the Terminal.

2.1 Configure GitHub Username and Email

To introduce ourselves to git we are going to update our global options with our GitHub user name and email information. We’ll use the R code tab below but check out the terminal tab if doing this via command line is of interest.

ImportantCase and Spelling Matter!

When you add your user.email to the global options you must use an address linked to your GitHub account, otherwise Git won’t be able to sync to your account.

Your user.name is not used for matching Git to GitHub - it is just for helping other people identify you on the commits you write. We recommend using your GitHub user name (e.g., oharac) but you can also use your human name (e.g, Casey O'Hara).

Step 1: Tell Git (1) your GitHub username, (2) your GitHub-associated email address.

usethis::use_git_config(user.name = "my_user_name",
                        user.email = "my_email@nceas.ucsb.edu")
1
Add your GitHub username (recommended) or human name.
2
Add your email address associated to you GitHub account.

Step 2: Define the default name for a branch that gets created when you make the first commit in a new Git repository (a.k.a. “repo”).

usethis::git_default_branch_configure(name = "main")

Step 3: Check to make sure everything looks correct.

usethis::git_sitrep()

Step 1: Tell Git your GitHub username (recommended) or human name. Note that if the code runs successfully, it will look like nothing happened. We will check at the end to make sure it worked.

git config --global user.name "my_user_name"

Step 2: Tell Git your GitHub-associated email address.

git config --global user.email "my_email@nceas.ucsb.edu"

Step 3: Define the default name for a branch that gets created when you make the first commit in a new Git repository (a.k.a. “repo”).

git config --global init.defaultBranch main

Step 4: Check to make sure everything looks correct. The following command return the global options you have set.

git config --global --list
NoteWhy Change the Default Branch Name?

Previously, the default branch name was “master” and this terminology for Git branches is problematic, which motivates us to update our default branch to “main” instead.

2.2 Configure Strategy for Integrating Changes Across Branches

When you’re working on the same GitHub repository as the rest of your team, what happens when you and a teammate edit the same file at the same time? How does Git ‘know’ how to reconcile those differences? Simply put, we tell Git how we want it to make that judgement call!

There are three options, “merge,” “rebase,” and “fast forward.” We recommend that you choose the “merge” strategy as it will seamlessly handle easy situations where human oversight isn’t needed but will flag more nuanced problems (called “merge conflicts”) for you to resolve manually. For more information on “merge” versus “rebase”, see here. You can always revisit this decision later using essentially the same code below!

Set the default strategy for reconciling differences.

usethis::use_git_config(pull.rebase = "false")

Set the default strategy for reconciling differences.

git config --global pull.rebase false

Note: The --global option will set this as default for all repos on your computer. If you forget this, it will only set for the current repo.

WarningWhy did I get this error?

If you forget to set your pull.rebase option, you will get the following error message when you try to sync your local computer with GitHub. Note, the error message gives you the terminal code to fix it!

hint: You have divergent branches and need to specify how to reconcile them.
hint: You can do so by running one of the following commands sometime before
hint: your next pull:
hint: 
hint:    git config pull.rebase false # merge (the default strategy)
hint:    git config pull.rebase true  # rebase
hint:    git config pull.ff only      # fast-forward only
hint: 
hint: You can replace "git config" with "git config --global" to set a default
hint: preference for all repositories. You can also pass --rebase, --norebase, 
hint: or --ff-only on the command line to override the configured default per
hint: invocation.
fatal: Need to specify how to reconcile divergent branches
1
This is the Terminal code to set the “merge” strategy, though we recommend you set this globally using the --global option.

3 Authenticate Your Computer with GitHub

While you will use your GitHub password to log in to your account on a web browser, in order to actually send code you write from your local computer up to GitHub, you’ll need to “authenticate” in a different, more secure way.

The book Happy Git and GitHub for the useR has a wealth of information related to working with Git in R, and the instructions below are based off of Chapter 9: Personal access token for HTTPS in that book.

We will be using a Personal Access Token (PAT) in this course. For better security and long term use, we recommend taking the extra steps to set up SSH keys (check out Chapter 10 Set up Keys for SSH).

TipSetting up Your PAT
  1. Run usethis::create_github_token() in the Console.
  2. A new browser window should open up to GitHub, showing all the “scopes” options. You can review the scopes, but you don’t need to worry about which ones to select this time. The previous function automatically pre-selects some recommended scopes. Go ahead and scroll to the bottom and click “Generate Token”.
  3. Copy the generated token. You will not be able to see this token again (ever) when you leave this page!
  4. Back in the Console of your IDE, run gitcreds::gitcreds_set().
  5. Paste your PAT when the prompt asks for it.
  6. Run usethis::git_sitrep() in the Console to check your Git configuration and that you’ve successful stored your PAT. Note: look for Personal access token for 'https://github.com': '<discovered>'

If you see <unset> instead of <discovered> means your PAT is not correctly set. You’ll need to troubleshoot.

Congrats! Now you’ve setup your authentication you should be able to work with GitHub in your IDE now.