Git Workshop

Interactive Git workshop materials with a real-time visualizer that reads your actual .git directory.

Quick Start

# 1. Install dependencies
cd visualizer
npm install

# 2. Start the visualizer (point it at any repo)
node server.js /path/to/your/repo

# Or visualize current directory
node server.js

# 3. Open browser
open http://localhost:3456

What's Included

git-workshop/
├── HANDS_ON_SCRIPT.md     # Full workshop script (participants follow along)
├── SCRIPT.md              # Instructor reference/notes
└── visualizer/
    ├── server.js          # Node.js server that reads .git
    └── public/
        └── index.html     # Browser-based visualization

Visualizer Features

• Real-time updates: Watches your .git directory and updates instantly
• Commit graph: Shows branches, merges, HEAD position
• Conventional commits: Color-coded by type (feat=green, fix=red, docs=blue, etc.)
• Three areas diagram: Working directory, staging area, repository
• Branch/remote sidebar: Shows all branches, remotes (origin/upstream highlighted)
• File status: Staged, modified, untracked files
• Switch repos: Change the visualized repo without restarting

Workshop Topics Covered

1. Origin vs Upstream (8 min)

   • Fork workflow
   • git remote add upstream
   • Syncing your fork

2. Atomic Commits (10 min)

   • One logical change per commit
   • git add -p for partial staging
   • Why it matters

3. Conventional Commits (10 min)

   • type(scope): description format
   • Types: feat, fix, docs, style, refactor, test, chore
   • Breaking changes

4. Git Bisect (12 min)

   • Binary search for bugs
   • Manual bisect
   • Automated git bisect run

Running the Workshop

Instructor Setup

1. Create a GitHub repo for collaboration (participants will fork it)
2. Start the visualizer on your machine
3. Share your screen showing terminal + browser with visualizer

Participant Requirements

• Git installed (git --version)
• GitHub account
• Node.js (optional, for running their own visualizer)

Tips

• Use a large terminal font (16pt+)
• Keep the visualizer visible alongside terminal
• Let participants catch up at each checkpoint
• Have the cheat sheet ready for quick reference

Cheat Sheet

┌─────────────────────────────────────────────────────────┐
│ REMOTES                                                 │
│   origin   → YOUR fork (you push here)                  │
│   upstream → original repo (you PR here)                │
├─────────────────────────────────────────────────────────┤
│ ATOMIC COMMITS                                          │
│   One logical change = one commit                       │
│   git add -p file.js    # stage hunks                   │
├─────────────────────────────────────────────────────────┤
│ CONVENTIONAL COMMITS                                    │
│   type(scope): description                              │
│   feat | fix | docs | style | refactor | test | chore  │
├─────────────────────────────────────────────────────────┤
│ BISECT                                                  │
│   git bisect start                                      │
│   git bisect bad        # mark current bad              │
│   git bisect good SHA   # mark known good               │
│   git bisect run ./test.sh  # automate                  │
│   git bisect reset      # finish                        │
└─────────────────────────────────────────────────────────┘

Customization

Change port

PORT=8080 node server.js /path/to/repo

Switch repos without restarting

Use the input field in the browser, or:

curl "http://localhost:3456/api/set-repo?path=/new/repo/path"