Learning objectives
- > Understand what Git tracks and why: commits, branches, and the three areas where your files live
- > Know when to ask Claude Code to commit, branch, merge, push, or pull — and why each action matters
- > Set up a GitHub repository for a journalism project using Claude Code
- > Collaborate on a shared project by understanding pull requests, merge conflicts, and remote repositories
Before you start
You've been building things with Claude Code — scripts, project folders, processed documents. But every project reaches a point where you need to track what changed, go back to something that worked, or share your work with someone else. Git is how you do all three.
You don't need to memorize Git commands. Claude Code knows them. Your job is understanding the concepts well enough to know what to ask for and when to ask for it. This module gives you that understanding.
The visual explainers below are inspired by "Git Will Finally Make Sense After This" by LearnThatStack — a video that explains Git through visuals and metaphors rather than command syntax. We take the same approach here.
Key concepts
What is Git?
Git is a version control system. It keeps a complete history of every change made to every file in a project. Think of it as an unlimited undo button that works across your entire project — not just one file, but every file in the folder, and not just the last change, but every change you've ever recorded.
GitHub is a website that hosts Git projects online. Git runs on your computer. GitHub stores a copy in the cloud so you can back up your work, share it with colleagues, or publish it publicly.
SAVING vs. COMMITTING
The three areas: where your files live
Git organizes your project into three areas. Understanding these is the key to knowing when to ask Claude Code for what.
THE THREE AREAS OF A GIT PROJECT
WORKING DIRECTORY — The folder on your computer where you (and Claude Code) edit files. Changes here are not yet tracked by Git. If you delete something, it's gone — unless it was previously committed.
STAGING AREA — A preparation zone. When you tell Claude Code to stage changes, you're selecting which edits should be included in the next commit. Think of it as laying out pages on a table before binding them into a book. You don't have to stage everything — you can commit only the files that belong together logically.
REPOSITORY — The permanent record. Once changes are committed, they're stored in the repository's history. You can always go back to any previous commit. The repository lives inside a hidden .git folder in your project.
Commits: snapshots, not saves
A commit is a snapshot of your entire project at one moment in time. Every commit has three things: a unique ID (a long string of letters and numbers), a message you write describing what changed, and a pointer to the previous commit. Together, they form a timeline.
A PROJECT'S COMMIT TIMELINE
When to commit: After you reach a meaningful checkpoint. The analysis script works. The data file is cleaned. The bug is fixed. Don't commit after every keystroke — commit after each logical unit of work.
What to say in the message: Describe what changed and why. "Add council vote data for January through March" is useful. "Update files" is not. Good commit messages are your future self's breadcrumbs.
Branches: parallel timelines
A branch is a separate line of development. The default branch is called main. When you create a new branch, you're saying: "I want to try something, but I don't want to touch the working version until I'm sure it works."
BRANCHING AND MERGING
When to branch: Before trying anything risky. Refactoring a working script. Testing a new analysis approach. Experimenting with a different data format. Tell Claude Code: "Create a new branch called [name] before making these changes."
When to merge: When the experiment works. Tell Claude Code: "Merge the [name] branch back into main." If the experiment failed, tell Claude Code to delete the branch — main stays untouched.
A branch is not a copy. This is a common misconception. A branch is a lightweight pointer — Git doesn't duplicate your files. It just tracks a separate line of changes. That's why branches are fast to create and cheap to keep.
Remote repositories: Git + GitHub
So far, everything has happened on your computer. A remote repository is a copy of your project stored somewhere else — usually on GitHub. This gives you backup, collaboration, and publishing.
YOUR COMPUTER ↔ GITHUB
Push: Sends your local commits to GitHub. Tell Claude Code: "Push my changes to GitHub." Do this when you want to back up, share, or publish your work.
Pull: Gets new commits from GitHub that you don't have locally. Tell Claude Code: "Pull the latest changes from GitHub." Do this at the start of a work session if someone else might have made changes, or if you're switching between computers.
Clone: Downloads an entire repository from GitHub to your computer for the first time. Tell Claude Code: "Clone this repository" and give it the URL. This is how you get someone else's project — or your own project on a new computer.
Pull requests: the editorial review of code
A pull request (PR) is a proposal to merge one branch into another. It's GitHub's system for review. You do your work on a branch, push that branch to GitHub, and then open a pull request that says: "Here's what I changed. Review it before it goes into main."
PULL REQUEST WORKFLOW
Pull requests are where collaboration happens on GitHub. They show exactly what changed, let reviewers leave comments, and create a record of who approved what. In a newsroom context, they're how you get a second pair of eyes on an analysis before it goes live.
Merge conflicts: when two edits collide
A merge conflict happens when two branches change the same lines of the same file. Git doesn't know which version to keep, so it asks you to decide.
WHEN A MERGE CONFLICT HAPPENS
Conflicts are not errors — they're a normal part of collaboration. They mean two people were productive on the same file. When a conflict happens, Claude Code can show you exactly which lines conflict and help you decide which version to keep, or combine them.
What to tell Claude Code: "There's a merge conflict. Show me what both sides changed and help me resolve it." Claude Code will display the conflicting sections side by side and ask you which version to keep.
What to ask Claude Code: a quick reference
You don't need to know the commands. You need to know what to ask for. Here's when to say what:
STARTING A PROJECT
"Initialize a Git repository in this folder and make the first commit."
SAVING A CHECKPOINT
"Commit my changes with a message describing what I just did."
TRYING SOMETHING RISKY
"Create a new branch called [name] before making these changes."
THE EXPERIMENT WORKED
"Merge the [name] branch back into main."
BACKING UP / SHARING
"Push my changes to GitHub."
GETTING TEAM UPDATES
"Pull the latest changes from GitHub."
SOMETHING BROKE
"Show me the history and go back to the last commit where [thing] worked."
GETTING A PROJECT
"Clone this repository: [paste GitHub URL]."
EXERCISE
GOAL: Use Claude Code to set up a version-controlled journalism project, make commits at meaningful checkpoints, experiment on a branch, and push the project to GitHub.
01 Launch Claude Code
Open your terminal and start an interactive session:
claude02 Create a project and initialize Git
Ask Claude Code to set up a journalism project with version control from the start:
Create a new folder called "city-hall-tracker" with these files:
1. A CLAUDE.md that describes this as a project tracking city council votes, with instructions to format output as markdown and include source attribution.
2. A README.md explaining the project's purpose.
3. A votes.csv with five rows of sample city council vote data: date, council member name, issue, and vote (yes/no).
Initialize a Git repository and make the first commit with the message "Initial project setup with context file, README, and sample data."Watch what Claude Code does. It creates the files, initializes Git, stages everything, and commits — all from one prompt.
03 Add data and commit the change
Now ask Claude Code to modify the project and record the change:
Add five more rows of city council vote data to votes.csv. Use different issues than the first five — things like park funding, zoning changes, and library hours.
Then commit this change with a message describing what you added.04 Explore the project history
Show me the full Git history of this project. For each commit, tell me what changed in plain English.This is where version control starts to feel real. You can see every checkpoint in your project's life.
05 Branch, experiment, merge
Try branching — the concept that lets you experiment without risk:
Create a new branch called "add-analysis" and switch to it. Then write a Python script called analyze_votes.py that reads votes.csv and prints a summary: total votes, yes vs. no breakdown, and which council member voted "no" the most.
Commit the script to this branch.Now merge it back:
Switch back to the main branch and merge the add-analysis branch into it. Confirm the merge worked by showing me the Git log.06 Push to GitHub
Create a new private repository on GitHub called "city-hall-tracker" and push this entire project to it. If GitHub CLI isn't set up yet, walk me through the setup.Claude Code will handle the GitHub CLI authentication if needed. Your project is now backed up and shareable.
Checkpoint
Self-check: Make sure you can answer these before moving on.
- ? What's the difference between saving a file and committing in Git?
- ? Name the three areas where files live in a Git project.
- ? When should you create a branch?
- ? What does "push to GitHub" mean, and when would you do it?
- ? What is a pull request, and why does it matter for collaboration?
Resources
- [VIDEO] Git Will Finally Make Sense After This — LearnThatStack visual walkthrough
- [INTERACTIVE] Learn Git Branching — Visual, interactive playground for branches and merges
- [DOCS] GitHub quickstart — Official guide to repositories, commits, and pull requests
- [REF] git - the simple guide — Single-page reference with no deep jargon
- [COURSE] GitHub Skills — Free interactive courses on pull requests, conflicts, and GitHub Pages
Troubleshooting
"fatal: not a git repository"
You're in a folder that doesn't have Git initialized. Ask Claude Code: "Initialize a Git repository in this folder." Or navigate to the correct project folder first.
Claude Code says "nothing to commit"
All your changes are already committed, or you haven't made any changes since the last commit. This is fine — it means your project is up to date.
"failed to push" or authentication errors with GitHub
GitHub CLI may not be authenticated. Ask Claude Code: "Check if GitHub CLI is installed and authenticated. If not, walk me through the setup." The gh auth login flow opens a browser window similar to Gemini CLI's authentication.
"merge conflict" during merge
This means two branches changed the same lines. It's normal. Ask Claude Code: "Show me the conflict and help me resolve it." Claude Code will display both versions and help you pick the right one.
"your branch is behind" when pushing
Someone else (or you on another computer) pushed changes you don't have locally. Ask Claude Code: "Pull the latest changes from GitHub first, then push my changes."