diff --git a/01_materials/slides/01_git_intro_clone_fork.pdf b/01_materials/slides/01_git_intro_clone_fork.pdf new file mode 100644 index 0000000..bac9c20 Binary files /dev/null and b/01_materials/slides/01_git_intro_clone_fork.pdf differ diff --git a/01_materials/slides/02_git_basic_commands.pdf b/01_materials/slides/02_git_basic_commands.pdf new file mode 100644 index 0000000..36006ce Binary files /dev/null and b/01_materials/slides/02_git_basic_commands.pdf differ diff --git a/01_materials/slides/03_git_branching_merge_conflict.pdf b/01_materials/slides/03_git_branching_merge_conflict.pdf new file mode 100644 index 0000000..e011c08 Binary files /dev/null and b/01_materials/slides/03_git_branching_merge_conflict.pdf differ diff --git a/03_instructional_team/.dsi-certificates-theme.css b/03_instructional_team/.dsi-certificates-theme.css deleted file mode 100644 index 6b7cc19..0000000 --- a/03_instructional_team/.dsi-certificates-theme.css +++ /dev/null @@ -1,51 +0,0 @@ -/* dsi-certificates-theme.css */ -/* @theme dsi-certificates-theme */ - -@import 'uncover'; - -img[alt~="center"] { - display: block; - margin: 0 auto; -} - - -p { - text-align: left; - font-size: 35px -} -ul { - margin: 0; - font-size: 35px; -} -table { - font-size: 35px; -} -ol { - margin: 0; - font-size: 35px; -} - -blockquote { - border-left: 10px solid #ccc; - margin: 1.5em 10px; - padding: 0.5em 30px; - quotes: "\201C""\201D""\2018""\2019"; -} - -blockquote:before { - color: #ccc; - content: none; - font-size: 4em; - line-height: 0.1em; - margin-right: 0.25em; - vertical-align: -0.4em; -} - -blockquote:after{ - content: none; -} - -footer { - margin-bottom: 0px; - text-align: left; -} diff --git a/03_instructional_team/README.md b/03_instructional_team/README.md index d00ba14..719baf7 100644 --- a/03_instructional_team/README.md +++ b/03_instructional_team/README.md @@ -58,3 +58,17 @@ Feedback should be given through the pull request a participant has made. Techni ## generate_slides.sh This script is designed to convert Markdown files located in a specified folder into slide presentations using Marp CLI, allowing for the generation of either HTML or PDF formats based on user input. It includes an option to apply a custom CSS theme to the slides by specifying a theme path. The script also provides a help function detailing its usage, options, and examples for convenience. It ensures the necessary directories exist, validates the presence of Marp CLI on the system, processes each Markdown file found in the specified directory, and outputs the generated slides into a designated output folder, displaying the status of each operation and a completion message. The only configuration needed is to set where the md files are and where you would like the pdf/html files to be placed. + +Example command to generate themed PDF slides: + +```bash +cd 03_instructional_team +./generate_slides.sh --pdf --theme markdown_slides/themes/dsi_certificates_theme.css +``` + +To generate themed HTML slides instead, use: + +```bash +cd 03_instructional_team +./generate_slides.sh --html --theme markdown_slides/themes/dsi_certificates_theme.css +``` diff --git a/03_instructional_team/homework/.keep b/03_instructional_team/homework/.keep new file mode 100644 index 0000000..945c9b4 --- /dev/null +++ b/03_instructional_team/homework/.keep @@ -0,0 +1 @@ +. \ No newline at end of file diff --git a/03_instructional_team/homework/README.md b/03_instructional_team/homework/README.md deleted file mode 100644 index 993dd70..0000000 --- a/03_instructional_team/homework/README.md +++ /dev/null @@ -1 +0,0 @@ -Homework 2 was removed from the homework directory due to its high complexity. At the time when we will be teaching the learners, it would be inappropriate to assign it. The decision to introduce this homework or not is at the discretion of the technical facilitator, depending on the average learner's technical capabilities. \ No newline at end of file diff --git a/03_instructional_team/markdown_slides/01_git_intro_clone_fork.md b/03_instructional_team/markdown_slides/01_git_intro_clone_fork.md new file mode 100644 index 0000000..7ec4772 --- /dev/null +++ b/03_instructional_team/markdown_slides/01_git_intro_clone_fork.md @@ -0,0 +1,471 @@ +--- +marp: true +theme: dsi_certificates_theme +style: | + section { + font-family: Inter, -apple-system, BlinkMacSystemFont, 'Helvetica Neue', sans-serif; + } + .two-col { + display: grid; + grid-template-columns: 1fr 1fr; + gap: 28px; + align-items: start; + } + .three-col { + display: grid; + grid-template-columns: 1fr 1fr 1fr; + gap: 18px; + align-items: stretch; + } + .box { + border: 2px solid #ddd; + border-radius: 14px; + padding: 18px; + background: #fafafa; + } + .center { + text-align: center; + } + .big { + font-size: 1.25em; + } + .small { + font-size: 0.78em; + } +paginate: true +--- + +# Git: First Workflow + +```bash +$ fork +$ git clone +``` + +From project history → local work → shared GitHub copies + +--- + +## Where We Are in the Module + +| Session | Focus | Big idea | +|---|---|---| +| Unix Shell | Files and folders | Work with project files from the command line | +| Local Git | Version control | Save meaningful checkpoints in project history | +| GitHub | Remote sharing | Share, collaborate, and showcase work online | + +Today we connect **Git on your computer** with **GitHub online**. + +--- + +## Learning Goals + +By the end of this section, you should be able to explain: + +1. What Git is for +2. What **modified**, **staged**, and **committed** mean +3. What **local** and **remote** repositories are +4. The difference between **clone** and **fork** +5. How to fork a GitHub repo and clone your fork + +--- + +## What Is Git For? + +Git is a tool for tracking project history. + +It helps us answer questions like: + +- What changed? +- When did it change? +- Why did it change? +- Who changed it? +- Can I go back to an earlier version? + +--- + +## Analogy: Git as a Project Archive + +Imagine you are working on a research project. + +You do not want 20 files named: + +```text +analysis_final.R +analysis_final_revised.R +analysis_final_revised_REAL_FINAL.R +``` + +Instead, Git lets you keep **one project folder** with a clear history of saved checkpoints. + +--- + +## Git in One Sentence + +
+Git lets you save labeled checkpoints as your project changes. +
+ +
+ +Each checkpoint is called a **commit**. + +A commit is like a saved snapshot of your project at a meaningful moment. + +--- + +## The Three States + +Git uses three important states for files: + +| State | Meaning | +|---|---| +| Modified | You changed the file, but Git has not saved it yet | +| Staged | You selected the change for the next commit | +| Committed | Git saved the change in project history | + +--- + +## Analogy: Desk → Tray → Archive + +
+
+ +### Desk + +You are actively editing papers. + +**Modified** + +
+
+ +### Review Tray + +You choose what is ready to save. + +**Staged** + +
+
+ +### Archive + +You store a labeled snapshot. + +**Committed** + +
+
+ +--- + +## The Local Git Workflow + +```text +Modified Staged Committed +on your desk → in review tray → in archive +``` + +```bash +# edit files + +git status # what changed? +git add file # choose this file for the next checkpoint +git commit -m "message" # save the checkpoint +``` + +Important: `git add` does **not** save history yet. + +It prepares changes for the next commit. + +--- + +## What Does `git status` Do? + +`git status` is your checklist. + +It tells you: + +- which files changed +- which changes are staged +- which changes are not staged +- whether your working tree is clean + +```bash +git status +``` + +Use it often. + +--- + +## What Are Local and Remote Repositories? + +A Git project can have more than one copy. + +| Copy | Where it lives | Analogy | +|---|---|---| +| Local repository | Your computer | Your personal archive | +| Remote repository | GitHub | Shared online archive | + +A commit is local first. + +GitHub sees it only after you **push**. + +--- + +## Local and Remote: Visual + +```text +Your computer GitHub + +┌──────────────────┐ ┌──────────────────┐ +│ Local repository │ │ Remote repository│ +│ │ │ │ +│ commits │ git push ───▶ │ shared commits │ +│ files │ git pull ◀─── │ online backup │ +└──────────────────┘ └──────────────────┘ +``` + +`push` sends your commits up. +`pull` brings remote commits down. + +--- + +## What Is GitHub? + +GitHub is a website that hosts Git repositories online. + +It is commonly used for: + +- backing up projects online +- collaborating with other people +- reviewing code and changes +- submitting assignments +- building a public portfolio + +Git and GitHub are related, but they are not the same thing. + +--- + +## Clone vs Fork + +Both are ways to copy a repository, but they copy it to different places. + +| Action | What it creates | Where | +|---|---|---| +| Clone | A local copy | Your computer | +| Fork | Your own remote copy | Your GitHub account | + +In this activity, we will usually **fork first**, then **clone our fork**. + +--- + +## Clone: Visual + +```text +GitHub original repo +UofT-DSI/git + │ + │ git clone + ▼ +Your computer +local copy of UofT-DSI/git +``` + +Cloning downloads a repository to your computer. + +But it does **not** create your own copy on GitHub. + +--- + +## Fork: Visual + +```text +GitHub original repo Your GitHub account +UofT-DSI/git fork YOUR-USERNAME/git +┌──────────────┐ ─────────────▶ ┌──────────────┐ +│ original │ │ your copy │ +│ remote repo │ │ remote repo │ +└──────────────┘ └──────────────┘ +``` + +Forking creates your own GitHub copy of someone else's repository. + +--- + +## Fork + Clone: Visual + +```text +1. Fork on GitHub + +UofT-DSI/git ─────────────▶ YOUR-USERNAME/git + +2. Clone your fork + +YOUR-USERNAME/git ─────────▶ your computer +``` + +After this, you can work locally and push changes to **your fork**. + +--- + +## Why Fork for This Exercise? + +We do not want everyone pushing changes to the original course repository. + +Forking gives each learner: + +- their own remote copy +- permission to push to their own copy +- a safe place to practice +- a visible GitHub project they can revisit later + +--- + +# Code Along + +Fork and clone the course repository. + +--- + +## Step 1: Open the Course Repository + +Open this page in your browser: + +```text +https://github.com/UofT-DSI/git +``` + +Make sure you are signed in to GitHub. + +Then click **Fork**. + +--- + +## Step 2: Create Your Fork + +On the fork page: + +1. Keep the owner as your GitHub account +2. Keep the repository name as `git` +3. Add a description if you want +4. Click **Create fork** + +You should now be on a page like: + +```text +https://github.com/YOUR-USERNAME/git +``` + +--- + +## Step 3: Copy the Clone URL + +On your forked repository: + +1. Click the green **Code** button +2. Select **HTTPS** +3. Copy the URL + +It should look like: + +```text +https://github.com/YOUR-USERNAME/git.git +``` + +--- + +## Step 4: Clone Your Fork + +In your terminal, move to the folder where you keep class work. + +Then run: + +```bash +git clone https://github.com/YOUR-USERNAME/git.git +``` + +Replace `YOUR-USERNAME` with your GitHub username. + +--- + +## Step 5: Enter the Repository + +```bash +cd git +``` + +Check where you are: + +```bash +pwd +ls +``` + +Then ask Git what it sees: + +```bash +git status +``` + +--- + +## Step 6: Check the Remote Connection + +```bash +git remote -v +``` + +You should see something like: + +```text +origin https://github.com/YOUR-USERNAME/git.git (fetch) +origin https://github.com/YOUR-USERNAME/git.git (push) +``` + +`origin` is the default name for the remote repository you cloned from. + +--- + +## Stop and Check + +Can you answer these questions? + +1. Where is the original repository? +2. Where is your fork? +3. Where is your local clone? +4. What does `origin` point to? +5. Why did we fork before cloning? + +--- + +## Common Mistakes + +| Problem | What to check | +|---|---| +| Cloned the original repo | Did your URL include your username? | +| Cannot push later | Did you clone your fork or the original? | +| Cannot find the folder | Did you run `cd git`? | +| Not signed in | Are you signed in to GitHub before forking? | +| Wrong folder | Run `pwd` and `ls` to orient yourself | + +--- + +## Key Takeaways + +- Git tracks project history with commits. +- Files move from **modified** → **staged** → **committed**. +- Local repositories live on your computer. +- Remote repositories live online, often on GitHub. +- Clone copies a repo to your computer. +- Fork creates your own GitHub copy. +- In this class: **fork first, then clone your fork**. + +--- + +## References + +- Pro Git book: https://git-scm.com/book/en/v2 +- UofT-DSI Git repository: https://github.com/UofT-DSI/git diff --git a/03_instructional_team/markdown_slides/02_git_basic_commands.md b/03_instructional_team/markdown_slides/02_git_basic_commands.md new file mode 100644 index 0000000..5539017 --- /dev/null +++ b/03_instructional_team/markdown_slides/02_git_basic_commands.md @@ -0,0 +1,811 @@ +--- +marp: true +theme: dsi_certificates_theme +style: | + section { + font-family: Inter, -apple-system, BlinkMacSystemFont, 'Helvetica Neue', sans-serif; + } + code { + font-size: 0.9em; + } +paginate: true +--- + +# Git Basic Commands + +```bash +$ git status +$ git add +$ git commit +$ git push +``` + +--- + +## Where We Are Now + +From the first slide set, you should now have: + +```text +A GitHub account +A forked repository on GitHub +A cloned copy on your computer +``` + +Now we will learn the basic Git commands we use every day on a NEW repo. + +--- +## Why Create a New Repo? + +The forked course repo is useful for practicing fork and clone. + +For basic commands, we will create a small personal repo called `book`. + +This gives us a clean, simple place to practice: + +- editing files +- making commits +- pushing to GitHub +- pulling remote changes +- checking old commits +--- + +## Today's Goal + +By the end of this section, you should be able to: + +- check what changed +- stage selected files +- commit a local snapshot +- push changes to GitHub +- pull changes from GitHub +- look at project history +- temporarily check out an older version + +--- + +## The Mental Model + +Think of Git as a project workflow: + +| Git concept | Analogy | +|---|---| +| Working directory | Your desk | +| Staging area | Review tray | +| Local repository | Personal archive | +| Remote repository | Shared online archive | + +```text +Desk → Review tray → Personal archive → Shared archive +``` + +--- + +## The Basic Workflow + +```text +Working directory Staging area Local repo Remote repo + your files selected changes committed history GitHub + | | | | + | git add | git commit | git push | + v v v v + Modified --------> Staged --------> Committed -----> Published +``` + +Important idea: + +> `git add` stages changes. `git commit` saves staged changes. + +--- + +# `git status` + +--- + +## `git status`: What Is Happening? + +`git status` shows the current state of your repository. + +```bash +git status +``` + +It tells you: + +- which branch you are on +- which files changed +- which files are staged +- which files are untracked +- whether your local branch is ahead or behind GitHub + +--- + +## Analogy: `git status` + +`git status` is like checking your desk and review tray. + +It answers: + +```text +What is on my desk? +What is already in the review tray? +What is ready to archive? +Is my archive synced with GitHub? +``` + +Use it often. + +--- + +## Example: `git status` + +```bash +$ git status + +On branch main +Your branch is up to date with 'origin/main'. + +Changes not staged for commit: + modified: README.md + +Untracked files: + notes.txt +``` + +Plain language: + +```text +README.md changed. +notes.txt is new. +Neither is staged yet. +``` + +--- + +# `git add` + +--- + +## `git add`: Move Changes to Staging + +`git add` puts selected changes into the staging area. + +```bash +git add README.md +``` + +This means: + +```text +Include README.md in the next commit. +``` + +It does **not** create a saved version yet. + +--- + +## Connection: Staged = `git add` + +When a file is **staged**, it is in the review tray. + +```bash +git add README.md +``` + +```text +Desk → Review tray +``` + +You are telling Git: + +> This change should be part of my next saved snapshot. + +--- + +## Common `git add` Patterns + +Stage one file: + +```bash +git add README.md +``` + +Stage all current changes: + +```bash +git add -A +``` + +Good practice: + +```bash +git status +git add README.md +git status +``` + +Check before and after staging. + +--- + +# `git commit` + +--- + +## `git commit`: Save a Snapshot Locally + +`git commit` saves the staged changes into your local Git history. + +```bash +git commit -m "Update README" +``` + +The commit message explains what changed. + +--- + +## Connection: Committed = `git commit` + +When a change is **committed**, it is saved in your personal archive. + +```text +Review tray → Personal archive +``` + +Important: + +```text +git add = choose what to save +git commit = save it locally +git push = upload it to GitHub +``` + +--- + +## What Makes a Good Commit Message? + +A good message is short and meaningful. + +Good examples: + +```bash +git commit -m "Add project README" +git commit -m "Fix typo in installation instructions" +git commit -m "Add data cleaning script" +``` + +Less helpful: + +```bash +git commit -m "stuff" +git commit -m "changes" +git commit -m "final final version" +``` + +--- + +# `git log` + +--- + +## `git log`: View Project History + +`git log` shows the commit history. + +```bash +git log +``` + +A shorter version is often easier to read: + +```bash +git log --oneline +``` + +This shows each commit as one line with a short commit ID. + +--- + +## Analogy: `git log` + +`git log` is like opening the archive index. + +It answers: + +```text +What snapshots exist? +When were they made? +Who made them? +What message did they leave? +What is the commit ID? +``` + +--- + +## Example: `git log --oneline` + +```bash +$ git log --oneline + +a72f91c Add notes file +4c19b21 Update README +91e7c03 Initial commit +``` + +Each line is a saved checkpoint. + +The first part is the commit ID: + +```text +a72f91c +``` + +--- + +# `git push` + +--- + +## `git push`: Send Local Commits to GitHub + +After committing locally, GitHub does not automatically know about your changes. + +Use `git push` to upload your local commits. + +```bash +git push +``` + +Or, if needed: + +```bash +git push origin main +``` + +--- + +## Analogy: `git push` + +`git push` sends updates from your personal archive to the shared online archive. + +```text +Personal archive → Shared online archive +Local repo → Remote repo +Your computer → GitHub +``` + +A commit is local first. + +GitHub sees it only after you push. + +--- + +# `git pull` + +--- + +## `git pull`: Bring GitHub Changes to Your Computer + +If the remote repository has changes you do not have locally, use: + +```bash +git pull +``` + +This downloads and applies the remote changes to your local repository. + +--- + +## Analogy: `git pull` + +`git pull` brings updates from the shared online archive back to your personal archive and desk. + +```text +Shared online archive → Personal archive → Desk +GitHub → Local repo → Working directory +``` + +Good habit: + +```bash +git pull +``` + +at the beginning of a work session. + +--- + +# `git checkout ` + +--- + +## `git checkout `: Visit an Older Snapshot + +You can temporarily look at an older version of your project: + +```bash +git log --oneline +git checkout +``` + +Example: + +```bash +git checkout 91e7c03 +``` + +This lets you inspect what the project looked like at that commit. + +--- + +## Important: Detached HEAD + +When you check out a commit ID directly, Git puts you in a temporary state called **detached HEAD**. + +Plain language: + +```text +You are visiting an old snapshot. +You are not on the main branch right now. +``` + +To go back: + +```bash +git switch main +``` + +or: + +```bash +git checkout main +``` + +--- + +## Analogy: `git checkout ` + +Checking out a commit is like taking an old snapshot out of the archive to look at it. + +You can inspect it, but you should be careful about editing there. + +```text +Archive snapshot → temporary viewing table +``` + +For today: + +> Use checkout to look, then return to `main`. + +--- + +# Code-Along Exercise + +Create a new GitHub repo and practice the full workflow. + +--- + +## Exercise Goal + +We will create a new repository on GitHub and practice: + +```bash +git clone +git status +git add +git commit +git log +git push +git pull +git checkout +``` + +By the end, you will have your own GitHub repository with multiple commits. + +--- + +## Step 1: Create a New Repo on GitHub + +On GitHub: + +1. Click **New repository** +2. Name it: + +```text +book +``` + +3. Choose **Public** or **Private** +4. Check **Add a README file** +5. Click **Create repository** + +--- + +## Step 2: Clone Your Repo + +On GitHub, copy the HTTPS URL from the green **Code** button. + +Then in your terminal: + +```bash +cd Desktop +git clone https://github.com//book.git +cd book +``` + +Replace `` with your GitHub username. + +--- + +## Step 3: Check the Repository + +```bash +git status +git log --oneline +``` + +You should see: + +```text +You are on branch main. +Your working tree is clean. +There is at least one commit. +``` + +That first commit was created when GitHub added the README. + +--- + +## Step 4: Modify the README + +Add a line to `README.md`. + +Option A: edit the file in VS Code or another editor. + +Option B: use the terminal: + +```bash +echo "This is the Git repository of my book." >> README.md +``` + +Then check: + +```bash +git status +``` + +--- + +## Step 5: Stage the Change + +```bash +git add README.md +``` + +Remember: + +```text +git add = move from desk to review tray +git add = modified → staged +``` + +Check again: + +```bash +git status +``` + +--- + +## Step 6: Commit the Change + +```bash +git commit -m "Update README with project description" +``` + +Remember: + +```text +git commit = save staged changes to local archive +git commit = staged → committed +``` + +Then check history: + +```bash +git log --oneline +``` + +--- + +## Step 7: Push to GitHub + +```bash +git push +``` + +Then refresh your GitHub repository page. + +You should see your README update online. + +```text +Local committed change → GitHub +``` + +--- + +## Step 8: Make a Remote Change on GitHub + +On GitHub: + +1. Open `README.md` +2. Click the pencil/edit icon +3. Add one more line: + +```text +This line was added on GitHub. +``` + +4. Commit the change on GitHub + +Now GitHub has a commit your computer does not have yet. + +--- + +## Step 9: Pull the Remote Change + +Back in your terminal: + +```bash +git status +git pull +git log --oneline +``` + +Now your local repository should include the commit you made on GitHub. + +```text +GitHub → your computer +``` + +--- + +## Step 10: Check Out an Older Commit + +First, view history: + +```bash +git log --oneline +``` + +Copy an older commit ID. + +Then: + +```bash +git checkout +``` + +Look at the files. + +What changed? + +--- + +## Step 11: Return to `main` + +After inspecting the old snapshot, return to your main branch: + +```bash +git switch main +``` + +or: + +```bash +git checkout main +``` + +Then check: + +```bash +git status +``` + +--- + +# The Daily Git Routine + +--- + +## Everyday Workflow + +A normal Git workflow often looks like this: + +```bash +git pull + +# edit files + +git status +git add README.md +git commit -m "Describe the change" +git push +``` + +Plain language: + +```text +Sync → edit → check → stage → commit → share +``` + +--- + +## Command Summary + +| Command | Purpose | Analogy | +|---|---|---| +| `git status` | Check current state | Check desk and tray | +| `git add` | Stage selected changes | Put pages in review tray | +| `git commit` | Save local snapshot | Archive labeled snapshot | +| `git log` | View history | Read archive index | +| `git push` | Upload commits | Send to shared archive | +| `git pull` | Download updates | Get from shared archive | +| `git checkout ` | Visit old commit | Inspect old snapshot | + +--- + +## Common Issues + +### “Nothing to commit” + +There may be no saved file changes. + +```bash +git status +``` + +### “Rejected push” + +GitHub has changes you do not have yet. + +```bash +git pull +git push +``` + +### “Detached HEAD” + +You checked out a commit ID. + +```bash +git switch main +``` + +--- + +## Mini Challenge + +Create a new file and publish it to GitHub. + +```bash +echo "My Git notes" > notes.txt +git status +git add notes.txt +git commit -m "Add Git notes" +git push +``` + +Then refresh your GitHub repo. + +Do you see `notes.txt`? + +--- + +# Questions? + +```bash +git status +``` + +When in doubt, start here. diff --git a/03_instructional_team/markdown_slides/03_git_branching_merge_conflict.md b/03_instructional_team/markdown_slides/03_git_branching_merge_conflict.md new file mode 100644 index 0000000..737f1d8 --- /dev/null +++ b/03_instructional_team/markdown_slides/03_git_branching_merge_conflict.md @@ -0,0 +1,890 @@ +--- +marp: true +theme: dsi_certificates_theme +style: | + section { + font-family: Inter, -apple-system, BlinkMacSystemFont, 'Helvetica Neue', sans-serif; + } +paginate: true +--- + +# Git Branching, Pull Requests, and Conflicts + +```bash +$ git branch +$ git switch -c new-branch +$ git push +``` +--- + +## Where We Are + +By now, we have practiced the basic Git loop: + +```bash +git status +git add +git commit +git push +git pull +``` + +Today we add one more important idea: + +> How do we safely work on changes without disturbing the main project? + +--- + +## Today's Goals + +By the end of this session, you should be able to: + +- explain what a branch is +- create and switch branches +- understand why branches are useful +- merge a branch back into `main` +- recognize and resolve a merge conflict +- use a branch-based workflow in your own repo + +--- + +# Why Branch? + +--- + +## Analogy: A Safe Copy of Your Workbench + +Imagine `main` is the clean, stable version of your project. + +A branch is like setting up a separate workbench. + +You can experiment, make a mess, and try ideas without touching the stable version. + +```text +main branch = stable workbench +feature branch = experiment workbench +merge = bring finished work back +``` + +--- + +## Why Branches Are Useful + +Branches help us: + +- try ideas safely +- work on one task at a time +- collaborate without overwriting each other +- keep `main` stable +- review changes before merging +- fix problems without disrupting other work + +--- + +## Common Branch Use Cases + +```text +feature/add-readme +fix/typo-in-script +docs/update-installation +analysis/test-new-model +``` + +Each branch should usually have one clear purpose. + +--- + +## Branches Are Lightweight + +A branch is not a full copy of your project. + +It is more like a pointer to a commit. + +```text +main ---- A ---- B + ↑ + feature +``` + +Creating branches is cheap and fast. + +--- + +## Mental Model + +```text +Commit = saved checkpoint +Branch = movable label pointing to a checkpoint +HEAD = where you are currently working +``` + +When you commit on a branch, that branch pointer moves forward. + +--- + +# Branch Commands + +--- + +## See Your Branches + +```bash +git branch +``` + +The branch with `*` is the branch you are currently on. + +Example: + +```bash +* main + feature-readme +``` + +--- + +## Create a New Branch + +```bash +git switch -c feature-readme +``` + +This means: + +```text +Create a new branch called feature-readme, +and switch to it. +``` + +Older command you may see online: + +```bash +git checkout -b feature-readme +``` + +--- + +## Switch Between Branches + +```bash +git switch main + +git switch feature-readme +``` + +Older command you may see online: + +```bash +git checkout main +``` + +--- + +## Check the Branch History + +```bash +git log --oneline --graph --decorate --all +``` + +This gives a compact view of commits and branches. + +Useful when you want to see where branches split and merge. + +--- + +# Best Practices + +--- + +## Branch Best Practices + +Before creating a branch: + +```bash +git switch main +git pull +``` + +Then create your new branch: + +```bash +git switch -c docs/update-readme +``` + +Start from the latest shared version whenever possible. + +--- + +## Naming Branches + +Good branch names are short and descriptive. + +```text +feature/add-login +fix/data-loading-error +docs/update-readme +analysis/compare-models +``` + +Avoid vague names: + +```text +stuff +changes +keli-branch +new +``` + +--- + +## Keep Branches Focused + +A good branch usually does one thing. + +Better: + +```text +Branch 1: update README +Branch 2: clean analysis script +Branch 3: add visualization +``` + +Harder to review: + +```text +One branch with README + script cleanup + new plots + random fixes +``` + +--- + +## Commit Often, But Meaningfully + +Good commits are small enough to understand. + +```bash +git add README.md +git commit -m "Add installation instructions" +``` + +Avoid one giant commit at the end of a long work session. + +--- + +# Merging on GitHub + +--- + +## What Is a Merge? + +A merge brings changes from one branch into another branch. + +Most often: + +```text +feature branch → main branch +``` + +Analogy: + +> You finished work on the experiment workbench, and now you bring the useful result back to the stable workbench. + +--- + +## Local Merge vs GitHub Merge + +There are two common places where merging can happen: + +| Where | What it means | +|---|---| +| Local merge | You run `git merge` on your computer | +| GitHub merge | You open a Pull Request and merge on GitHub | + +In this course, we will practice **GitHub merge**. + +That means: + +```text +push branch → open Pull Request → review → merge on GitHub +``` + +--- + +## Why Merge on GitHub? + +Merging on GitHub is useful because it gives us a shared review space. + +Before merging, we can: + +- compare the branch against `main` +- review exactly what changed +- discuss changes with collaborators +- catch conflicts before changing `main` +- keep a visible project history + +--- + +## Visual: Branch Before Pull Request + +```text +main: A ---- B + \ +branch: C ---- D +``` + +The branch has commits that are not yet in `main`. + +--- + +## Visual: Pull Request on GitHub + +```text +GitHub compares: + +branch ──────── wants to merge into ──────── main + + "Can these changes be safely added?" +``` + +A Pull Request is a request to bring branch changes into `main`. + +--- + +## Visual: After GitHub Merge + +```text +main: A ---- B -------- M + \ / +branch: C ---- D +``` + +`M` is the merge result. + +After this, `main` includes the branch changes. + +--- + +## What Is a Pull Request? + +A Pull Request, or PR, is a GitHub page for reviewing and merging a branch. + +A PR usually shows: + +- which branch is merging into which branch +- commits included in the branch +- files changed +- line-by-line differences +- whether the branch can merge cleanly +- whether there are conflicts + +--- + +# Merge Conflicts + +--- + +## What Is a Conflict? + +A conflict happens when Git cannot automatically decide how to combine changes. + +Most common case: + +> Two branches changed the same part of the same file in different ways. + +GitHub pauses the merge and asks you to choose the final version. + +--- + +## Analogy: Two People Edit the Same Sentence + +Original sentence: + +```text +This project analyzes data. +``` + +Branch changes it to: + +```text +This project analyzes survey data. +``` + +Main changes it to: + +```text +This project analyzes GitHub data. +``` + +GitHub cannot know which one you want. + +--- + +## What Conflict Markers Look Like + +GitHub may show conflict markers like this: + +```text +<<<<<<< main +This project analyzes GitHub data. +======= +This project analyzes survey data. +>>>>>>> update-readme-title +``` + +Your job is to edit this into the final version you want. + +--- + +## How to Resolve a Conflict on GitHub + +1. Open the Pull Request. +2. Click **Resolve conflicts**. +3. Edit the file into the final version you want. +4. Remove conflict markers: + +```text +<<<<<<< +======= +>>>>>>> +``` + +5. Click **Mark as resolved**. +6. Commit the resolution. +7. Merge the Pull Request. + +--- + +## Do Not Panic + +A conflict does not mean you broke Git. + +It means Git found overlapping changes and needs human judgment. + +The key question is: + +> What should the final file say? + +--- + + +# Code Along + +--- + +## Code Along Goal + +We will work on the same GitHub repo `book`. + +Then we will use one file, `chapter1.txt`, to practice: + +1. creating a branch +2. pushing the branch to GitHub +3. editing `main` on GitHub +4. opening a Pull Request +5. resolving a conflict on GitHub +6. merging on GitHub +7. pulling the final result back locally + +--- + +## Code Along Picture + +```text +GitHub repo: book + +main branch: chapter1.txt has one opening line +feature branch: changes the same opening line +main on GitHub: also changes that same opening line + +Result: GitHub asks us to resolve the conflict before merging +``` + +--- + +## Step 0: Make sure we are in the right starting point + +Before We Start, In your terminal: + +```bash +cd book +git switch main +git pull +git status +``` +--- + +## Step 1: Create `chapter1.txt` on `main` + +Create a new file: + +```bash +touch chapter1.txt +``` + +Open it: + +```bash +code chapter1.txt +# or: nano chapter1.txt +``` + +Add this text: + +```text +Chapter 1: A quiet morning + +Once upon a time, a new Git repo was born. +``` + +Save the file. + +--- + +## Step 2: Commit and Push `chapter1.txt` + +Check what changed: + +```bash +git status +git diff +``` + +Stage, commit, and push: + +```bash +git add chapter1.txt +git commit -m "Add chapter 1" +git push +``` + +Remember: + +```text +git add = move change to review tray +git commit = save it to local history +git push = send local commits to GitHub +``` + +--- + +## Step 3: Create One Branch + +Create and switch to a new branch: + +```bash +git switch -c revise-chapter1-opening +``` + +Check where you are: + +```bash +git branch +``` + +You should see: + +```text +* revise-chapter1-opening + main +``` + +--- + +## Step 4: Edit `chapter1.txt` on the Branch + +Open `chapter1.txt` again. + +Change the first line to: + +```text +Chapter 1: The Adventure Begins +``` + +Leave the rest of the file the same. + +Save the file. + +--- + +## Step 5: Commit the Branch Change + +Check what changed: + +```bash +git status +git diff +``` + +Stage and commit: + +```bash +git add chapter1.txt +git commit -m "Revise chapter 1 opening on branch" +``` + +This commit is saved locally on your branch. + +GitHub cannot see it yet. + +--- + +## Step 6: Push the Branch to GitHub + +Send the branch to GitHub: + +```bash +git push -u origin revise-chapter1-opening +``` + +The `-u` connects your local branch to the remote branch on GitHub. + +After this, GitHub can see your branch. + +--- + +## Step 7: Edit `main` on GitHub + +Now we intentionally create a conflict. + +On GitHub: + +1. Go to your `book` repository. +2. Make sure you are viewing the `main` branch. +3. Open `chapter1.txt`. +4. Click the edit pencil. +5. Change the same first line to: + +```text +Chapter 1: A Different Beginning +``` + +6. Commit the change directly to `main`. + +--- + +## Step 8: Open a Pull Request + +On GitHub, open a Pull Request: + +```text +base: main +compare: revise-chapter1-opening +``` + +This means: + +```text +Please merge revise-chapter1-opening into main. +``` + +GitHub should detect that both branches changed the same line in `chapter1.txt`. + +--- + +## Step 9: See the Conflict + +GitHub should show that the branch has conflicts. + +This is expected. + +We created this on purpose by editing the same line in two places: + +```text +main branch: Chapter 1: A Different Beginning +revise-chapter1-opening branch: Chapter 1: The Adventure Begins +``` + +--- + +## Step 10: Resolve the Conflict on GitHub + +Click **Resolve conflicts**. + +You may see something like: + +```text +<<<<<<< main +Chapter 1: A Different Beginning +======= +Chapter 1: The Adventure Begins +>>>>>>> revise-chapter1-opening + +Once upon a time, a new Git repo was born. +``` + +Your job is to edit this into the final version you want. + +--- + +## Step 11: Choose the Final Text + +For example, choose: + +```text +Chapter 1: The Adventure Begins + +Once upon a time, a new Git repo was born. +``` + +Delete the conflict markers: + +```text +<<<<<<< main +======= +>>>>>>> revise-chapter1-opening +``` + +Then click **Mark as resolved** and **Commit merge**. + +--- + +## Step 12: Merge the Pull Request + +Once the conflict is resolved, GitHub should allow the PR to merge. + +Click: + +```text +Merge pull request +Confirm merge +``` + +Now `main` on GitHub contains the final resolved version of `chapter1.txt`. + +--- + +## Step 13: Pull the Result Back Locally + +Return to your terminal. + +Switch to `main`: + +```bash +git switch main +``` + +Pull the merged result from GitHub: + +```bash +git pull +``` + +Open `chapter1.txt` and confirm that the final opening line is there. + +--- + +## Step 14: Check the History + +Use: + +```bash +git log --oneline --graph --decorate --all +``` + +You should see a history that includes: + +- the original `chapter1.txt` commit +- your branch commit +- the direct edit on `main` +- the conflict resolution / merge from GitHub + +--- + +## Optional Cleanup + +Delete the local branch after the Pull Request is merged: + +```bash +git branch -d revise-chapter1-opening +``` + +If GitHub offers to delete the remote branch after merging, you can click: + +```text +Delete branch +``` +--- + +# GitHub as Portfolio + +--- +## GitHub Portfolio Tips + +A strong GitHub profile should make your work easy to understand. + +Good habits: + +- Pin your best repositories +- Write clear README files +- Use meaningful repository names +- Keep folders organized +- Commit regularly with readable messages +- Do not upload passwords, API keys, or private data +- Make sure your project can be understood by your target audience + +--- + +## A Good README Is Your Project's Front Door + +When someone opens your repository, the README is usually the first thing they see. + +A good README answers: + +```text +What is this project? +Why does it matter? +What files are included? +How do I run it? +What tools or packages are needed? +What did you learn or produce? +``` + +--- + +# Recap + +--- + +## What We Practiced + +```bash +git branch # list branches +git switch -c new-branch # create and switch +git status # check current state +git diff # inspect changes +git add file # stage changes +git commit -m "message" # save local checkpoint +git push -u origin branch # send branch to GitHub +git pull # bring GitHub changes local +``` + +And on GitHub: + +```text +Open Pull Request +Resolve conflict +Merge Pull Request +``` + +--- + +## Big Picture + +```text +Branch = safe place to work +Pull Request = review space on GitHub +Merge = bring work back into main +Conflict = GitHub needs human judgment +``` + +A conflict is not a failure. + +It is a normal part of collaboration. + +--- + +## Discussion + +- When would you create a branch? +- Why might we prefer merging on GitHub instead of locally in this course? +- What kinds of files are likely to cause conflicts? +- How can small commits and focused branches make conflicts easier? diff --git a/03_instructional_team/git_03_repo_setup_script.sh b/03_instructional_team/repo_setup_scripts/git_03_repo_setup_script.sh similarity index 100% rename from 03_instructional_team/git_03_repo_setup_script.sh rename to 03_instructional_team/repo_setup_scripts/git_03_repo_setup_script.sh diff --git a/03_instructional_team/git_04_repo_setup_script.sh b/03_instructional_team/repo_setup_scripts/git_04_repo_setup_script.sh similarity index 98% rename from 03_instructional_team/git_04_repo_setup_script.sh rename to 03_instructional_team/repo_setup_scripts/git_04_repo_setup_script.sh index 7d7162c..bf63e30 100644 --- a/03_instructional_team/git_04_repo_setup_script.sh +++ b/03_instructional_team/repo_setup_scripts/git_04_repo_setup_script.sh @@ -1,6 +1,6 @@ #!/bin/bash -# This script extends the recipe-book repository from git_03_repo_setup_script.sh +# This script extends the recipe-book repository created by git_03_repo_setup_script.sh # It adds a community-recipes directory and a GitHub Actions workflow to # automatically approve and merge pull requests that add recipes to the # community-recipes directory, provided they are text files without executable diff --git a/03_instructional_team/git_05_repo_setup_script.sh b/03_instructional_team/repo_setup_scripts/git_05_repo_setup_script.sh similarity index 100% rename from 03_instructional_team/git_05_repo_setup_script.sh rename to 03_instructional_team/repo_setup_scripts/git_05_repo_setup_script.sh diff --git a/01_materials/01_git_intro.pdf b/04_this_cohort/additional_resources/01_git_intro.pdf similarity index 100% rename from 01_materials/01_git_intro.pdf rename to 04_this_cohort/additional_resources/01_git_intro.pdf diff --git a/01_materials/02_git_setup.md b/04_this_cohort/additional_resources/02_git_setup.md similarity index 100% rename from 01_materials/02_git_setup.md rename to 04_this_cohort/additional_resources/02_git_setup.md diff --git a/01_materials/03_git_log_checkout.md b/04_this_cohort/additional_resources/03_git_log_checkout.md similarity index 100% rename from 01_materials/03_git_log_checkout.md rename to 04_this_cohort/additional_resources/03_git_log_checkout.md diff --git a/01_materials/04_git_clone_add_push.md b/04_this_cohort/additional_resources/04_git_clone_add_push.md similarity index 100% rename from 01_materials/04_git_clone_add_push.md rename to 04_this_cohort/additional_resources/04_git_clone_add_push.md diff --git a/01_materials/05_git_merge_conflicts.md b/04_this_cohort/additional_resources/05_git_merge_conflicts.md similarity index 100% rename from 01_materials/05_git_merge_conflicts.md rename to 04_this_cohort/additional_resources/05_git_merge_conflicts.md diff --git a/01_materials/slides/git_as_story.html b/04_this_cohort/additional_resources/git_as_story.html similarity index 100% rename from 01_materials/slides/git_as_story.html rename to 04_this_cohort/additional_resources/git_as_story.html diff --git a/03_instructional_team/markdown_slides/git_as_story.md b/04_this_cohort/additional_resources/git_as_story.md similarity index 100% rename from 03_instructional_team/markdown_slides/git_as_story.md rename to 04_this_cohort/additional_resources/git_as_story.md diff --git a/01_materials/slides/git_as_story.pdf b/04_this_cohort/additional_resources/git_as_story.pdf similarity index 100% rename from 01_materials/slides/git_as_story.pdf rename to 04_this_cohort/additional_resources/git_as_story.pdf diff --git a/01_materials/git_cheatsheet.md b/04_this_cohort/additional_resources/git_cheatsheet.md similarity index 100% rename from 01_materials/git_cheatsheet.md rename to 04_this_cohort/additional_resources/git_cheatsheet.md