Git & GitHub

Workflow Reference

Everything you need to know about branches, commits, pull requests, and merge conflicts for the Junior Accelerator sprint.

Branching

You never work directly on the main branch. Every piece of work gets its own branch. This keeps main clean and stable while you experiment and build on a separate copy of the code.

Branch naming convention

Every branch name follows this pattern:

<type>/<ticket-number>-<short-description>

The type tells anyone looking at the branch what kind of work it is:

Type	When to Use	Example
feature/	Building something new	feature/3-add-login-form
fix/	Fixing a bug	fix/5-broken-nav-link
chore/	Cleanup, refactoring, config changes	chore/7-update-readme
docs/	Documentation only	docs/1-add-setup-guide

The ticket number ties the branch to the GitHub Issue. This is important because:

Anyone looking at the repo can trace a branch back to the issue it was created for
It keeps you organized when you have multiple branches
It's standard practice on professional engineering teams

Creating a branch

Always create your branch from an up-to-date main:

# Make sure you're on main and it's up to date
git checkout main
git pull origin main

# Create and switch to your new branch
git checkout -b feature/3-add-login-form

That's it. You're now on your new branch and everything you do stays separate from main until you merge it.

Commits

A commit is a snapshot of your work at a specific point. Think of it like saving a checkpoint in a game. You want to commit often enough that you never lose meaningful progress, but not so often that every commit is just one character change.

Writing good commit messages

Your commit message should explain what you did, not what files you changed. Reference the issue number so the commit links back to the ticket.

Good commit messages:

git commit -m "Add login form layout #3"
git commit -m "Handle form validation errors #3"
git commit -m "Connect login form to auth API #3"

Bad commit messages:

git commit -m "updated stuff"
git commit -m "fix"
git commit -m "asdfasdf"
git commit -m "changes"

Commit messages are part of the permanent record of your project. Hiring managers read them. Make them count.

The basic commit workflow

# See what you've changed
git status

# Stage specific files
git add src/components/LoginForm.jsx
git add src/styles/login.css

# Or stage everything (use with caution)
git add .

# Commit with a descriptive message
git commit -m "Add login form layout #3"

# Push your branch to GitHub
git push origin feature/3-add-login-form

Pull Requests (PRs)

A pull request is how you ask for your code to be reviewed and merged into main. It's also where the conversation about your code happens. On a real team, no code gets into main without a PR and at least one review. We follow the same process here.

Opening your first PR

Push your branch to GitHub: git push origin feature/3-add-login-form
Go to the repo on GitHub. You'll see a banner saying your branch was recently pushed with a "Compare & pull request" button. Click it.
Fill in the PR description. This is important. Don't leave it blank.
Assign me as a reviewer by clicking the gear icon next to "Reviewers" on the right sidebar and selecting my username.
Click "Create pull request." That's it. I'll get a notification and review your code.

What to put in the PR description

A good PR description answers three questions. Here's a template you can copy:

## What this does
Brief description of what you built or fixed.

## How it works
Explain your approach. What decisions did you make?
What did you consider and reject?

## How to test it
Steps someone can follow to see it working.

## Ticket
Closes #3

Writing "Closes #3" in the PR description automatically closes the linked issue when the PR is merged. Use it.

Responding to code review feedback

When I review your PR, I'll leave comments on specific lines of code. Some types of feedback you might see:

Questions: "Why did you choose this approach?" I'm not saying it's wrong. I want to understand your thinking.
Suggestions: "Consider doing X instead of Y." These are optional but worth considering.
Requests: "This needs to change before we merge." These are required.

To address feedback:

Read the comments carefully and ask if anything is unclear
Make changes on the same branch (don't create a new one)
Commit and push the changes
Reply to each comment explaining what you did or why you disagree (yes, you can push back, just explain your reasoning)
Let me know when it's ready for another look

Squash merging

When your PR is approved, we merge it using "squash and merge." This takes all of your individual commits on the branch and squashes them into one clean commit on main.

Why: While you're working, it's fine to have lots of small commits like "fix typo" and "try different approach" and "actually this works." But main should have a clean history where each commit represents one completed piece of work. Squash merging gives you the best of both worlds: messy work history on your branch, clean history on main.

You don't need to do anything special for this. When you click the merge button on GitHub, just select "Squash and merge" from the dropdown instead of the default "Create a merge commit." I'll show you this on your first PR.

Merge Conflicts

A merge conflict happens when two branches have changed the same part of the same file and Git doesn't know which version to keep. This is normal. It happens on every team and it's not a sign that you did something wrong.

Merge conflicts are not errors. They are decisions waiting to be made.

What a merge conflict looks like

When you try to merge or pull and there's a conflict, Git marks the conflicting sections in the file like this:

<<<<<<< HEAD
const greeting = "Hello, world!";
=======
const greeting = "Hi there!";
>>>>>>> feature/5-update-greeting

Here's what each part means:

Marker	What It Means
<<<<<<< HEAD	The start of the conflict. Everything between here and ======= is what's currently on the branch you're merging into.
=======	The divider between the two versions.
>>>>>>> branch-name	The end of the conflict. Everything between ======= and here is what's on the incoming branch.

How to resolve a merge conflict

Don't panic. Read the conflict markers carefully. Understand what both versions are doing.
Decide what the code should actually be. Sometimes you want one version. Sometimes you want the other. Sometimes you want a combination of both.
Edit the file. Remove all conflict markers (<<<<<<, =======, >>>>>>>) and leave only the code you want to keep.
Test the code. Make sure it still works after your changes.
Stage, commit, and push.

Here's what the resolution looks like in the terminal:

# After editing the file to resolve the conflict
git add src/components/Greeting.jsx
git commit -m "Resolve merge conflict in Greeting component"
git push origin feature/3-add-login-form

Staying up to date to avoid conflicts

The best way to deal with merge conflicts is to reduce how often they happen. Pull the latest main into your branch regularly:

# While on your feature branch
git fetch origin
git merge origin/main

# If there are conflicts, resolve them now
# If there aren't, keep working

Do this at least once a day, ideally before you start working each morning. It's much easier to resolve a small conflict from one day's work than a massive one from two weeks of divergence.

Quick Reference

Copy and paste these commands. You'll use them every day.

Starting a new ticket

git checkout main
git pull origin main
git checkout -b feature/<ticket-number>-<short-description>

Saving your work

git add .
git commit -m "<description of what you did> #<ticket-number>"
git push origin <your-branch-name>

Staying up to date

git fetch origin
git merge origin/main

After PR is approved

# On GitHub: Click "Squash and merge"
# Then locally:
git checkout main
git pull origin main
# Start your next ticket from here

Common Mistakes (and How to Fix Them)

Mistake	What Happens	How to Fix
Committing directly to main	Your work isn't on a branch and can't be reviewed via PR	Create a branch now, move your commits there. Ask me if you need help.
Forgetting to pull before branching	Your branch is based on old code and you'll get more conflicts	`git fetch origin && git merge origin/main` on your branch
Giant commits with everything in one	Hard to review, hard to understand, hard to revert if something breaks	Commit more often. Each commit should be one logical change.
Pushing sensitive data (API keys, passwords)	Security risk. Even if you delete it, it's in the Git history.	Use a .env file and add it to .gitignore. Never commit secrets.
Deleting conflict markers but not testing	The code might not work even though the conflict is "resolved"	Always run and test the code after resolving a conflict.

Learn with O.J. · learnwithoj.com A working engineer helping other engineers level up.

Git Github Workflow Reference