Lab 1: Git and GitHub

This session introduces version control with Git and GitHub. Setting up these tools first means you can track your work from day one.

Week 1 software requirement

Bring your laptop in week 1 and confirm Git/GitHub access. Install both R and RStudio in week 1, and use RStudio as the standard editor for this course. Instructions are in Lab 2: Install R and Set Up Your IDE.

What is version control?

Version control tracks every change you make to your files. Instead of saving e.g. report_v2_final_FINAL.docx, you save a single file and Git remembers its entire history. You can go back to any previous version, see exactly what changed, and collaborate without overwriting each other's work.

GitHub is a website that hosts your Git repositories online. It serves as a backup and lets you share your work. There are other services like GitLab and Bitbucket, but GitHub is the most popular.

Why bother?

• Your lab diary and final report will be easier to manage.
• You will never lose work (every version is saved).
• Employers value version control skills.
• It is the standard tool for reproducible research -- much more powerful than OSF presentations because every change is tracked and time-stamped.

Step 1: Create a GitHub account

1. Go to https://github.com.
2. Click Sign up and follow the prompts. (Get the student version -- see below).
3. Choose a username you are happy to use professionally (e.g., jsmith-nz, not xXx_gamer_xXx).
4. Verify your email address.

Student benefits

Apply for the GitHub Student Developer Pack with your university email. It includes free access to GitHub Copilot, cloud credits, and other developer tools.

Step 2: Install Git

macOS

Open Terminal (search for it in Spotlight) and type:

git --version

If Git is not installed, macOS will prompt you to install the Xcode Command Line Tools. Follow the prompts.

Windows

Download Git from https://git-scm.com/download/win. Run the installer and accept the defaults.

Verify installation

Open a terminal (Terminal on macOS, Git Bash on Windows) and type:

git --version

You should see something like git version 2.44.0.

Step 3: Configure Git

Tell Git your name and email (use the same email as your GitHub account):

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

Step 4: Set up SSH authentication

Before you can push code, GitHub needs to verify who you are. SSH keys let your computer prove its identity without a password each time. You do this once and it works from then on.

Check whether you already have a key

Many students already have an SSH key from a previous course, internship, or Git setup. Before creating a new one, check what is already in your ~/.ssh/ folder:

ls -la ~/.ssh

If you see files such as id_ed25519 and id_ed25519.pub, you may already have a usable key. If you are unsure, it is fine to create a fresh key for this course. GitHub allows more than one SSH key on an account.

Generate an SSH key

Open a terminal and run:

ssh-keygen -t ed25519 -C "your.email@example.com"

Use the email address attached to your GitHub account.

You will see prompts like these:

Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/yourname/.ssh/id_ed25519):

Press Enter to accept the default location unless you already have a key there and want to keep it. If you already have an id_ed25519 key and want a separate course key, you can type a different file name such as ~/.ssh/id_ed25519_psyc434.

Next you will be asked about a passphrase:

Enter passphrase (empty for no passphrase):
Enter same passphrase again:

You may press Enter twice to skip it. A passphrase adds security, but it also means you may need to unlock the key when you restart your computer.

This creates two files in ~/.ssh/:

Protect your private key

The file ~/.ssh/id_ed25519 (no .pub) is your private key. Treat it like a password. Never paste it into a chat, never commit it to a repository, never upload it anywhere. If you suspect it has been exposed, delete the key from your GitHub account immediately at github.com/settings/keys and generate a new one.

Confirm that the files were created

Run:

ls -l ~/.ssh

You should see both the private key and the public key. If you saved the key under a custom name, look for that name instead of id_ed25519.

Add the key to the SSH agent

The SSH agent remembers your key so Git can use it automatically.

Start the agent:

eval "$(ssh-agent -s)"

Then add your key:

ssh-add ~/.ssh/id_ed25519

If you used a custom file name, replace id_ed25519 with that name.

On some macOS systems, the following command is preferred because it stores the passphrase in the keychain:

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

If that command gives an error, use the plain ssh-add ~/.ssh/id_ed25519 command instead.

Add the public key to your GitHub account

Copy the public key (the file ending in .pub) to your clipboard.

macOS:

pbcopy < ~/.ssh/id_ed25519.pub

Windows (Git Bash):

cat ~/.ssh/id_ed25519.pub

Select and copy the output manually.

If pbcopy does not work on your system, you can also print the key manually:

cat ~/.ssh/id_ed25519.pub

Copy the entire line beginning with ssh-ed25519.

Then add it to GitHub:

1. Go to github.com/settings/keys.
2. Click New SSH key.
3. Give it a title (e.g., "My laptop").
4. Paste the key into the Key field.
5. Click Add SSH key.

Test the connection

ssh -T git@github.com

The first time, you will usually see a message like:

The authenticity of host 'github.com (IP ADDRESS)' can't be established.
ED25519 key fingerprint is ...
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Type yes and press Enter. You should then see:

Hi your-username! You've successfully authenticated, but GitHub does not provide shell access.

That message means it worked. All future git push and git pull commands will authenticate automatically.

Common problems

If you get Permission denied (publickey)

This usually means one of four things:

1. You copied the wrong key to GitHub.
2. You copied the private key instead of the public key.
3. Your key was not added to the SSH agent.
4. You are using a different GitHub account from the one attached to the key.

Work through these checks:

ls -l ~/.ssh
ssh-add -l
cat ~/.ssh/id_ed25519.pub

Then compare the printed public key with the one shown at github.com/settings/keys.

If ~/.ssh/id_ed25519.pub does not exist

The key pair was not created where you think it was. Run ls -la ~/.ssh and look for the file name you chose during ssh-keygen.

If you see Agent admitted failure to sign

Run:

ssh-add ~/.ssh/id_ed25519

and then test again with ssh -T git@github.com.

If ssh -T hangs or fails

Some university networks block SSH. If you are on campus Wi-Fi and the command hangs, try from a different network (e.g., your phone hotspot). If it still fails, contact the course coordinator.

Step 5: Create a private repository on GitHub

1. Go to github.com/new.
2. Name your repository psy434-labs (or similar).
3. Set visibility to Private.
4. Check Add a README file.
5. Click Create repository.

Privacy and submission

Your GitHub repository must remain private for the duration of the course. Do not change its visibility to public. Lab diaries are submitted as .md files via NUKU, not through GitHub. GitHub is your version-control tool; NUKU is where marking happens. Submission instructions for each lab diary appear on the NUKU assignment page.

Step 6: Clone the repository to your computer

Cloning downloads a copy of the repository to your machine and links it to GitHub.

1. On your repository page, click the green Code button.
2. Select SSH and copy the URL (it starts with git@github.com:).
3. Open a terminal and navigate to where you want to store your work:

mkdir -p ~/Documents/psy434
cd ~/Documents/psy434

1. Clone the repository:

git clone git@github.com:YOUR-USERNAME/psy434-labs.git

Replace YOUR-USERNAME with your GitHub username.

1. Move into the repository folder:

cd psy434-labs

You now have a local copy linked to GitHub.

Sanity check that you are in the right place:

pwd
ls

You should see your location end with psy434-labs, and you should see the files in your repository (it may be empty at first).

If you are new to Terminal

These commands help you check where you are and what files you have:

pwd        # print the current folder (your location)
ls         # list files in the current folder
cd ..      # go up one folder
cd ~       # go to your home folder

If you ever see an error like "No such file or directory", run pwd and ls to check your location and spelling.

Checkpoint

If you have cloned your repository successfully, you are on track. Everything below can be finished before next week's lab if you run out of time.

Step 7: The basic Git workflow

The everyday workflow has three steps: stage, commit, push.

Recommended editor

RStudio is the recommended editor for creating and editing .md, .R, and .qmd files. It reduces file-extension errors (for example, accidentally saving README.md.txt) and all lab instructions assume RStudio. Install instructions are in Lab 2. You may use another editor, but you will need to adapt instructions yourself.

1. Create your first file

Your repository already has a README.md from Step 5. Open it and replace its contents with:

# PSYCH 434 lab diary

This is my lab diary for PSYCH 434 (2026).

Save the file in the root of your repository folder (psy434-labs/). Use RStudio if available (File > New File > Text File), then save as README.md.

Windows file extensions

If you create the file in File Explorer, make sure it is named README.md (not README.md.txt). If you cannot see extensions, turn on "File name extensions" in File Explorer.

Creating a file from the command line

If you are already in your repository folder, you can create an empty file with:

touch README.md

Then open it in a text editor and paste in the text above. If you are not sure you are in the right place, run pwd and check that the folder name ends with psy434-labs.

2. Check what changed

Before staging, check what Git sees:

git status

You should see README.md in red under "Untracked files". This command is your best friend: run it whenever you are unsure what state your repository is in.

A typical first output looks something like this:

On branch main

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        README.md

nothing added to commit but untracked files present

Read this output slowly:

1. On branch main tells you which branch you are working on.
2. Untracked files means Git sees the file, but is not yet tracking it.
3. The suggested git add command tells you the next step.

If you see "not a git repository"

You are not in your repository folder. Run pwd and ls, then cd psy434-labs and try git status again.

3. Stage the change

Staging tells Git which changes you want to include in your next snapshot:

git add README.md

Run git status again immediately afterward:

git status

Now README.md should appear in green under a heading such as Changes to be committed. That means the file is staged and ready for the next commit.

You can inspect exactly what is staged with:

git diff --staged

This command shows the line-by-line changes that will go into the commit. It is a good habit to check this before every commit.

Safety: always name the files you are staging

git add README.md stages one file. You know exactly what will be committed. Commands like git add . or git add -A stage everything Git can see in the current directory and below. If you run one of these from the wrong folder, you can accidentally stage thousands of files, including private data, SSH keys, or your entire home directory. One student ran git add .. (note the two dots, meaning the parent folder) and began uploading gigabytes of data.

Rules:

1. Always run pwd first. Confirm you are inside your repository folder.
2. Always run git status before committing. Check that only the files you expect appear in green.
3. Prefer naming files explicitly (e.g., git add README.md diaries/lab-01.md). Use git add . only when you have just checked git status and every listed file belongs in the commit.
4. If you see hundreds of files listed in git status, stop. You are probably in the wrong directory. Do not commit. Run pwd, then cd to the right folder.

4. Commit the change

A commit is a snapshot with a short message describing what you did:

git commit -m "add readme with course details"

Think of the commit message as an instruction to your future self. Good commit messages are short and specific.

Good examples:

git commit -m "add readme with course details"
git commit -m "start lab 01 diary"
git commit -m "fix typo in README"

Poor examples:

git commit -m "stuff"
git commit -m "update"
git commit -m "final final really final"

Sanity check that Git recorded your commit:

git log -1 --oneline

You should see your commit message listed.

Common mistake

There must be a space after commit and between -m and the message:

git commit -m "update readme"   # correct
git commit-m "update readme"    # wrong: git does not recognise commit-m
git commit -m"update readme"    # wrong: missing space before the message

If Git says "nothing to commit"

Either you forgot to save the file in your editor, or you forgot to stage it. Run:

git status

If the file appears under Changes not staged for commit, run git add README.md again. If Git shows nothing changed, save the file and try again.

5. Push to GitHub

Push sends your commits to GitHub so they are backed up online:

git push

If you set up authentication in Step 4, this should work without a password prompt.

If you see an error about an upstream branch, run:

git push -u origin HEAD

That command tells Git which remote branch your local branch should track. You usually only need to do it once.

If the push succeeds, Git will print a summary showing which branch was updated on GitHub.

If git push is rejected

Sometimes GitHub has changes that your computer does not yet have, for example if you edited the README on the GitHub website. In that case, run:

git pull --rebase
git push

If Git reports a conflict, stop and ask for help rather than guessing.

Step 8: Check your work

Go to your repository page on GitHub. You should see the updated README file with your changes.

You should also see:

1. The latest commit message near the top of the file list.
2. The commit count link, which you can click to view history.
3. Your updated README rendered as formatted text on the repository front page.

If the page has not changed, refresh the browser and check that your git push command succeeded.

Quick reference

Workflow summary

Edit files → git add → git commit -m "message" → git push. Repeat.

Emergency: stuck in a rebase

If you accidentally start a rebase and want to get back to where you were:

git rebase --abort

If you are resolving a rebase conflict, the usual flow is:

git add <file>
git rebase --continue

If you are unsure, run git status and ask for help before you try random commands.

What never belongs in a repository

Git remembers everything you commit, even after you delete the file. If you push a secret to GitHub, assume it is compromised. Removing it from later commits does not remove it from the history.

Never commit any of the following:

Your .gitignore blocks most data and output files automatically, but it cannot protect you if you stage files from outside your repository or override it with a force flag.

If you accidentally push something private

1. Do not panic, but act quickly.
2. Revoke the credential. If it is an SSH key, delete it from github.com/settings/keys and generate a new one (repeat Step 4). If it is an API token or password, revoke it on the service that issued it. Once revoked, the exposed copy is useless.
3. Delete and recreate the repository. Removing the file from a later commit does not remove it from the history. The simplest fix is to delete the repository on GitHub, create a new one, and push your current local folder to it. Your local files are unaffected.
4. If personal data was exposed (e.g., participant records with names or ID numbers), this is a privacy breach. Report it to the course coordinator immediately so it can be escalated to the university.

Terminal basics

You have already used a few terminal commands (cd, git clone). The terminal is a text interface for your computer. Every command you type runs a small program. Here are the commands you will use most often.

Where am I?

pwd

pwd (print working directory) shows the folder you are currently in.

List files

ls

ls lists the files and folders in the current directory. To see hidden files (names starting with .), use:

ls -a

Git stores its data in a hidden folder called .git. Try ls -a inside your repository to see it.

Change directory

cd ~/Documents/psy434/psy434-labs

cd moves you into a folder. A few shortcuts:

So cd .. moves up one level, and cd ~ takes you home.

Create a folder

mkdir diaries

mkdir (make directory) creates a new folder.

Create an empty file

touch lab-01.md

touch creates an empty file if it does not already exist. (Windows users: touch works in Git Bash but not in PowerShell or Command Prompt. Make sure you are using Git Bash.)

Terminal quick reference

Organise your repository

Set up a simple folder structure for the course. From inside your repository folder:

mkdir diaries data R

Git does not track empty folders. To make sure diaries/, data/, and R/ appear on GitHub, add a placeholder file to each:

touch diaries/.gitkeep data/.gitkeep R/.gitkeep

(data/.gitkeep is the only file in data/ that should be tracked.)

Each folder has a purpose:

A tidy repository separates source files (code you write) from generated output (plots, PDFs, HTML). Source files go into Git; output does not. If your code is correct, anyone can regenerate the output by running it. This principle, that results follow from code, is the basis of reproducible research.

Naming conventions

Good file names are lowercase, use hyphens instead of spaces, and sort naturally:

Three rules of thumb:

1. No spaces. Use hyphens (-) or underscores (_). Spaces require quoting in the terminal and cause errors in scripts.
2. Zero-pad numbers. 01, 02, ... 10 sort correctly; 1, 2, ... 10 does not (your system puts 10 before 2).
3. Name for content, not sequence. A file called analysis-ate.R is still meaningful six months later; script3.R is not.

Next, create a .gitignore file. This tells Git to ignore files that should not be tracked (system files, R temporary files, datasets, large binaries, etc.).

If you are using RStudio:

1. Go to File > New File > Text File.
2. Paste the contents below.
3. Go to File > Save As....
4. Save the file as .gitignore in the root of your repository (psy434-labs/).
5. In the Files pane, click More > Show Hidden Files so dotfiles are visible.
6. Open .gitignore from the Files pane whenever you want to edit it.

Paste the following contents:

# system files
.DS_Store
Thumbs.db

# R
.Rhistory
.RData
.Rproj.user
*.Rproj

# data files
data/**
!data/.gitkeep
*.rds
*.qs
*.parquet
*.arrow
*.csv
*.xlsx
*.sav
*.dta

# large binary and archive files
*.zip
*.7z
*.tar
*.gz
*.bz2
*.xz
*.dmg
*.iso
*.mp4
*.mov
*.avi
*.mp3
*.wav

# output files
*.pdf
*.html
*.png
*.jpg
*.jpeg
*.svg
*.gif
*.tiff
_files/
*_cache/
.quarto/

Save the file in the root of your repository (the same folder as README.md). The filename must start with a dot: .gitignore, not gitignore.

Your repository should look like this:

psy434-labs/
├── .gitignore
├── README.md
├── R/
│   └── .gitkeep
├── data/
│   └── .gitkeep
└── diaries/
    └── .gitkeep

Notice that data/ exists on your computer but Git ignores its contents by default. This is intentional: data files can be large, and anyone with your code can regenerate them. Keep data local; keep code in Git.

Before every commit, check that you are staging only source files (.md, .R, .qmd, and small config files):

git status
git diff --cached --name-only

If you accidentally stage a data file or large object, unstage it:

git restore --staged <file>

If you already committed it, remove it from tracking while keeping the local copy:

git rm --cached <file>
git commit -m "stop tracking data file"
git push

Lab diary files go in the diaries/ folder, named by week number:

diaries/
├── lab-01.md
├── lab-02.md
├── lab-03.md
├── ...
└── lab-10.md

There is no lab-07.md (week 7 is test 1). Create your first diary file now:

touch diaries/lab-01.md

Markdown basics

Markdown is a plain-text format that converts to formatted documents. You write in a .md file using simple symbols for headings, bold, lists, and so on. GitHub renders markdown automatically, so your diary will look formatted when you view it online.

Headings

Use # symbols. More # signs mean smaller headings:

# Heading 1
## Heading 2
### Heading 3

Paragraphs

Separate paragraphs with a blank line. A single line break without a blank line will not start a new paragraph.

Bold and italics

This is **bold** and this is *italic*.

Lists

Unordered lists use -:

- first item
- second item
- third item

Numbered lists use 1., 2., etc.:

1. first step
2. second step
3. third step

Inline code

Wrap code in single backticks:

Use the `git push` command to upload your work.

Links

[GitHub](https://github.com)

Markdown reference

GitHub has a concise guide to GitHub-flavoured markdown: Basic writing and formatting syntax.

Write your first lab diary

Create your week 1 diary entry now. Open diaries/lab-01.md in RStudio and write ~150 words covering:

1. What this lab covered and what you did.
2. A connection to the week's lecture content.
3. One thing you found useful, surprising, or challenging.

Use at least one heading, one bold or italic word, and one list. When you are done, stage these files, commit, and push:

git add .gitignore diaries/lab-01.md diaries/.gitkeep data/.gitkeep R/.gitkeep
git commit -m "add lab 01 diary and repo structure"
git push

Check your repository on GitHub to confirm the file appears and the markdown renders correctly.

Editors

RStudio is the recommended editor for this course. All examples and in-class instructions assume RStudio. You are welcome to use any editor you prefer (VS Code, Zed, Neovim, etc.), but you will need to translate instructions on your own. Avoid rich-text editors (Word, Pages, TextEdit) that can silently change file format or extensions.

Alternative: GitHub Desktop

If you prefer a graphical interface, download GitHub Desktop. It provides the same stage/commit/push workflow with buttons instead of terminal commands. Either approach is fine for this course.