Using GitHub for project collaboration

Goal

The purpose of this lab is to help you set up Git and GitHub on your computer, and use them to collaborate on your EDA project.

Task 0: GitHub registration and Git installation

(Note: You were already being asked to complete these prior to the start of the program. Proceed to Task 1 if you already completed this task.)

GitHub account. Register for a (free) GitHub account at https://github.com.
(if you already have a GitHub account, feel free to ignore this)

Download Git.
(if Git is already installed on your computer, the following instructions still hold for updating Git to its latest version)

(Windows)

(macOS)

  • Open the Terminal app on your computer (Finder \(\rightarrow\) Applications \(\rightarrow\) Terminal)

  • Go to https://brew.sh and copy/paste the chunk under “Install Homebrew” to the Terminal

  • Once Homebrew is installed, type this into the Terminal: brew install git

Task 1: Git configuration

  • Make sure you’ve already (i) created a GitHub account and (ii) installed Git on your computer

  • You then need to configure Git. This can be done directly in R:

# uncomment and run the following line to install the usethis package
# install.packages("usethis")
usethis::use_git_config(user.name = "Your Name", user.email = "your-github@email.address")

  • Use your full name for the user.name field and the same email as your GitHub account for user.email

  • You then need to create a personal access token for authentication as follows:

usethis::create_github_token()

  • This will direct you to the GitHub site on your browser (you may have to log in). On this site:

    • Under “Note”, type in some description for this token (e.g., “SURE 2024 GitHub token”)

    • For “Expiration”, set an expiration date for this token (e.g., 90 days) or make it permanent (i.e. choose “No expiration” if you don’t want to deal with this again in the future)

    • Under “Select scopes”, recommended scopes will be pre-selected. Stick with these for now.

  • Next, click on “Generate token”

  • Copy the token to your clipboard (or leave the browser window open, so you can come back to copy the token later)

  • In RStudio, run the following to get a prompt where you can paste your token:

# uncomment and run the following line to install the gitcreds package
# install.packages("gitcreds")
gitcreds::gitcreds_set()

Task 2: EDA project collaboration with Git and GitHub

Make sure every group member finishes Task 1 before proceeding to Task 2, which requires a group effort.

Step 1: Create an EDA project repository on GitHub
(Required for ONE group member only)

Each group should elect ONE person to create a GitHub repository for the EDA project. This repository is to be shared among all group members.

The elected group member should do the following to create a new GitHub repository:

  • After you’ve signed in to GitHub, go to https://github.com/new

  • Name the repository (give it a meaningful name)

  • Give the repository a description (don’t leave this blank although this is optional)

  • Decide whether to keep the repository public or private (for now, keep it public, so that we can review your code)

  • Click on “Initialize this repository with a README”. For now, there’s no need to “Add .gitignore” or “Choose a license”

  • Click on “Create Repository”

Next, to add the rest of your group to the repository:

  • Go to browser page of the GitHub repository you just created and click on “Settings”

  • Navigate to the left sidebar and click on “Collaborators”

  • Click on “Add people” (under Manage access). Enter the GitHub username for the other group members.

Step 2: Clone the remote repository to your local computer
(Required for ALL group members)

  • Everyone (except the member responsible for creating the repository) should each get an invitation sent to the email associated with your GitHub account

  • Check your email and accept the invitation

  • Go to the browser page for the EDA project GitHub repository (created in Step 1)

  • Click on Code (in the same line as “Go to file”). Under HTTPS, copy the URL

  • In RStudio, click on File > New Project.... Next, click on “Version Control” and then on “Git”. Paste the URL you just copied into “Repository URL”

  • Type the name for the folder on your computer associated with this repository into Project directory name

    • You can choose whatever name you want, but it is recommended to give a name similar to the repository name on GitHub

  • Make sure “Create project as subdirectory of:” points to where you want to locate this new folder

  • Click on “Create Project”

  • At this point, you should find that the “Files” pane (in the bottom right of RStudio) is listing the files in your local repository.

Step 3: Modify the repository
(Required for ALL group members)

Each group member should create their own “sandbox” folder locally on their own computer as follows:

  • Navigate to the Files pane in RStudio and click on “Folder” to create a new folder (for the new folder name, use your last name.)

  • In RStudio, open a new file (could be anything - e.g. R Script, Quarto document, etc.). Fill the file with some code/comments/etc. (This is just for illustration purpose, to show how you can add a file to GitHub from your computer)

  • Save the file inside the folder you just created (with your last name as the folder name). At this point, this file should show up in the “Git” pane (in the top right of RStudio)

  • Check the box under “Staged” in the Git pane to stage the file for a commit

  • Click on “Commit” in the Git pane

  • In the new window that opens, add a “Commit message”, then click on the “Commit” button

  • Click on “Push” to push your changes from your local repository to the shared remote repository on GitHub

Step 4: Update the local repository
(Required for ALL group members)

  • First, make sure that everyone in your group have completed Step 3

  • In RStudio, navigate to the Git pane and click on “Pull”. A new window will pop up. Once everything is finished running, close the window.

  • At this point, you should find that your Files pane in RStudio is listing the folders that your group members have created, in addition to your own folder

    • This task is know as git pull, which updates the local repository to match that content of a shared remote repository

Step 5: Start your EDA project

If you encountered no errors then you can feel free to start brainstorming your EDA project with your group.

For this project, we ask you to create/update/save files within your own sandbox folder (that you created in Step 3). This will help mitigate the risk of running into trouble when pushing your files to GitHub, especially for those who are new to Git and GitHub. This also allows us to easily review your code.

Important notes

The GitHub procedure for any project collaboration is

  1. Pull new changes

  2. Make changes on your computer (e.g. create new files, update existing files)

  3. Commit your local changes (Note: this step may be repeated)

  4. Pull again to avoid merge conflicts

  5. Push your commit(s) to GitHub

Advices: Make small, frequent commits. ALWAYS pull before you push.

Ask us for help if you run into any issues or have any questions.