Git & GitHub · A Hands-on Tutorial

Roberts Lab · Self-directed tutorial

Version control your work with Git & GitHub.

GitHub is where the lab keeps its code, notebooks, and analyses — version-controlled, backed up, and open. This tutorial gets you from zero to a working repository using the friendly GitHub Desktop app, then shows the same workflow on the command line once you're ready.

⏱️ ~1–2 hours, self-paced 🖱️ GitHub Desktop first ⌨️ Command line as bonus ✅ No prior experience needed

Start here

How to use this tutorial

Do it, don't just read it. By the end you'll have a real repository on GitHub with at least one commit you pushed yourself. Check off boxes as you go — progress saves in this browser.

🧠

Understand

Section 1 explains what version control is and the handful of words you'll keep hearing.

🖱️

Do it with the app

Sections 2–7 walk through the whole loop in GitHub Desktop — no terminal required.

⌨️

Level up

Section 8 repeats every step on the command line for when you're working on Klone or over SSH.

The big picture. A repository ("repo") is a project folder whose entire history Git tracks. You work locally, save snapshots called commits, and push them to GitHub so they're backed up and shareable. That loop — change → commit → push — is 90% of what you'll ever do.

Section 1

Why version control?

Ever ended up with analysis_final.R, analysis_final_v2.R, and analysis_REALLY_final.R? Version control replaces that mess with a single file and a complete, labeled history you can move through.

What Git gives you

History — every saved state, who changed what, and why.
Undo — roll back to any previous commit.
Backup — your work lives on GitHub, not just your laptop.
Collaboration — many people on one project without overwriting each other.

Git vs. GitHub

Git is the version-control software that runs on your computer and tracks changes. GitHub is the website that hosts Git repositories online — backup, sharing, issues, and collaboration. GitHub Desktop is a free app that drives Git with buttons instead of typed commands.

The words you'll keep hearing

Term	Plain meaning
Repository (repo)	A project folder whose history Git tracks.
Commit	A saved snapshot of your changes, with a message describing them.
Push	Send your local commits up to GitHub.
Pull / Fetch	Bring changes down from GitHub to your computer.
Clone	Download a copy of a GitHub repo to work on locally.
Branch	A parallel line of work you can later merge back in.

Section 2 · Hands-on

Set up your account & the app

Two one-time steps: a GitHub account, and the GitHub Desktop app installed and signed in.

Create a GitHub account

Go to github.com/join and sign up. Use a professional username — you'll share it with collaborators. Students and educators can get free upgrades via GitHub Education.

Install GitHub Desktop

Download from desktop.github.com (macOS & Windows) and install it like any other app.

Sign in & set your identity

Open GitHub Desktop → File ▸ Options ▸ Accounts and sign in to GitHub. Under Git, confirm your name and email so your commits are attributed to you. That's it — you're ready to make a repo.

GitHub account created
GitHub Desktop installed
Signed in, with name & email set

Section 3 · Hands-on

Create a repository

You'll make a brand-new repo for practice. (To work on an existing lab repo instead, skip to Section 4 and clone it.)

New repository

In GitHub Desktop: File ▸ New Repository…

Fill in the details

Name — e.g. git-practice (no spaces; hyphens are fine).
Local Path — where it lives on your computer. The lab convention is to keep all repos inside a single gitrepos folder.
Initialize with a README — check this; it's the front page of your repo.
Git ignore — pick a template (e.g. R or Python) so junk files aren't tracked.
License — optional now; MIT is a common open choice.

Click Create Repository.

Publish it to GitHub

So far the repo only exists on your laptop. Click Publish repository (top bar). Choose whether it's private or public, then publish. Refresh your GitHub profile and you'll see it online.

Public vs. private. The lab works openly, but check with your mentor before making anything public that contains unpublished data, large data files, or anything sensitive. You can change visibility later in the repo's settings on GitHub.

Created a new local repository
Added a README and .gitignore
Published it to GitHub

Section 4 · Hands-on

Clone & sync an existing repo

Most of the time you'll join a repo that already exists — a lab project, or your own from another machine. Cloning downloads a full copy you can work on.

Clone from GitHub Desktop

File ▸ Clone Repository… Pick one from your account/organization list, or paste a URL like https://github.com/RobertsLab/resources. Choose the local path (inside gitrepos) and click Clone.

Keep it in sync

Before you start working each day, click Fetch origin → Pull to bring down anything teammates pushed. Starting from the latest version is the single best habit for avoiding conflicts.

Golden rule of collaboration: pull before you start, push when you pause. The more often you sync, the smaller and easier any merges will be.

Cloned a repository to my computer
Pulled the latest changes from GitHub

Section 5 · Hands-on

Make some changes

Now do real work in the repo folder — using whatever tools you normally would (RStudio, VS Code, a text editor, Finder). Git watches the folder for you.

Open the repo folder on your computer (in GitHub Desktop: Repository ▸ Show in Finder/Explorer).
Edit the README.md — add a sentence describing the project.
Create a new file, e.g. notes.md, and type a few lines.
Save your files.

Switch back to GitHub Desktop. The Changes tab now lists every file you touched, with a colored diff showing exactly what you added (green) and removed (red). This is your chance to review your own work before recording it.

What is a "diff"? A diff is a line-by-line comparison between the last committed version and your current files. Reading diffs before committing catches accidental changes, stray debug code, and files you didn't mean to include.

Edited the README
Added a new file
Reviewed the diff in the Changes tab

Section 6 · Hands-on

Commit your snapshot

A commit records the current state of selected files as a permanent point in history, with a short message explaining the change.

Choose what goes in

In the Changes tab, the checkbox beside each file decides whether it's included. Usually you commit everything related to one logical change together; leave unrelated edits for a separate commit.

Write a good message

At the bottom left, fill in the Summary (required) and optional Description. Write the summary as a short, present-tense instruction:

Add project description to README
Fix temperature unit conversion in cleaning script
Add notes on sample exclusion criteria

Aim to describe what changed and why — "stuff" and "update" tell future-you nothing.

Commit

Click Commit to main. Your snapshot is now saved locally. Repeat the change → commit cycle as often as you like; small, frequent commits are easier to understand and undo than giant ones.

Selected files to include
Wrote a clear commit message
Made at least one commit

Section 7 · Hands-on

Push to GitHub (and pull back)

Your commits are still only on your laptop. Pushing sends them up to GitHub — backing them up and making them visible to collaborators.

Push origin

Click Push origin (top bar). After a moment, refresh the repo page on GitHub — your new commit and files are there, with the message you wrote.

Pull on your other machines

Working somewhere else later (another computer, Klone)? Open the repo and Fetch ▸ Pull to bring those commits down. The repo stays consistent everywhere.

You've completed the core loop. Edit → review the diff → commit with a message → push. That's the whole everyday workflow. Everything else (branches, pull requests, issues) builds on top of this.

Bonus: branches & pull requests in 60 seconds

For bigger or shared changes, create a branch (Branch ▸ New Branch) so your work-in-progress doesn't disturb main. Commit and push to that branch, then on GitHub open a Pull Request to propose merging it back. Collaborators review, discuss, and merge. This is how the lab reviews substantial changes — see the handbook's Project Management page for conventions.

Pushed commits to GitHub
Confirmed the changes appear online
Completed a full edit → commit → push loop

Section 8 · Advanced

⌨️ The same workflow on the command line

On Klone, over SSH, or in any terminal there's no Desktop app — so it pays to know the underlying Git commands. Good news: they map one-to-one onto the buttons you just used. (New to the terminal? Do the Bash tutorial first.)

One-time setup

Tell Git who you are (matches the identity GitHub Desktop set for you):

$ git config --global user.name "Your Name"
$ git config --global user.email "you@example.com"
# check your settings any time:
$ git config --list

Get a repository

Clone an existing repo

$ cd ~/gitrepos
$ git clone https://github.com/RobertsLab/resources.git
$ cd resources

Start a brand-new one

$ mkdir git-practice && cd git-practice
$ git init
$ echo "# Git Practice" > README.md

Then create an empty repo on GitHub and connect it (see "Push" below).

The everyday loop

# 1. start from the latest version
$ git pull

# 2. ... edit files with your editor ...

# 3. see what changed (the command-line "Changes" tab)
$ git status
$ git diff

# 4. stage the files you want to commit
$ git add README.md notes.md
# (or stage everything that changed:)
$ git add .

# 5. commit with a message
$ git commit -m "Add project description to README"

# 6. push to GitHub
$ git push

Button → command map

GitHub Desktop	Command line	Does what
Clone Repository	`git clone <url>`	Download a repo locally
(Changes tab)	`git status` / `git diff`	See what changed
(Checkbox per file)	`git add <file>`	Stage changes to commit
Commit to main	`git commit -m "msg"`	Save a snapshot locally
Push origin	`git push`	Send commits to GitHub
Fetch / Pull	`git pull`	Bring down others' changes
New Branch	`git switch -c <name>`	Start a parallel line of work

Connecting a new local repo to GitHub

After git init locally, create an empty repo on GitHub (no README), then link and push:

$ git add .
$ git commit -m "Initial commit"
$ git branch -M main
$ git remote add origin https://github.com/<you>/git-practice.git
$ git push -u origin main

Authentication tip. Pushing over HTTPS prompts for a Personal Access Token (not your password). The easiest path on a laptop is to let GitHub Desktop handle credentials, or install the GitHub CLI and run gh auth login. On Klone, an SSH key is the smoothest option.

Section 9 · Practice

Put it together

Cement the loop with these. Do A–B in GitHub Desktop; try C on the command line if you're feeling bold.

Easy

A. Three-commit history

In your git-practice repo, make three separate edits and commit each one with its own clear message. Then look at the History tab and read your story back.

You'll practice: small commits and good messages.

Medium

B. Edit on GitHub, pull down

Edit the README directly on the GitHub website (pencil icon) and commit there. Back in GitHub Desktop, Fetch ▸ Pull and watch the change arrive on your computer.

You'll practice: syncing in both directions.

Stretch

C. Full loop in the terminal

Using only the command line, clone a repo, create a file, git add / commit / push it, and confirm it appears on GitHub. Use git status liberally along the way.

You'll practice: the command-line workflow you'll need on Klone.

Made a three-commit history (A)
Edited on GitHub and pulled it down (B)
Completed the loop on the command line (C, stretch)

Reference

Cheat sheet & key points

Everyday Git commands

`git clone <url>`	Copy a repo locally
`git pull`	Get latest from GitHub
`git status`	What's changed?
`git diff`	Show line-by-line changes
`git add .`	Stage all changes
`git commit -m "…"`	Save a snapshot
`git push`	Send commits to GitHub

Habits that prevent pain

Pull before you start, push when you pause.
Commit small and often, one logical change at a time.
Write messages future-you will understand.
Read the diff before every commit.
Never commit secrets or large data — use .gitignore.
Keep all repos in one gitrepos folder.

Want to go deeper? See GitHub's Getting Started guides, the GitHub Desktop docs, and the lab's Computing Best Practices for how we organize repositories.

You're version-controlled. Everything the lab does — code, notebooks, analyses — runs through this exact loop. Keep committing. 🐙