Welcome to our Introduction to GitHub

Objective

Here you will learn how to use the web interface and terminal to keep track and manage your files.

There are 3 options on how to use this github folder!

1. Read the .md files in the 'docs' folder.

• This option is great if you have a background in github and/or you do not have the time to work through the excersizes

2. Complete the excersises in the 'excersises' folder, and then reference the documents in the 'docs' file as needed to complete the excersises and once you have done them!
3. Just copy and paste files or other references you might need.

How to Navigate This Repository

Introduction

This repository is a sandbox for learning GitHub. Whether you are brand new to version control or just rusty, you will find what you need here. The exercises build on each other — each one introduces a new skill and references the matching doc for background reading. You do not need to complete them all in one sitting, and you do not need to do them in order (though it helps).

By the end, you will know how to:

• Get code onto your computer and push changes back to GitHub
• Use branches so your work-in-progress never disrupts your labmates
• Open and review Pull Requests
• Handle merge conflicts without panicking
• Keep sensitive data out of your repository
• Set up automated checks that run every time someone opens a PR

If you just need a quick reference (e.g., "what was that command to undo a staged file?"), the docs/ folder has you covered.

File arrangements/where to find things

• .github/ -> Contains all GitHub-specific configuration files. Four subfolders/files live here:
  • .github/PULL_REQUEST_TEMPLATE.md -> Pre-fills the description box every time someone opens a PR with a structured checklist (summary, changes, how to verify, checklist). Keeps PRs consistent across the team.
  • .github/CODEOWNERS -> Automatically assigns required reviewers based on which files a PR touches. The lab lead is listed as owner of the whole repo and the lab_website_bio_image/ folder, so every PR gets routed to them for approval. Replace @renata with the actual GitHub username before using.
  • .github/ISSUE_TEMPLATE/ -> Contains three issue form templates that appear when someone clicks "New Issue." Instead of a blank text box, contributors see a structured form. The three templates are: bug_report.yml (something broke), feature_request.yml (suggest an improvement), and question.yml (I'm stuck and need help). The config.yml controls whether blank issues are allowed and adds external links (docs, Slack, etc.) to the template chooser.
  • .github/workflows/ -> Contains GitHub Actions workflow files. python_checks.yml runs Black, Ruff, and pytest on every PR (acts as a gatekeeper — checks must pass before merging). python_autoformat.yml is a more advanced workflow that auto-formats your code and commits the changes back to your branch automatically.
• data/ -> Holds all of the data/files we will use. Most of them are empty, and are mainly kept to help you learn how to navigate github (which means the names and locations are important, but the content is usually not).
• docs/ -> These are here to help you learn github processes (on the web and in the terminal)
• excercises/ -> There are here as a sandbox, to help you practice everything you learn
• src/ -> Holds Python files used in the GitHub Actions exercise (Exercise 10). hello.py has simple functions; tests/test_hello.py has the matching pytest tests. The other files (helper.py, statistics.py) are empty placeholders — their names and locations are what matter for navigation practice, not their content.
• lab_website_bio_image/ -> Do not delete this folder. Edit it when you are ready to upload your bio and image onto our lab website as the final project (excercises/11_lab_website_final_project/). Copy template_bio.md, rename it, and fill in your information.
• .gitattributes -> Tells Git how to handle certain file types. Common uses: normalizing line endings between Mac/Windows (so files don't show up as "changed" just because of invisible newline differences), marking binary files (images, Excel) so Git doesn't try to show a text diff for them, and controlling which files GitHub counts toward the repo's language statistics. The .gitattributes file in this repo is a starting template — see the comments inside for examples.
• .gitignore -> This file is an example of a .gitignore file, and it walks through how to set up and use a .gitignore file to effectively ignore files and folders within your repository.
• LICENSE -> Describes the terms under which others can use, share, or build on the code in this repository. This repo uses an Apache 2.0 license. See choosealicense.com for plain-language explanations of common license options.
• requirements.txt -> Lists the Python packages needed for the GitHub Actions CI workflow (Exercise 10): black, ruff, and pytest.

Helper Docs

1. docs/01_setup.md -> This file is how to setup github in your repository

• How to clone (download) a repository via your terminal or the webinterface
• How to create a new repository
• How to edit files
• How to save your changes (add, commit, push)
• Explains what a private and public repository is, and when to use each
• References docs/08_templates.md
• References docs/07_github_protection_policies.md

2. docs/02_branches.md -> How to setup and use branches

• Explains what a branch is, and how to use them effectively
• Explains how to visualize your branches
• Explains a gitflow
• How to create new branches
• How to delete branches
• How to switch branches

3. docs/03_commits.md -> How to save your progress

• Explains what a commit is
• Explains how to use them
• How to write good commit messages

4. docs/04_pull_requests.md -> How to have other people review your work effectively

• Explains what a pull request is, and how to use it effectively
• Explains how to setup a pull request
• Explains what to do if someone asks you to review their pull request

5. docs/05_merging.md -> How to merge your branches (and handle conflicts)

• Talks through squashing vs merging
• Explains how to merge
• Explains how to handle merge conflicts

6. docs/06_github_actions.md -> What github actions are and how to use them

• Explains what github actions are
• Explains how to set one up
• Explains ideas for what to do with them
• Explains how Cornell's account only allows you to do this (Because they have an enterprise account)

7. docs/07_github_protection_policies.md -> How to set up policies, and other protection measures to ensure there are less mix-ups and mistakes when collaborating or using a repository

• Explains what rules and policies are and how to use them
• Gives examples and reasonings

8. docs/08_templates.md -> Covers git hub coding and processing templates

• Explains what templates are, how to find ones that already exist, and develop new ones.
• Introduces coding practices in python, r, and github action templates.
• Explains why templates are useful and when is the most effective time to use them.

9. docs/09_good_git_habits.md-> Highlights good and bad github practices

• General rules of thumb for coding practices
• How to use github in the most effective ways
• Examples of bad and good habits

10. docs/terminal_vs_web.md -> The capability differences of using the terminal vs the web.

• Explains what the terminal vs the web based platform is used for

Exercises

Note: many of the exercises have continuing thoughts, but the actual content/terminal/web usage can be applied outside of the exact context of each exercise.

1. excercises/01_initializing_repository/ -> How to download code from github (cloning) and how to start a new repo from scratch (git init)
2. excercises/02_first_commit/ -> The core git workflow: add, commit, push — plus how to rename and delete files using git
3. excercises/03_branching/ -> How to create, switch between, visualize, and delete branches
4. excercises/04_pull_requests/ -> How to open a pull request, review code, leave comments, and merge
5. excercises/05_merge_conflicts/ -> How to intentionally create a merge conflict and resolve it step by step
6. excercises/06_squash_vs_merge/ -> The difference between a regular merge and a squash merge, and why it matters for history
7. excercises/07_gitignore/ -> How to keep sensitive files and generated output out of your repository
8. excercises/08_files_with_spaces/ -> How to work with filenames that have spaces in them from the terminal
9. excercises/09_recover_mistakes/ -> How to unstage, undo commits, and safely reverse pushed changes
10. excercises/10_git_actions/ -> How to set up a CI workflow that runs Black, Ruff, and pytest on every pull request
11. excercises/11_lab_website_final_project/ -> Final project: add your bio and photo to the lab website using the full branch → PR → review → merge workflow
12. excercises/12_bonus_challenges/ -> Advanced standalone challenges: cherry-pick, interactive rebase, stash, git tags, releases, and more

Templates

This repository comes with two templates already set up:

• Pull Request template (.github/PULL_REQUEST_TEMPLATE.md) — automatically pre-fills the description box whenever you open a new PR. It prompts you for a summary, what changed, how to verify it, and a checklist. You will see it in action starting with Exercise 4.
• Bio template (lab_website_bio_image/template_bio.md) — the starting point for the final project. Copy it, rename it with your name, and fill in your research interests and contact info.

For more on creating your own templates (repo templates, issue templates, GitHub Actions starter workflows), see docs/08_templates.md.

GitHub Actions

This repository includes a CI (Continuous Integration) setup for Exercise 10:

• Workflow file: .github/workflows/python_checks.yml (you will create this in Exercise 10)
• What it does: runs on every pull request targeting main — checks Python formatting with Black, linting with Ruff, and runs the test suite with pytest
• Files it tests: src/hello.py and tests/test_hello.py
• Dependencies: listed in requirements.txt

Branch protection rules can be set to require these checks to pass before any PR is allowed to merge. See docs/06_github_actions.md and docs/07_github_protection_policies.md for details.

GitIgnore file

The .gitignore file at the root of this repository does two things:

1. Teaches you how .gitignore syntax works — it is heavily commented with examples of patterns (exact files, wildcards, folders).
2. Protects the repo from accidentally tracking files that should stay local (raw data, credentials, generated output).

Key patterns already in use: data/files_to_ignore_storage/, data/same_name_ignore (any extension), and *.jpeg. Exercise 7 walks you through adding more patterns and recovering from an accidentally staged file.

License File

The LICENSE file declares the terms under which this repository's contents can be used and shared. This repo uses the Apache 2.0 license, which allows anyone to use, modify, and distribute the code as long as they include attribution and the original license notice.

Common license options:

License	Allows use?	Requires attribution?	Requires sharing changes?
MIT	✅	✅	❌
Apache 2.0	✅	✅	❌
GPL v3	✅	✅	✅
CC BY 4.0	✅ (non-code)	✅	❌

Not sure which one fits your project? choosealicense.com has plain-English explanations.

GitAttributes File

The .gitattributes file controls how Git treats specific file types. The most common use case in a research lab setting is line ending normalization: Mac and Linux use LF for line endings; Windows uses CRLF. Without .gitattributes, switching between machines can make every line of a file appear "changed" even when the actual content hasn't changed.

The standard fix:

# .gitattributes
* text=auto          # let Git decide whether a file is text or binary
*.csv text eol=lf    # always use LF for CSV files
*.png binary          # treat PNGs as binary (don't try to diff them as text)

This repository's .gitattributes file is a starting template — add patterns as you encounter issues.

Terminal vs GitHub Accessibility

Here is a brief table of what is able to be done in the terminal, the web, or both

Task	Terminal	GitHub Web
Create branch	✅	✅
Edit file	✅	✅
Commit	✅	✅
Pull Request	✅	✅
Merge	✅	✅
Review	❌	✅
Resolve conflicts	✅	Limited
Delete branch	✅	✅
GitHub Actions	✅	✅
Finding/Creating/Using Templates	✅	✅
Branch protection rules	❌	✅
Interactive rebase / stash / cherry-pick	✅	❌

Fun Facts and Quick Notes

• This is a "ReadMe" file, and has the file extension .md, which is short for Markdown — a lightweight formatting language where **bold** renders as bold, # Heading becomes a heading, and backticks make code look like this.
• GitHub automatically renders any file named README.md (case-insensitive) as the landing page for a folder. That is why every exercise folder has its own README — GitHub shows it when you navigate to that folder.
• The . at the start of filenames like .gitignore, .gitattributes, and .github/ makes them "hidden" files on Mac and Linux — they won't show up in a regular ls, but they do show up in ls -a or in VS Code's file explorer.
• git (the command-line tool) and GitHub (the website) are not the same thing. Git was created in 2005 by Linus Torvalds; GitHub launched in 2008 as a place to host Git repositories online. You can use Git without GitHub (e.g. a local repo), but GitHub requires Git.
• A repository's full history is stored in the hidden .git/ folder at the root. Never delete it — that folder is the version history.