Git & GitHub

version control, github, rstudio integration

2026-01-13

Housekeeping

• Accountability plans due YESTERDAY
• Make sure you have GitHub account created
• RStudio + Git setup: happygitwithr.com

Why Version Control?

Final_NDrevisions-finalmarch22_FINALFINAL.docx

PhD Comics: notFinal.doc

Version Control Basics

• Minimally:
  • What changed?
    • additions, deletions, modifications
  • When?
    • timestamp for each change
  • Who changed what?
    • track author contributions in collaborative work
  • Revert changes!
    • go back to any previous version instantly

Google Doc version history

“version control” is basically a system for keeping track of changes to files over time. A very simple and user-friendly version control system is what you’ll find in the “version history” of edits on a google doc.

Git Version Control

Git is a robust version control system designed for text-based files

What? When? Who? Revert! plus:

• Which change is this?
  • unique IDs for every revision
• Why did it change?
  • commit messages explain purpose
• Branch and merge
  • work on multiple features simultaneously
• Backup
  • project (aka repository) history lives in multiple places
• Asynchronous collaboration
  • identify and resolve conflicting changes
• Integration
  • with IDEs (e.g., RStudio) and cloud services (e.g., GitHub)

Git commit history

Version control is like having a complete backup of every version of your project, plus a detailed log of what changed and why. It’s not just for programmers - anyone who works with files that change over time benefits.

Git Repositories

A repository (or “repo”) is a project folder tracked by Git. Everything Git does is centered around repos.

Git repos can be local (on your computer) or remote (hosted on a server like GitHub).

Any folder on your computer can be turned into a Git repository (i.e. “initialized”), but a well-organized repo typically includes a few key components:

• Project files (e.g., scripts, data, documents)
• Metadata files (hidden files and directories that Git uses to manage version control)
• Bespoke files like README.md, .gitignore, and .yml files (more on these later)

Git ≠ GitHub

GitHub: a web-based platform for hosting public and private Git repositories.

GitHub and Git are related, but not the same thing.

Git

• Version control system
• Tracks changes in metadata files
• Your files + metadata files = project repository (aka “repo”)
• Repos stored locally on your computer
• Works offline
• Free & open source
• The standard for version control

GitHub

• Web-based hosting service
• Cloud storage for Git repositories
• All repo contents, full history, additional features
• User-friendly web interface for Git
• Collaboration tools
• Free and paid features
• One of many Git hosting services

Education users (anyone with a .edu address) can access premium features for free.

GITHUB is designed to promote code sharing and collaboration, but very useful for individuals, too.

Analogy: Git is like a local photo album, GitHub is like syncing to icloud or dropbox.

Git does the version control work on your computer. GitHub is just one place to store and share your Git repositories online. There are alternatives like GitLab, Bitbucket, etc.

GitHub Features

In this class we’ll use GitHub to:

• Maintain all class materials
• Create and share your work
• Submit assignments using pull requests
• Collaborate on group projects

But GitHub offers many more features, including:

• GitHub Pages
• GitHub Copilot
• Actions
• Projects
• Codespaces
• Issues

Some of these extras you’ll be able to play around with during this course, but they won’t be explicitly part of the syllabus. Developing familiarity with these features can contribute to the engagement portion of your grade.

• GitHub Pages to host websites directly from a repository
• GitHub Copilot to assist with code generation and suggestions
• Actions to automate workflows
• Projects to organize and prioritize work
• Codespaces to provide cloud-based development environments
• Issues to track bugs and feature requests

Git Fundamentals

Git Vocab: Repo-level

• Repository or repo
  • a project folder tracked by Git
• init
  • initialize a new Git repository
• clone
  • create your own personal copy of an existing repository
• fork
  • copy a repository keeping a connection to the original
• branch
  • create your own temporary line of work in a repo
• checkout
  • switch between branches in a repo

Repo: A directory (i.e., folder) the holds all documents and document edits associated with a project Init: Initializing a repo, making an existing directory ready to work with git (RStudio will do this for you) Clone: Copy an existing repository, creating a fully distinct and separate repo that you own and control Fork: Copy an existing repository, maintaining a connection to the original; you have full control over your fork, but not the original repo Branch: Create an isolated segment of a repo (that you own), so that you can make many changes before combining it back with the original (for collaboration) Checkout: Swap between different branches of a repo

Git Vocabulary: File-level

• stage
  • prepare changes for commit
• commit
  • save a snapshot of changes with a descriptive message
• fetch
  • get latest changes from remote repo without merging
• merge
  • combine changes from different branches
• pull
  • get latest changes from remote repo (=fetch+merge)
• push
  • send your commits to remote repo
• merge conflict
  • conflicting changes that need manual resolution

Stage: The process of selecting which changed files to include in the next commit

Commit: A snapshot of changes in the repo; documented with an informative note left for posterity called a commit message

Pull: Synchronizing your local repo with latest changes from a remote server (like Github)

Push: Sending your commits (and the changed docs) from your local repo to the remote server

Diff: The process run by git comparing and combining old and new files when you push changes

Merge: The resulting process of a diff, where multiple versions of a file are intelligently combined

Merge conflict: Error (recognized in the diff) where multiple changes to any single line of text can’t be automatically resolved and require user decisions

Commits: Snapshots in Time

A commit is the metadata associated with a change.

commit UNIQUE ID HASH
Author: YOUR NAME <YOUR@EMAIL.ADDRESS>
Date: FULL DATE & TIMESTAMP
    
    ONE LINE SUMMARY OF CHANGE(S)
    
    - OPTIONAL
    - DESCRIPTIVE
    - DETAILS

commit a3d2f1b
Author: Natalie Dowling <ndowling@uchicago.edu>
Date: Mon Jan 20 14:30:15 2026
    
    Add data cleaning script for survey responses
    
    - Remove duplicate entries
    - Standardize column names  
    - Handle missing values in age variable

Commit Messages: Best Practices

Good commit messages:

• Describe what and why, not how
• Start with a present tense verb (“Add”, “Fix”, “Update”)
• First line under 50 characters

Add data cleaning script for survey responses

Move glms out of qmd into a separate script

Start zero-drafting methods

Bad commit messages:

• Vague
• Uninformative
• Cover way too many or unrelated changes

Updates to data

Friday afternoon commit

data cleaning script, move glms, start methods, fix typos, add bibliography

A shameful confession

I am a total hypocrite and rarely follow these guidelines. Actual commits from my actual repos:

oops i broke the kid data but the adult glms work now; omg i can't anymore here are some broken plots fix this later or don't i don't care; i need a drink

I’m not proud, but what matters is that you 1) commit often and 2) write messages that make sense to anyone who has to read them (including, hopefully, future you).

I am a total hypocrite and rarely follow these “good” and “bad” guidelines. The longer I work, the more likely my commit messages devolve into oops i broke the kid data but the adult glms work now or omg i can't anymore here are some broken plots fix this later or don't i don't care or i need a drink.

These are actual commits from my actual repos. I’m not proud. Present-me is often pretty frustrated with past-me’s choices, but I can’t pretend that I don’t also find it entertaining and humanizing. (You’d think I wouldn’t need to humanize myself to myself, wouldn’t you? You’d be wrong.)

While I encourage you to do as I say, not as I do, what actually matters is that you 1) commit often and 2) write messages that make sense to anyone who has to read them (including, hopefully, future you).

Git(Hub) cardinal rules

Your workflow:

Commit little & commit lots

1. Pull before you start editing
2. Commit often as your work
3. Push when you close your session

Thou shalt:

• Use frequent, informative commit messages
• Use a .gitignore to specify files and filetypes to keep local
• Maintain a README.md file documenting your repo’s structure and purpose
• Be intentional managing public and protected files

Remember the whole point of GitHub is version control!

Each assignment has a unique repo. Each repo is a unique files.

Never create multiple copies of the same files!!!

Commit little; commit often

“little” as in the commits themselves are little changes

Use a .gitignore to specify files and filetypes that should not be included in pulls or pushes Maintain a README.md file providing at least minimal documentation of the structure of your repo and purpose of the project Make purposeful and wise decisions about managing public, private, and protected data and files Use informative commit messages Pull before you start editing; commit as you work; push when you close your session

Remember the whole point of github is version control!

Each assignment has a unique repo. Each repo is a unique files.

Do not create multiple copies of the same files!!!

Your repos are the homes of your projects, not a random collection of notes and homework. Keep them organized, future-proof, and collaborator-friendly for contexts beyond this class.

This means you should have way more commits than pushes. Each commit is a snapshot of your project at a specific point in time. Pushing sends all your committed changes to GitHub.

Merge Conflicts

merge conflict: Git cannot automatically reconcile differences between two versions of a file

Symbols like <<<, ===, and >>> mark conflicting sections.

All you have to do is change the text and delete the markers.

What you’ll see in a conflicted file:

<<<<<<< HEAD
This is the original line in the file.
=======
This is the conflicting change made by another user.
>>>>>>> feature-branch

You manually edit the file to resolve the conflict:

This is the original line in the file.
This is the conflicting change made by another user.

A merge conflict occurs when Git cannot automatically reconcile differences between two versions of a file. You’ll see symbols like <<<, ===, and >>> marking the conflicting sections. All you have to do is change the text and delete the markers.

Git in the Command Line

Local git repos are managed through the command line (Terminal on Mac, Git Bash on Windows)

Step 1: Set up your local workspace

# navigate to local repo directory
cd repos/d2m-r/slides

# get latest changes from upstream repo
git pull origin main

Step 2: Do stuff. Make changes, additions, whatever in the repo files

Step 2.5: Commit your work frequently after every “nameable” change.

# commit staged changes with "m"essage
git commit -m "Create first draft for GitHub lecture"

Step 3: Send your committed changes back to the remote repo

# send commits to upstream repo
git push origin main

Local git repos are managed through the command line (Terminal on Mac, Git Bash on Windows). The process of sitting down to work, pulling from an upstream repo, making a few changes, adding those edited files to the staging area, committing with a brief commit message, and then pushing to upstream at the end of your work session might look something like this.

Git in RStudio: git pane

The git pane displays a list of all tracked files in your repo, along with their current status.

1. Pull: get latest changes from remote repo
2. Stage: select files to include in next commit
3. Commit: save a snapshot of staged changes with a descriptive message
4. Push: send your commits to remote repo

In D2M-R, you’ll interact with Git through RStudio rather than Terminal or Command Prompt.

You’ll mostly use the Git pane, which gives you a pretty user-friendly interface for the same commands you would run in the terminal.

But you can also use the Terminal tab in RStudio to run git commands directly, exactly as you would in a standalone terminal.

You’ll need this for more advanced tasks like resolving merge conflicts, but you can always opt to use it instead of the interface if you prefer.

• Clicking the down arrow icon allows for pulling with “rebase”

Git in RStudio: git window

The git window opens when you click commit, diff, or history. It includes everything from the pane, plus:

• Diff viewer: see line-by-line changes in selected files
• Revert button: reset local changes in selected files back to their last commit
• Ignore button: add selected files to your .gitignore and remove them from your staging area
• Commit message box: write descriptive messages for your commits
• Commit history: view past commits and their messages, where you can revert the whole repo

When you click the commit button in the git pane, it opens the git window.

You can make multiple commits at once by staging (checking off) only a subset of files that have related changes. Describe the changes and commit. You’ll see leftover files in the git pane that you can stage and commit separately. This avoids overly broad commit messages that cover unrelated changes.

Git Project Components

What literally goes in your git repo?

Repository Structure

A typical Git repository includes:

• Project files
  • The actual content of your project (e.g., scripts, data, documents), organized in a logical folder structure
• Metadata files
  • Hidden files and directories (like .git/) that Git uses to manage version control
• README.md
  • A markdown file that provides an overview of the project, instructions for use, and other relevant information
• .gitignore
  • A text file that specifies which files or directories Git should ignore
• Configuration files (as needed)
  • Things like .yml options, bibliography files, themes, etc.

Repo Structure: Example 1

Project file directories

1. /localonly: only present in your local R Project, listed in your .gitignore and never synced to github
2. /data: .csv/tabular data files for all raw or intermediate datasets read into in your .qmd, optional /raw subfolder for raw data read (only) into unsourced R scripts
3. /source: .R scripts to be called in an early chunk of your .qmd, e.g., stylistic preferences, functions, minor data wrangling
4. /images: exported figures and any image files to read-in to your R Markdown manuscript
5. /_extensions: auto-generated or installed Quarto extensions, like apaquarto

Top-level files

1. README.md: project overview, repo structure, to-do list, etc.
2. .gitignore: starting from the R .gitignore template
3. project-manuscript.qmd: the home of your eventual publication
4. bibliography.bib: a plain-text file containing all the BibTeX entries cited in your manuscript
5. yourCitationStyle.csl: the script used to format in-text and bibliography citations when knitting

Repo Structure: Example 2

A simple, generic project:

quarto-manuscript-project/
├── README.md
├── .gitignore
├── project-manuscript.qmd
├── bibliography.bib
├── yourCitationStyle.csl
├── localonly/                 // ONLY ON YOUR COMPUTER, NOT GITHUB
├── data/
│   ├── raw/                   // Raw data read into unsourced R scripts
│   └── cleaned-data.csv       // Processed data read into your .qmd
├── source/
│   ├── style-preferences.R    // Styling/theming
│   ├── custom-functions.R     // Reusable functions
│   └── data-wrangling.R       // Minor data prep
├── images/
│   ├── figure1.png
│   └── figure2.png
└── _extensions/
        └── apaquarto/             // Auto-generated extension files

Hidden files and directories (non-exhaustive list)

• .git/ - Git metadata, what makes Git work
• .Rproj.user/ - RStudio project settings
• .quarto/ - Quarto project settings
• .Rproj
• .RData
• .Rhistory
• .DS_Store

Repos and R Projects will also include some hidden files and directories

• .git/ - Git metadata, what makes Git work
• .Rproj - RStudio project settings
• .quarto/ - Quarto project settings

You won’t interact with these directories directly, and you won’t see them in RStudio or on GitHub.

You may also have other hidden files, for example:

• .Rproj.user
• .RData
• .Rhistory
• .DS_Store

You won’t interact with these either but they won’t always be fully hidden in every interface. You can add them to your .gitignore file so they don’t clutter up your repo.

README.md

A README.md file provides a project overview. It is typically the first thing someone sees when they visit your repository on GitHub.

• Simple markdown (.md) document
• What you see rendered on a repo’s GitHub page
• Minimally describe:
  • Purpose of the repo
  • Dataset(s)
  • Repo structure
  • Any relevant licensing, restrictions, or citations

.gitignore: what

A .gitignore file tells Git which files and directories to ignore when comparing differences between versions.

• Plain text file w/out extension
• Files & folders excluded from all git processes
• Matched on strings, including wildcard characters and simplified regex
• View documentation

.gitignore: why

Not everything belongs online.

• PRIVACY.
  • Do not upload anything with sensitive or identifiable information.
  • It is your responsibility to follow your IRB.
• Security
  • passwords, security keys, login tokens
• Bloat
  • Git is designed for text files
  • Large files push very slowly and can cause RStudio to hang
  • Some files are regenerated automatically
• Conflict
  • “behind the scenes” files that actually interact with local, git, or R processes will conflict for baffling reasons (sort of a technological observer effect)

.gitignore: how

Optionally start with a template then:

• Use informative # comments
• Protect private data in a localonly/ folder
• Ignore files/folders with matched text

Ignore large files

• Media files: e.g, *.png, *.jpg, *.mp4
• Presentation files: e.g., *.pptx, *.key
• Specialized and raw files: e.g, *.bdl, *.ear, *.mgh

Ignore auto-generated files

• System files: e.g., *.DS_Store, *.RData, *.Rhistory
• Process files: e.g., *.log, *.aux, *.out
• Compiled files: e.g., *.pdf, *.docx, *.html

.gitignore: how (verbose)

Optionally start with a template then:

• Use informative # comments
• Protect private data in a localonly/ folder
  • Dedicated place for anything you need to keep offline that the .gitignore might not explicitly catch
  • Good place to keep deanonymized datasets instead of trusting yourself to remember to add them to the .gitignore
• Ignore files/folders
  • Matching the name: data/raw/sensitive_data.csv, topsecret/
  • Using wildcards: *.pdf, no-git_*

Ignore large files

• Media files: e.g, *.png, *.jpg, *.mp4
  • tend to be very large, often contain sensitive info
• Presentation files: e.g., *.pptx, *.key
  • not necessary for reproducibility, often large
• Specialized and raw files: e.g, *.bdl, *.ear, *.mgh
  • data needs to be tabular eventually anyway

Ignore auto-generated files

• System files: e.g., *.DS_Store, *.RData, *.Rhistory
  • platform-specific, or not text-based
• Process files: e.g., *.log, *.aux, *.out
  • should be deleted after success but can stick around if knitting fails
• Compiled files: e.g., *.pdf, *.docx, *.html
  • recreated every time you knit

Key Takeaways

• Manage all projects with version control
• Git is a powerful version control system; GitHub is a platform for hosting Git repositories
• Key Git concepts:
  • repositories: folders tracked by Git
  • commits: snapshots of changes
  • pulls: get changes from remote repos
  • pushes: send changes to remote repos
• Your repo needs:
  • project files
  • metadata files
  • a README.md
  • a .gitignore file
• PULL when you sit down to work. COMMIT frequently as you work. PUSH when you pause or finish.

• Version control is essential for managing changes in your projects
• Git is a powerful version control system; GitHub is a platform for hosting Git repositories
• Key Git concepts include repositories, commits, branches, pulls, and pushes
• A well-structured repository includes project files, metadata, a README, and a . gitignore file
• Using Git in RStudio provides a user-friendly interface for version control tasks
• Regularly committing and pushing changes helps maintain a clear project history