Git and GitHub

EVR 628- Intro to Environmental Data Science

Author
Affiliation

Juan Carlos Villaseñor-Derbez (JC)

Rosenstiel School of Marine, Atmospheric & Earth Science and Institute for Data Science & Computing

Hands-on: Building Your First Repository

The overall flow:

  1. Create a GitHub account (if you don’t have one), install git, authenticate (instructions)
  2. Create a new repository on GitHub
  3. Clone it to your computer
  4. Add your project files
  5. Make your first commit
  6. Push to GitHub

Step 0: Check set up

  1. Make sure you have git. In a terminal (Mac) or Git bash (Windows) run:
which git
/usr/bin/git
  1. Make sure your have introduced yourself to git. To check for your configuration, use this in a terminal:
git config -l
credential.helper=osxkeychain
init.defaultbranch=main
user.email=juancarlos.villader@gmail.com
user.name=jcvdav
core.excludesfile=~/.gitignore
filter.lfs.clean=git-lfs clean -- %f
filter.lfs.smudge=git-lfs smudge -- %f
filter.lfs.process=git-lfs filter-process
filter.lfs.required=true
http.postbuffer=157286400
core.repositoryformatversion=0
core.filemode=true
core.bare=false
core.logallrefupdates=true
core.ignorecase=true
core.precomposeunicode=true
remote.origin.url=https://github.com/jcvdav/EVR_628.git
remote.origin.fetch=+refs/heads/*:refs/remotes/origin/*
branch.main.remote=origin
branch.main.merge=refs/heads/main
branch.main.vscode-merge-base=origin/main
pull.rebase=true
branch.dev.remote=origin
branch.dev.merge=refs/heads/dev
branch.test.remote=origin
branch.test.merge=refs/heads/test

You should see your user.name and user.email listed, typically at the bottom.

Step 1: Create a GitHub Repository

  1. Go to github.com and sign in
  2. Click the “+” icon in the top right
  3. Select “New repository”
  4. Choose a simple name: EVR_628
  5. Add a description: “Learning how to use GitHub”
  6. Make it Public
  7. Check “Add a README file”
  8. Select gitignore tailored to R
  9. Click “Create repository”

Step 2: Clone to Your Computer

In RStudio:

  1. Top-right corner, then “New Project”
  2. Choose “Version Control”
  3. Select “Git”
  4. Paste your repository URL
  5. Choose where to save it locally
  6. Click “Create Project”
  7. Verify that you now have a README.md and .gitignore files

Step 3: Set Up Your Project Structure

To create these folders in your repository:

environmental-data-project/
├── data/
│   ├── raw/
│   ├── processed/
|   └── output/
├── scripts/
│   ├── 01_processing/
│   ├── 02_analysis/
│   └── 03_content/
├── results/
│   ├── img/
│   └── tab/
├── docs/
└── README.md

Use:

EVR628tools::create_dirs()
TipThe namespace

When you only want to use a function from a package, we can avoid loading the library with library(package_name) and instead directly access the function via it’s namespace. Here, we say package_name::function_name().

Step 4: Create / Modify the Global and Project .gitignore Files

  1. We will use the usethis::git_vaccinate()
  2. Look at the documentation using ?usethis::git_vaccinate()
  3. Call usethis::git_vaccinate()
Tip

You can always add specific files or folders by editing the .gitignore file or using the git pane

Step 5: Add Your First “content”

  • Create a simple R script in scripts/content/my_first_plot.R
  • Copy the code below and paste it in the script
# Load packages
library(EVR628tools)
✔ ✔ ✔ You sucessfully loaded the EVR628tools package ✔ ✔ ✔
library(tidyverse)
── Attaching core tidyverse packages ──────────────────────── tidyverse 2.0.0 ──
✔ dplyr     1.2.1     ✔ readr     2.2.0
✔ forcats   1.0.1     ✔ stringr   1.6.0
✔ ggplot2   4.0.3     ✔ tibble    3.3.1
✔ lubridate 1.9.5     ✔ tidyr     1.3.2
✔ purrr     1.2.2     
── Conflicts ────────────────────────────────────────── tidyverse_conflicts() ──
✖ dplyr::filter() masks stats::filter()
✖ dplyr::lag()    masks stats::lag()
ℹ Use the conflicted package (<http://conflicted.r-lib.org/>) to force all conflicts to become errors
# Load data
data(data_lionfish)

# Create a simple plot
p <- ggplot(data_lionfish,
            aes(x = total_length_mm, y = total_weight_gr)) +
  geom_point()

p

# Save plot
# The above shouldn't work, why?
ggsave(plot = p, filename = "results/figures/first_plot.png")
Error in `ggsave()`:
! Cannot find directory 'results/figures'.
ℹ Please supply an existing directory or use `create.dir = TRUE`.

Step 6: Update Your README

Create a comprehensive README.md

# My repo for EVR 628

## Author

[Your Name and email? GitHub username?]

## Description

Analysis of environmental data for EVR 628 course.

## Project Structure

- `scripts/`: R scripts for analysis
- `results/`: Output figures and tables

Step 7: Stage-Commit-Push

  1. Stage and then commit your R script
  2. Push
  3. Stage and then commit your README
  4. Stage and then commit your plot
  5. Push

Now Let’s Collaborate

1) Simple collaboration

  • Find a partner
  • Decide who will be partner A and who will be partner B

Partner A

  1. In your repo’s page on GitHub, go to settings -> collaborators -> Add collaborator
  2. Add partner B’s username and send an invitation
  3. Wait until B tells you they are done.

… wait until partner B tells you…

  1. Pull

Partner B

  1. Give partner A your username
  2. Check your email and accept the invite
  3. Go to the repository
  4. Repeat the cloning process:
  • You will have a new project
  • Use a different location (I suggest desktop so you can delete it once you are done)
  1. Make one change to partner A’s figure, and update the exported image (e.g. xlab(Total Length (mm)) or color = "blue"…)
  2. Stage the files, then commit, and push
  3. Tell partner A you are done

Changes to make by B:

# Example: environmental_data_analysis.R
library(EVR628tools)
library(tidyverse)

data(data_lionfish)

# Create a simple plot
p <- ggplot(data_lionfish,
            aes(x = total_length_mm, y = total_weight_gr)) +
  geom_point(color = "blue") +  # <--- This is one change
  xlab("Total Length (cm)")     # <--- This is another change

p

  • Now switch who is A and who is B and repeat