K
K12worX Education501(c)(3) Public Charity
Jamboree

Git Workflow

Understanding the Git workflow is essential for professional development. This guide explains how to use Git to track changes, collaborate with others, and contribute code safely.

What You'll Learn

  • The standard Git workflow
  • Why we use branches
  • The change → commit → push → PR cycle
  • How Git protects the main codebase
  • Best practices for collaboration

What is Git?

Git is a version control system that:

  • Tracks every change to your code
  • Lets multiple people work on the same project
  • Allows you to experiment without breaking things
  • Provides a history of all changes

GitHub is a website that hosts Git repositories and provides collaboration tools.

The Professional Git Workflow

Overview

1. Create branch     (work in isolation)
   ↓
2. Make changes      (write code)
   ↓
3. Test changes      (ensure it works)
   ↓
4. Commit changes    (save snapshot)
   ↓
5. Push to GitHub    (backup online)
   ↓
6. Create PR         (request review)
   ↓
7. Get reviewed      (team checks code)
   ↓
8. Merge to main     (code goes live)

Why This Process?

Protects the main codebase:

  • Main branch always works
  • Changes reviewed before merging
  • Easy to undo if something breaks

Enables collaboration:

  • Multiple people work simultaneously
  • No conflicts with others' work
  • Clear history of who changed what

The Five States of Code

1. Working Directory

What: Files on your computer State: Modified but not tracked

# You edited app/page.tsx
# Git knows it changed but hasn't saved it

2. Staging Area

What: Changes marked to be saved State: Ready to commit

git add app/page.tsx
# Now it's staged (ready to commit)

3. Local Repository

What: Committed changes on your computer State: Saved locally

git commit -m "Update homepage"
# Snapshot saved to local Git history

4. Remote Repository

What: Code on GitHub State: Backed up online

git push
# Your commits uploaded to GitHub

5. Main Branch

What: Production-ready code State: Reviewed and merged

Pull Request merged
# Your changes now in main branch

Step-by-Step Workflow

Step 1: Check Current Status

Always start here:

git status

You'll see:

  • What branch you're on
  • What files changed
  • What's staged
  • What's not tracked

Example output:

On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  modified:   app/page.tsx

Untracked files:
  components/NewComponent.tsx

Step 2: Create a Branch

Never work directly on main!

git checkout -b feature/update-homepage

Naming convention:

  • feature/description - New features
  • fix/description - Bug fixes
  • update/description - Updates to existing code

Examples:

git checkout -b feature/add-blog-page
git checkout -b fix/navigation-bug
git checkout -b update/homepage-text

Step 3: Make Your Changes

Now you can safely edit code:

  1. Open files in VS Code
  2. Make changes
  3. Save files
  4. Test in browser

While working:

git status  # Check what changed
git diff    # See exact changes

Step 4: Review Your Changes

Before committing, review:

# See all changes
git diff

# See changes for specific file
git diff app/page.tsx

What to check:

  • Only intended changes present?
  • No debug code left behind?
  • No sensitive information?
  • Changes make sense together?

Step 5: Stage Your Changes

Add files to staging area:

# Stage all changes
git add .

# Stage specific file
git add app/page.tsx

# Stage multiple files
git add app/page.tsx components/Header.tsx

Check staging:

git status

Should show:

Changes to be committed:
  modified:   app/page.tsx

Step 6: Commit Your Changes

Save a snapshot with a message:

git commit -m "Update homepage headline and subtitle"

Good commit messages:

  • Describe WHAT changed
  • Explain WHY (if not obvious)
  • Use present tense
  • Keep under 50 characters (or add detail in body)

Examples:

# ✅ Good
git commit -m "Add dark mode toggle to settings"
git commit -m "Fix navigation menu on mobile"
git commit -m "Update color scheme to match brand guidelines"

# ❌ Bad
git commit -m "changes"
git commit -m "fix stuff"
git commit -m "asdf"

Step 7: Push to GitHub

Upload your branch:

# First time pushing this branch
git push -u origin feature/update-homepage

# Subsequent pushes
git push

What happens:

  • Code uploaded to GitHub
  • Branch created on GitHub
  • Now backed up and shareable

Step 8: Create Pull Request

On GitHub:

  1. Go to repository page
  2. Click "Pull requests" tab
  3. Click "New pull request"
  4. Select your branch
  5. Add title and description
  6. Click "Create pull request"

Or use GitHub CLI:

gh pr create --title "Update homepage" --body "Description here"

Step 9: Wait for Review

What happens now:

  • Team members review your code
  • They may request changes
  • Automated tests run
  • Discussion happens in PR comments

If changes requested:

  1. Make the changes
  2. Commit them
  3. Push again
  4. PR updates automatically

Step 10: Merge

After approval:

  • Someone merges your PR
  • Your code goes to main branch
  • Your branch can be deleted

Clean up:

# Switch back to main
git checkout main

# Update your local main
git pull

# Delete your feature branch
git branch -d feature/update-homepage

Common Git Commands

Checking Status

git status              # What changed?
git log                 # Commit history
git log --oneline       # Compact history
git diff                # See changes
git diff --staged       # See staged changes

Branching

git branch                    # List branches
git checkout -b branch-name   # Create and switch
git checkout branch-name      # Switch branches
git branch -d branch-name     # Delete branch

Saving Work

git add .                     # Stage all
git add filename              # Stage specific file
git commit -m "message"       # Commit
git push                      # Push to GitHub

Undoing

git checkout -- filename      # Discard changes
git reset HEAD filename       # Unstage
git reset --soft HEAD~1       # Undo last commit

Syncing

git pull                      # Get latest from GitHub
git fetch                     # Check for updates
git pull origin main          # Update main branch

Git Best Practices

1. Commit Often

✅ Many small commits (every logical change)
❌ One huge commit at the end

Why: Easier to review, easier to undo

2. Write Clear Messages

# ✅ Good
"Add user authentication to login page"
"Fix broken link in navigation menu"

# ❌ Bad
"updates"
"fix"

3. Never Force Push

# ❌ Dangerous!
git push --force

# ✅ Safe
git push

Why: Force push can destroy others' work

4. Keep Branches Focused

✅ One feature per branch
❌ Multiple unrelated changes

Example:

  • Good: Branch for adding blog page
  • Bad: Branch that adds blog + fixes nav + updates colors

5. Pull Before You Work

# Start of each session
git checkout main
git pull
git checkout -b new-feature

Why: Ensures you have latest code

6. Don't Commit These

Never commit:

  • .env files (secrets)
  • node_modules/ (dependencies)
  • Build artifacts (.next/, dist/)
  • Personal config files
  • Large binary files

Check .gitignore file - these are already excluded

The Branch Strategy

Main Branch

Protected branch:

  • Always deployable
  • Only receives reviewed code
  • Never delete this

You cannot push directly to main!

Feature Branches

Temporary branches:

  • One feature/fix per branch
  • Created from main
  • Merged back to main via PR
  • Deleted after merge

Naming patterns:

feature/add-blog-section
fix/mobile-menu-bug
update/homepage-content
docs/update-readme

Handling Conflicts

What is a Conflict?

Happens when:

  • You change line 10
  • Someone else changes line 10
  • Both try to merge

Git doesn't know which to keep!

How to Resolve

  1. Pull latest code:
git pull origin main
  1. Git shows conflict:
<<<<<<< HEAD
<h1>Your version</h1>
=======
<h1>Their version</h1>
>>>>>>> main
  1. Edit file manually:
  • Choose which version to keep
  • Or combine both
  • Remove conflict markers
  1. Mark as resolved:
git add filename
git commit -m "Resolve merge conflict"

Best practice: Avoid conflicts by pulling often!

Git Visual Tools

VS Code Built-in

Source Control panel:

  • Click icon in sidebar
  • See changed files
  • Stage/unstage visually
  • Commit with GUI

GitHub Desktop

Free GUI app:

  • Download from desktop.github.com
  • Visual branching
  • Easy commits
  • PR creation

Command Line

Most powerful:

  • Full control
  • Faster (once you learn)
  • Works everywhere

Use what's comfortable!

Typical Day with Git

Morning

# Get latest code
git checkout main
git pull

# Create branch for today's work
git checkout -b feature/add-contact-form

During Work

# Check status frequently
git status

# Commit logical chunks
git add .
git commit -m "Add contact form component"

# Continue working
# ... edit more files ...

git add .
git commit -m "Add form validation"

End of Day

# Push your work (backup!)
git push -u origin feature/add-contact-form

# Create PR when ready
gh pr create --title "Add contact form" --body "Description"

Next Day

# Get any updates
git pull

# Continue working on same branch
# ... make more changes ...

git add .
git commit -m "Update form styling"
git push

Troubleshooting

"Nothing to commit"

You see:

nothing to commit, working tree clean

Means: No changes made or all changes committed

"Your branch is ahead"

You see:

Your branch is ahead of 'origin/main' by 2 commits.

Means: You have local commits not pushed to GitHub

Fix: git push

"Your branch is behind"

You see:

Your branch is behind 'origin/main' by 3 commits.

Means: GitHub has commits you don't have locally

Fix: git pull

"Diverged branches"

You see:

Your branch and 'origin/main' have diverged.

Means: You both have different commits

Fix: git pull then resolve any conflicts

Quick Reference

Setup:

git clone <url>              # Clone repository
git config user.name "Name"  # Set name
git config user.email "email"# Set email

Daily workflow:

git status                   # Check status
git checkout -b branch       # New branch
git add .                    # Stage all
git commit -m "message"      # Commit
git push                     # Push to GitHub

Branching:

git branch                   # List branches
git checkout main            # Switch to main
git pull                     # Update main
git checkout -b feature      # New branch

History:

git log                      # See commits
git diff                     # See changes
git show                     # Show last commit

What's Next

Now that you understand the workflow, let's learn how to create and manage branches:

Creating Branches →