Claude Code Tutorial Part 9: Syncing GitHub with Your Computer

Part 9 of 9 of Building a Website with Claude Code. See all parts.

Syncing GitHub with your computer

You have files on your laptop. You have a copy on GitHub. The two need to stay in agreement. If they drift apart, "the latest version" stops being a meaningful idea, and you waste an evening untangling which file was newest where.

This part teaches the small set of commands that keep the two in sync. None of it is hard. It is, however, the part of a project people most often skip and most often regret.

How to read this part, start to end

Each section builds on the one before it. The reading order is the working order:

1. Why and how (Sections 32–33). What GitHub gives you as an engineer, then the one-off install of Git (and Homebrew on macOS).
2. Build something real, locally (Section 34). Make a CV website in ~/Downloads/cvwebsite/ using Claude Code. No Git yet. This is the project you will push to GitHub in the next sections.
3. Core mental model (Section 35). Local repo, remote repo, the three commands that move work between them.
4. The basic sync (Sections 36–39). Clone, push, pull, then the safe five-command daily habit.
5. Engineering practice (Section 40). Branches, pull requests, the small disciplines that turn Git into a real workflow.
6. Multi-machine and edge cases (Sections 41–45). Two computers, the GitHub web UI, conflicts, SSH so you stop typing passwords, and a troubleshooting cheat sheet.
7. Ship it (Sections 46–48). Publish for free on GitHub Pages, push the CV you built in Section 34, then a second worked example: a personal portfolio with your photo.

Work through the part once in order. After that, jump back to any section as a reference whenever you need it.

Why every engineer needs GitHub

Most of this part is mechanics: clone, push, pull, sync. Before you learn the mechanics, it helps to know why this matters for you specifically as someone building software, and not just as a tutorial-follower.

A remote like GitHub (or its peers — GitLab, Bitbucket, a self-hosted forge) is the single most useful tool in the working engineer's belt. Nine concrete reasons:

1. Backup that matches your laptop, byte for byte. If your machine dies tonight, every line of code, every commit message, every branch is one git clone away on a new machine. No "I think I emailed it to myself last week" archaeology. No lost evening over a spilled coffee.

2. A complete change history you can read. Every commit is a snapshot with a message attached. Six months from now you can ask "what changed in the auth flow last Tuesday and why?" and read the answer. git blame shows who wrote any given line and the commit message they left for it. Future-you will thank present-you for the discipline.

3. Branches let you experiment without fear. When you want to try something risky — a different framework, a big refactor, an idea that might not work — you make a branch, mess about, and either merge it or throw it away. The main branch stays stable while you explore. This is the difference between "tinkering on a copy" and "breaking the live site."

4. Two computers, one project. Home laptop in the evening, work laptop in the morning, the cafe in between. The remote keeps every machine in sync; you push what you finished, then pull it on the other side.

5. Code review, even with yourself. Opening a pull request against your own main branch makes you read your changes the way a colleague would. You catch your own typos, half-finished tests, and "why did I do this?" decisions before they land in production.

6. Real collaboration without zip files. When someone else needs to contribute — a designer, a contractor, a teammate — you do not email folders around. They clone, branch, push, open a PR. You review, you merge. Git keeps a clean record of who changed what and why.

7. Hosting platforms read from it. Cloudflare Pages, Netlify, Vercel, Railway, Render, GitHub Pages, and even Hostinger's git-deploy all watch a repo and redeploy automatically when you push. The remote becomes your deployment trigger: no FTP uploads, no "did I forget a file?" anxiety.

8. Your portfolio and your credibility. Recruiters and hiring managers look at GitHub profiles. A well-tended repo with thoughtful commit messages and a clean README signals more about how you work than a CV bullet does. The earlier you start, the longer the trail of evidence.

9. Industry baseline. Almost every professional engineering team uses Git and a remote. Comfort with pull, push, branch, merge, and pull requests is table stakes. Learning it once means you will never be the person in a job interview who says "I have not really used Git."

The rest of this part teaches the mechanics that turn that list into a daily habit. Treat the next thirty minutes as an investment that repays itself every working week for the rest of your career.

Installing Git (and Homebrew on macOS)

Before any of the workflows below, your computer needs the git command itself. The check is the same on every platform:

git --version

If you see something like git version 2.45.0, skip the rest of this section — you are ready. If the terminal says "command not found", install Git using the instructions for your platform.

macOS

There are two easy ways. Homebrew is the recommended path because it makes every other developer tool you will install easier, including the version of Git you want to keep up to date.

Option A: Homebrew (recommended).

Homebrew is the package manager for macOS — a single command installs and updates other tools like Git, Node, Python, and so on.

Step 1: Install Homebrew.

Open Terminal (Cmd+Space, type "Terminal", Enter) and paste:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

The script will ask for your macOS password and explain what it is about to do. Read what it prints, then press Enter to continue. The install takes a few minutes.

At the very end the script prints two "Next steps" commands that look like this — copy and run them, replacing your-name with your actual username:

echo >> /Users/your-name/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/your-name/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

That puts brew on your PATH permanently. Confirm Homebrew works:

brew --version

Step 2: Install Git via Homebrew.

brew install git

Confirm:

git --version

Step 3 (one-time): tell Git who you are.

These two lines stamp every commit with your name and email. Use the same email that is on your GitHub account:

git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"
git config --global init.defaultBranch main

The last line makes new repos default to a main branch (instead of the older master), matching GitHub's convention.

Option B: Apple Command Line Tools (no Homebrew).

If you only need Git and nothing else, you can install the Apple-provided version:

xcode-select --install

A system dialog asks you to confirm. Click Install. When it finishes, run git --version to check, then complete Step 3 (one-time) above to set your name and email.

Tip: Homebrew is worth the extra ten minutes. You will install other developer tools later — Node, Python, the GitHub CLI — and Homebrew is the path of least resistance for all of them.

Windows

The official Git for Windows installer bundles git, Git Bash (a real Bash shell), and the OpenSSH client.

Step 1: Download the installer.

Visit https://git-scm.com/download/win and download the 64-bit Standalone Installer. Run it.

Step 2: Accept the defaults.

The installer has many screens. The defaults are sensible for almost everyone — keep clicking Next until you reach Install. The two screens worth pausing on:

• "Choosing the default editor" — pick Visual Studio Code if you installed it earlier, otherwise leave Vim (you will rarely see it).
• "Configuring the line ending conversions" — leave the default ("Checkout Windows-style, commit Unix-style line endings"). This avoids Mac/Windows file-line-ending mismatches in shared repos.

Step 3: Confirm Git is on your PATH.

Close any old PowerShell windows and open a new one. Then:

git --version

If you see git version 2.x.x, you are set.

Step 4 (one-time): tell Git who you are.

In PowerShell (or Git Bash):

git config --global user.name "Your Name"
git config --global user.email "your-email@example.com"
git config --global init.defaultBranch main

Linux

Most Linux distributions ship Git in the standard package repos:

# Debian, Ubuntu, Mint, etc.
sudo apt update && sudo apt install git

# Fedora, RHEL
sudo dnf install git

# Arch
sudo pacman -S git

Then run the same git config --global lines as above to set your name, email, and default branch.

Verify the install with one command

On any platform, run:

git --version && git config --global --get user.name && git config --global --get user.email

You should see the Git version, your name, and your email on three lines. If all three look right, you are ready for the rest of this part.

Build your first project: a CV website (no GitHub yet)

Before you learn the GitHub mechanics, build something real. Having a finished project on your laptop makes the rest of this part concrete — instead of pushing "a repo," you will be pushing your CV site, the one you made in this section.

This walkthrough makes no assumptions about Git or GitHub yet. You will create a folder, drop your CV and a photo into it, ask Claude Code to build a mobile-responsive CV website around them, and open it in a browser. The GitHub sections that follow will take this exact folder online.

Step 1: open a Terminal in the Downloads folder

On macOS: press Cmd+Space, type "Terminal", press Enter. Then:

cd ~/Downloads

On Windows: open PowerShell from the Start menu. Then:

cd $HOME\Downloads

cd stands for "change directory" — it moves your terminal session to that folder.

Step 2: make a folder for the project

mkdir cvwebsite
cd cvwebsite

mkdir makes a new folder ("make directory"); the second cd moves you inside it. Your terminal is now sitting inside ~/Downloads/cvwebsite/. Anything Claude writes from this point on goes into that folder.

To prove you are in the right place:

pwd     # macOS / Linux — prints "/Users/yourname/Downloads/cvwebsite"

On Windows PowerShell use Get-Location instead of pwd.

Step 3: drop your CV and a photo into the folder

Open Finder on Mac (or File Explorer on Windows). Navigate to Downloads/cvwebsite/. Copy in:

• Your CV as a PDF (cv.pdf) or Word document (cv.docx). Either is fine — Claude can read both.
• A square headshot photo named me.jpg (or .png). Around 800×800 px works well. Take a clear, well-lit photo on your phone and crop it square if you do not already have one. No photo? Skip; Claude will leave a placeholder you can swap in later.

The folder should now contain two (or three) files.

Step 4: start Claude Code

Still in Terminal, inside the cvwebsite folder, run:

claude

You should see Claude Code's welcome screen. Claude is now reading from the current folder — your cvwebsite project.

Step 5: paste this prompt

Copy the whole block below, change the LinkedIn URL to your real handle (or leave the placeholder for Claude to fill in later), and press Enter:

Read the CV file in this folder (cv.pdf or cv.docx) and extract: my name, current role, a one-paragraph summary, work experience with dates, education, skills, and contact details. Also use me.jpg (or me.png) for the hero photo if present.

Build a single-page CV website in this folder following these rules:

1. Stack. Plain index.html, Tailwind CSS via the official CDN (https://cdn.tailwindcss.com), and a small script.js. No build step, no framework, no Node packages. Opening index.html in a browser must just work.

2. Sections, in order: Hero (my circular photo if present, name, role, one-line tagline, two CTA buttons — "Download CV" and "LinkedIn"); About; Experience (vertical timeline); Skills (grouped tags); Contact (email, LinkedIn).

3. Mobile-first responsive. Design for 320 px first, then scale up. Test the layout at 320, 768, and 1280 px in dev tools.

4. Mobile menu. On screens below 768 px, the top header collapses to a hamburger icon on the right (the brand stays on the left). Tapping it opens a slide-down menu with four section links — About, Experience, Skills, Contact. Tapping a link smooth-scrolls to that section and closes the menu. The menu must be keyboard-accessible (Tab through, Enter to activate, Escape to close) and have visible focus rings. On screens 768 px and above, hide the hamburger and show those four links as a normal horizontal top nav.

5. Download CV. The "Download CV" button links to cv.pdf in the same folder, using the download attribute. If only a .docx is present, link to that instead.

6. User-centred design. Strong visual hierarchy, generous whitespace, one primary CTA per viewport, WCAG AA colour contrast, body text 16 px or larger, visible focus states on keyboard navigation, prefers-reduced-motion respected, alt text on every image.

Before you write any code, do three things and wait for my answer: (a) Tell me what you extracted from my CV (name, current role, summary, latest role). (b) Propose the visual style in one paragraph: colour palette (3–4 hex codes), font pair, and a one-line "feel" description. (c) List the files you intend to create.

When I say "go ahead," create the files and finish by showing me the file tree and how to open the site (I am on macOS).

Step 6: review, approve, view

Claude replies with the three preview items. Read each:

• Is the extracted CV info correct? If a job title or date is wrong, paste the correction in plain English: "My role is Senior Data Engineer, not Data Analyst."
• Is the proposed style right for you? If the palette feels off, redirect: "Make it warmer with a coral accent and use a serif heading font."
• Is anything missing from the file list? Add it: "Also include a print.css so the page prints cleanly to a single A4 page."

Only when you are happy do you say "go ahead." Claude writes the files.

Open the site in your browser:

open index.html     # macOS
start index.html    # Windows PowerShell

Resize the browser narrower than 768 px — the top nav should collapse into a hamburger button; tap it and the menu should slide down with smooth-scroll links. Wider, and the four links should appear as a normal top header. Click Download CV — it should download cv.pdf (or your .docx).

You now have a working CV site on your laptop. The rest of Part 9 teaches the workflow to put it on GitHub and serve it on a free public URL.

Tip: Stay inside ~/Downloads/cvwebsite/ for everything that follows in this part. Many of the workflows below assume you are in the project folder; if you ever feel lost, run pwd (Mac/Linux) or Get-Location (PowerShell) to see exactly where you are.

The mental model: local and remote

There are two repositories. One on your computer, one on GitHub.

• Local repository: the folder on your laptop. The version you edit.
• Remote repository: the copy on GitHub. The version other people see, the version that survives if your laptop dies, the version your hosting provider can pull from.

Three commands move work between them:

• git clone <repo-url> — copy the remote onto a fresh computer for the first time.
• git push — send your local commits up to GitHub.
• git pull — bring GitHub's commits down to your computer.

That is the whole shape of it. Everything else in this part is detail.

Tip: Think of push and pull like uploading and downloading. push uploads your changes; pull downloads other people's changes.

First-time sync: GitHub to your computer

When you (or anyone else) wants to work on the project on a new machine, you copy it down once with git clone. This is a one-off — not something you re-run every day.

You'll need the repository URL from GitHub. Open the repo in a browser, click the green Code button, and copy the HTTPS URL. It looks like https://github.com/your-username/your-repo.git.

On macOS, in Terminal:

cd ~/Documents
git clone https://github.com/your-username/your-repo.git
cd your-repo

On Windows, in PowerShell:

cd $HOME\Documents
git clone https://github.com/your-username/your-repo.git
cd your-repo

After cloning, the project appears as a new folder inside whichever folder you were in (here, Documents). The folder name matches the repository name. Open it in VS Code and you're ready to work.

Warning: Run git clone once per computer, not once per session. Running it again into the same folder will error or overwrite your work.

Daily sync: from your computer to GitHub

You changed some files. You want GitHub (and everyone pulling from it) to have those changes. Four commands:

git status
git add .
git commit -m "Update homepage hero copy"
git push

What each line does:

• git status — shows which files you have changed since the last commit. Read this first; it is the cheapest way to spot something you did not mean to include (a stray .env, a debug file).
• git add . — stages all the changes in the current folder. "Staging" means "include this in the next snapshot."
• git commit -m "message" — saves a snapshot of the staged changes to your local history. The message is a one-line description of why you made the change, not just what.
• git push — uploads the new commits to GitHub.

Until you push, your work lives only on your laptop. If the laptop dies, those commits die with it. Push often.

Tip: Write commit messages someone else could read in six months and still understand. "Fix bug" tells you nothing. "Fix contact form not sending on Safari" tells you everything.

Daily sync: from GitHub to your computer

If anything has changed on GitHub since you last looked, pull it down before you start working:

git pull

That is the whole command. It downloads new commits and updates the files in your folder.

When to run it:

• You worked on this project on another computer yesterday.
• A teammate pushed something.
• You edited a file directly in the GitHub web interface.
• It has been more than a day since you last touched the project — pull just in case.

Tip: git pull only updates what is tracked by Git. Files you have created locally but never committed are left alone.

The safe recommended workflow

Five commands, every working session:

git pull
git status
git add .
git commit -m "Describe your change"
git push

pull first, so you start from the latest version. Edit. status to check what you changed. add to stage. commit to snapshot. push to share.

Get this into your muscle memory and you will avoid most of the sync problems people complain about.

Branches and the engineer's working method

The five-command habit from the previous section is the bare minimum for keeping your work and GitHub in sync. Professional engineers extend that with branches and a small set of habits that turn Git from "a backup tool" into a real engineering workflow.

This section explains what a branch is, when to use one, and the small disciplines that separate hobby Git from how real teams work.

What a branch is

A branch is a parallel line of work in your repo. Picture the main branch as the trunk of a tree: it should always be in a known-good state, the version you would be happy to ship. A feature branch is a small twig where you try something — a new feature, a refactor, an experiment, a content edit. When the twig is happy, you merge it back into the trunk. If it goes wrong, you throw the twig away and the trunk is untouched.

That single mental shift — "main is sacred; my work happens on a branch" — is the difference between hobby Git and professional Git.

Why engineers use branches

Without branches, every commit goes to main. Half-finished experiments, broken intermediate states, and finished features all pile up on the same timeline. With branches, each unit of work is isolated:

• Reversibility. A bad idea can be thrown away with one command (git branch -D bad-idea) and main is untouched.
• Focus. One branch equals one change. The diff is small, the commit messages are clear, the review is fast.
• Parallel work. You can be in the middle of a refactor on one branch and switch to a bug fix on another in two seconds.
• Code review. A branch is what you open a pull request from — the place where a colleague, or future-you, reviews the change before it lands.
• Safe deploys. If main is what gets deployed to production, branches keep work-in-progress out of production by default.

The basic branch commands

Start a new branch from main:

git switch -c add-projects-section

switch -c means "switch to a new branch with this name and base it on the current branch." Any commit you make from now on lands on add-projects-section, not on main.

See which branch you are on:

git branch

The current branch is marked with an asterisk.

Switch between branches:

git switch main
git switch add-projects-section

Push the branch up to GitHub the first time:

git push -u origin add-projects-section

The -u tells Git "remember this remote branch for future pushes and pulls." After the first push, plain git push works.

A complete feature-branch flow

For every piece of work — a new feature, a bug fix, a content tweak — repeat this loop:

git switch main
git pull
git switch -c short-description-of-change
# … edit files, ask Claude to do work …
git add .
git commit -m "Add projects section to portfolio"
git push -u origin short-description-of-change

On GitHub, open the repo and click Compare & pull request in the yellow banner at the top. Add a title and a short description (what changed and why), then Create pull request. The PR page shows the diff between your branch and main, comment-by-comment — it is much easier to read than the same files in your editor.

When you are happy with the review, click Squash and merge (recommended for solo work — keeps main history tidy) or Create a merge commit (preserves every commit on the branch). GitHub merges your branch into main.

Back on your laptop, pull the merged result and clean up the local branch:

git switch main
git pull
git branch -d add-projects-section

Good engineering habits with Git

These small disciplines pay off every working week:

• Never commit straight to main on a real project. Even for a one-line change, make a branch, open a PR, and merge it. It costs sixty seconds and gives you a reviewable record.
• One change, one branch, one PR. If you start fixing a typo and also rename a variable, that is two branches and two PRs. It feels slower; it is much faster to review and revert.
• Write commit messages someone else can read. "Fix bug" tells nobody anything. "Fix login error when email contains a plus sign" tells you the bug, the cause, and the fix in a single sentence.
• Use a .gitignore from day one. Anything generated, downloaded, or private — node_modules, .env, build outputs, OS junk like .DS_Store — belongs in .gitignore. Ask Claude: "Generate a .gitignore for a static HTML/Tailwind site."
• Push often, even mid-work. Push at the end of every working session, even if the branch is unfinished. Your work is now backed up; your laptop can die guilt-free.
• Pull before you push. Always. It is the cheapest way to avoid a "rejected — non-fast-forward" surprise (see the troubleshooting section in this part).
• Keep main deployable. The version on main should always be a version you would be happy to ship. That is the whole point of branches.
• Read your own diffs before you commit. git diff (unstaged) and git diff --staged (staged) show exactly what is about to land. Catch typos and accidental edits before the commit, not after.
• Atomic commits. Each commit should make sense on its own. "Add header markup and styles" is fine; "morning's work" is not.

Tip: Branches feel like overhead when you are working alone. They are not — they are how you collaborate with future-you. A clean main six months from now is much easier to navigate than a soup of "WIP" and "more stuff" commits.

Warning: Avoid long-lived branches. A branch that lives for weeks drifts away from main and becomes painful to merge. Aim to land each branch within a day or two. If something is going to take longer, break it into smaller pieces with their own branches.

Tip for using Claude on a branch: Tell Claude up front: "We are on a branch called add-projects-section. Do not commit, push, or switch branches yourself — just edit files. I will handle Git." That keeps Claude focused on the code change and prevents accidental commits to the wrong branch.

Syncing across two computers

You work from a home computer and a work or school computer. The pattern is symmetric: whatever you do on one machine, you push; whatever you start on the other machine, you pull.

Tuesday evening, on the home computer:

git add .
git commit -m "Add About page draft"
git push

Wednesday morning, on the work computer:

git pull

You now have last night's work, ready to continue.

If the work computer has never seen the project before, run git clone once first:

git clone https://github.com/your-username/your-repo.git

After that, daily life is pull at the start and push at the end.

Warning: Always push before walking away from a machine. The single most common cause of a wasted morning is "I forgot to push from home last night."

Editing files directly on GitHub

GitHub's web interface lets you edit a file in the browser: open the file, click the pencil icon, change the text, click Commit changes. That commit lives on GitHub immediately. It does not appear on your computer until you ask for it.

To bring those edits down:

git pull

This catches up your laptop with whatever you (or anyone else) changed on GitHub.

Tip: Browser edits are handy for one-line fixes, typos, or editing the README. For anything bigger, do it locally — you get spell-check, version history, and the safety of a real editor.

Sync conflicts explained simply

A conflict happens when the same lines of the same file were edited in two places before either side was synced. Git will not guess which one you meant; it asks you to choose.

Concrete scenario:

1. On your laptop, you change index.html and commit but do not push.
2. On GitHub (in the browser), you also change the same lines in index.html.
3. You run git pull on your laptop. Git cannot tell which version wins.

When you open the conflicted file, you will see markers like this:

<<<<<<< HEAD
My local version
=======
The GitHub version
>>>>>>> main

The block between <<<<<<< and ======= is your local version. The block between ======= and >>>>>>> is the GitHub version. To resolve:

1. Decide which version to keep — or combine them.
2. Delete the <<<<<<<, =======, and >>>>>>> lines entirely.
3. Save the file.
4. Run:

git add .
git commit -m "Resolve sync conflict"
git push

Tip: If you are unsure, ask Claude. Show it the file with the conflict markers and ask, "Help me resolve this conflict — I want to keep the GitHub version of the title and my local version of the body."

Setting up SSH so pushes do not ask for a password

The first time you git push, GitHub asks who you are. Pasting a Personal Access Token every few months works, but SSH keys are nicer: set them up once, push forever.

An SSH key is a pair of files on your computer:

• A private key (id_ed25519) that never leaves your machine.
• A public key (id_ed25519.pub) that you upload to GitHub.

When you push, the two are matched. If they pair, the push goes through. No password, no token expiry.

Tip: A passphrase on the private key is more secure but means typing it once per session. For a personal laptop, an empty passphrase is a reasonable trade-off; for a shared or work machine, set one.

The setup is slightly different on macOS and Windows. Pick the section that matches your computer and follow it end to end. The shared steps — add the key to GitHub, test the connection, switch existing repos — come after both walkthroughs.

macOS: full SSH setup

macOS comes with OpenSSH installed. Open Terminal (Cmd+Space, type "Terminal", Enter).

Step 1: Check whether you already have a key.

ls -al ~/.ssh

If you see id_ed25519.pub or id_rsa.pub, you already have one — skip to Step 4 (copy public key). If you see No such file or directory, you have none yet — continue.

Step 2: Generate a new key.

ssh-keygen -t ed25519 -C "your-email@example.com"

Replace the email with the one on your GitHub account. Press Enter three times to accept the defaults:

• File location: /Users/your-name/.ssh/id_ed25519
• Passphrase: leave empty (just press Enter)
• Confirm: press Enter again

You should see "Your identification has been saved..." and a key fingerprint.

Step 3: Add the key to the macOS keychain.

The ssh-agent remembers your key between Terminal sessions, and the keychain stores it across reboots:

eval "$(ssh-agent -s)"
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

To make this automatic on every login, create or edit ~/.ssh/config and add:

Host *
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519

You can open it with nano ~/.ssh/config, paste the block, then press Ctrl+O, Enter, Ctrl+X.

Step 4: Copy the public key to your clipboard.

pbcopy < ~/.ssh/id_ed25519.pub

There is no visible feedback — the key is silently on your clipboard. Jump to Step 5 (both platforms): add the key to GitHub below.

Windows: full SSH setup

Windows 10 (since 2018) and Windows 11 include OpenSSH by default. You can use Windows PowerShell (Start → type "PowerShell" → Enter) or Git Bash (installed with Git for Windows).

Step 1: Check whether you already have a key.

In PowerShell:

Get-ChildItem $HOME\.ssh

In Git Bash:

ls -al ~/.ssh

If you see id_ed25519.pub, you already have one — skip to Step 4. Otherwise continue.

Step 2: Generate a new key.

This command works the same in PowerShell and Git Bash:

ssh-keygen -t ed25519 -C "your-email@example.com"

Replace the email with the one on your GitHub account. Press Enter three times to accept the defaults. You should see "Your identification has been saved..."

Step 3: Start the SSH agent service and add your key.

Run this once to enable the agent to start automatically with Windows. Open PowerShell as administrator (right-click PowerShell → Run as administrator):

Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent

Then in any PowerShell window (no admin needed) add your key to the agent:

ssh-add $HOME\.ssh\id_ed25519

If you prefer Git Bash, the equivalent is:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Step 4: Copy the public key to your clipboard.

In PowerShell:

Get-Content $HOME\.ssh\id_ed25519.pub | Set-Clipboard

In Git Bash:

cat ~/.ssh/id_ed25519.pub | clip

There is no visible feedback — the key is on your clipboard.

Step 5 (both platforms): add the key to GitHub

1. Open GitHub in a browser → click your avatar (top right) → Settings.
2. In the left sidebar, click SSH and GPG keys.
3. Click New SSH key.
4. Title: something memorable, such as MacBook Air 2026 or Work PC.
5. Key type: leave as "Authentication Key".
6. Key: paste from your clipboard (Cmd+V on Mac, Ctrl+V on Windows).
7. Click Add SSH key.

GitHub may ask you to re-enter your password for confirmation.

Step 6 (both platforms): test the connection

In Terminal (Mac) or PowerShell / Git Bash (Windows):

ssh -T git@github.com

The first time it asks "Are you sure you want to continue connecting?" — type yes and press Enter. You should see:

Hi your-username! You've successfully authenticated, but GitHub does not provide shell access.

That message means it worked. The "no shell access" line is normal — GitHub never lets you log in interactively; the connection is only for git traffic.

If you see Permission denied (publickey) instead, the key is not being picked up. Run ssh-add -l to see which keys the agent currently has loaded. If the list is empty, repeat Step 3 for your platform.

Step 7: switch an existing repo from HTTPS to SSH

If you originally cloned with the HTTPS URL, swap it for the SSH one without re-cloning. On the GitHub repo page, click Code → SSH and copy the URL (it looks like git@github.com:your-username/your-repo.git). Then in your project folder:

git remote -v
git remote set-url origin git@github.com:your-username/your-repo.git
git remote -v

The first and third commands show you the current URL — a handy before-and-after check. From now on, git push and git pull will not ask for credentials.

For a fresh clone, use the SSH URL from the start:

git clone git@github.com:your-username/your-repo.git

Warning: Never share, email, or upload the private key file (id_ed25519, no extension). Only the .pub file goes to GitHub. If the private key ever leaks, delete the matching public key from GitHub's SSH and GPG keys page and generate a new pair.

Tip: Each computer should have its own SSH key. Do not copy ~/.ssh/id_ed25519 between machines — generate a new one on the second computer and add it to GitHub with a different title.

Sync troubleshooting

The errors people hit most often, what they mean, and how to fix them safely.

fatal: not a git repository (or any of the parent directories): .git

What it means: you ran a git command in a folder that is not a Git project.

Why it happens: you opened a Terminal in the wrong folder, or you have not cloned the project yet.

Fix: cd into the project folder (the one that contains your code), then try again. If you have never cloned the project on this computer, run git clone <repo-url> first.

---

Your branch is behind 'origin/main' by N commits, and can be fast-forwarded.

What it means: GitHub has commits that you do not.

Why it happens: someone pushed (or you pushed from another computer) since you last pulled.

Fix:

git pull

That brings you up to date.

---

! [rejected] main -> main (fetch first) — "Updates were rejected"

What it means: you tried to push but GitHub has commits that your laptop does not.

Why it happens: you forgot to pull before you pushed.

Fix:

git pull
git push

If git pull reports a conflict, see the Sync conflicts explained simply section above.

---

error: Your local changes to the following files would be overwritten by merge. Please commit your changes or stash them before you merge.

What it means: you have unsaved local edits that git pull would overwrite.

Why it happens: you started editing without committing, then tried to pull.

Fix: commit your work first, then pull.

git add .
git commit -m "Work in progress"
git pull

---

fatal: remote origin already exists.

What it means: you tried to add a GitHub remote, but one is already configured.

Why it happens: the project was already cloned or already had a remote set up.

Fix: in most cases, you did not need to add a remote at all — try git push and git pull directly. If you need to change the URL, use:

git remote set-url origin <new-repo-url>

---

Authentication issues when pushing (Authentication failed, Support for password authentication was removed)

What it means: GitHub does not accept your password the way it used to.

Why it happens: GitHub stopped accepting account passwords over HTTPS in 2021. You need a Personal Access Token (PAT) or SSH key.

Fix (simplest): install GitHub CLI (https://cli.github.com) and run gh auth login. It walks you through the login and sets up the right credentials. After that, git push and git pull just work.

---

GitHub Pages not updating after git push

What it means: you pushed, but the live site still shows the old version.

Why it happens: GitHub Pages takes one to ten minutes to rebuild. Sometimes the browser cache shows the old version even after the rebuild.

Fix:

1. Wait a couple of minutes.
2. Open the repository on GitHub, click Actions, and check the latest "pages build and deployment" run. A red cross means the build failed — click in for the error.
3. Hard-refresh the browser: Cmd+Shift+R on macOS, Ctrl+Shift+R on Windows.

If the Actions tab shows a green tick but the page still looks old after ten minutes, you are almost certainly looking at a cached version. Try a private browsing window.

Publishing a static site for free with GitHub Pages

For any static site — a CV, a portfolio, a landing page, a small documentation site — GitHub will host it for you, on HTTPS, at a real URL, for nothing. Every push to your main branch redeploys the site automatically. This is the simplest production hosting in the world.

The two worked examples that follow both publish to GitHub Pages, so this section is the canonical reference they point back to.

What you need

• A GitHub account.
• A repository containing your static site files (HTML, CSS, JS, images). No build step is required — what is in the repo is what gets served.
• An index.html at the root of the repo (or inside a /docs folder; see the alternatives at the bottom).
• SSH set up so pushes work without a password (Section 44).

Step 1: create the repository on GitHub

1. Open https://github.com/new.
2. Repository name: anything URL-safe. The site URL will be https://your-username.github.io/repo-name/. A common pattern is to name it after the project: cv-website, portfolio, notes.
3. Public or Private: choose Public for the free GitHub Pages tier. (Pages does support private repos on paid plans, but Public is the no-friction choice.)
4. Leave "Initialize this repository" unticked — Claude or you will push the first commit from your laptop.
5. Click Create repository.
6. Copy the SSH URL from the green Code button — it looks like git@github.com:your-username/repo-name.git.

Step 2: push your site to that repository

Inside your project folder on your laptop:

git init
git add .
git commit -m "Initial site"
git branch -M main
git remote add origin git@github.com:your-username/repo-name.git
git push -u origin main

Refresh the GitHub repo page; your files should be visible.

Step 3: turn on GitHub Pages

1. On the GitHub repo page, click Settings (top right of the repo nav, not your account settings).
2. In the left sidebar, click Pages (under "Code and automation").
3. Under Build and deployment:
   • Source: choose Deploy from a branch.
   • Branch: choose main and the folder / (root).
4. Click Save.

GitHub now starts building the site. The first build takes 1–3 minutes. While you wait, head over to the Actions tab — you will see a workflow called "pages build and deployment" running.

Step 4: visit your site

When the workflow finishes (green tick), return to Settings → Pages. At the top you will see:

Your site is live at https://your-username.github.io/repo-name/

Open the URL in a new tab. The site is live, on HTTPS, on a real domain, for free.

Step 5: redeploy by pushing

Every push to main triggers a fresh build. The cycle becomes:

# edit files locally
git add .
git commit -m "Update hero copy"
git push

Wait 1–2 minutes, hard-refresh the public URL, and the change is live.

Optional: use a custom domain

If you own a domain like your-name.com, you can point it at the GitHub Pages site:

1. In the repo: Settings → Pages → Custom domain → type your-name.com → Save. GitHub writes a CNAME file to your repo automatically.
2. At your domain registrar, create either:
   • An ALIAS / ANAME record on the apex pointing to your-username.github.io, or
   • Four A records on the apex pointing to GitHub's IPs: 185.199.108.153, 185.199.109.153, 185.199.110.153, 185.199.111.153.
3. Back on the Pages settings page, tick Enforce HTTPS once the certificate is issued (15–60 minutes after DNS propagates).

Common GitHub Pages snags

• 404 on the root URL. There is no index.html at the location GitHub is serving. Make sure index.html is at the repo root, not nested inside a dist/ or build/ folder. If your tool emits a build folder, either commit the contents of that folder to the root, or use the /docs source option in Step 3 and put your built files in /docs.
• Page loads but CSS is missing. Your stylesheet uses an absolute path like /styles.css, but GitHub serves your site under /repo-name/. Use relative paths in your HTML (styles.css or ./styles.css), or change the Pages source to a user/organization site (see below).
• Old content keeps appearing. Two layers of cache: GitHub's CDN (clears in 1–2 minutes after a successful build) and your browser. Hard-refresh with Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows), or open a private window.
• "User site" vs "project site". If you name your repo exactly your-username.github.io, it becomes your user site at https://your-username.github.io/ (no /repo-name/ suffix). Everything else is a project site.

Tip: GitHub Pages is fine for sites that are static at serve time — pre-rendered HTML, CSS, JS. If you need a database, server-rendered pages, or a form that emails you on submit, you have outgrown Pages; revisit Section 29 for the right hosting tier.

Worked example: push your CV site to GitHub Pages

You built the CV site locally in Section 34. It is sitting in ~/Downloads/cvwebsite/. This section takes that exact folder online — every file you have, served from a free public URL — using the workflow from the rest of this part.

Picking up from Section 34? If you skipped ahead, go back and run through Section 34 first. The remainder of this section assumes ~/Downloads/cvwebsite/ exists, with an index.html and your cv.pdf/cv.docx inside.

Step 1: create an empty GitHub repository

1. Open https://github.com/new in a browser.
2. Repository name: cv-website (anything URL-safe works; this name becomes part of the live URL).
3. Public, so GitHub Pages serves it for free.
4. Leave "Initialize this repository" unticked — your local folder already has all the files.
5. Click Create repository.
6. Copy the SSH URL from the green Code button — it looks like git@github.com:your-username/cv-website.git.

Step 2: turn the folder into a Git repo and push it

In Terminal (Mac) or PowerShell (Windows):

cd ~/Downloads/cvwebsite
git init
git add .
git status
git commit -m "Initial CV website"
git branch -M main
git remote add origin git@github.com:your-username/cv-website.git
git push -u origin main

What each new line does:

• git init — turns the folder into a Git project.
• git add . — stages every file in the folder for the first snapshot.
• git status — sanity check. If you see anything you did not mean to commit (a private note, a half-edited draft), remove it before the commit step.
• git commit -m "…" — saves the first snapshot to your local history.
• git branch -M main — renames the default branch to main (GitHub's convention; some local installs still default to master).
• git remote add origin … — points the local repo at the GitHub one you created in Step 1. Use the SSH URL — Section 44 set up SSH so this works without a password.
• git push -u origin main — pushes the first commit. The -u flag tells Git "remember this remote branch as the default for future pushes."

Refresh the GitHub repo page in your browser. Your files should be visible there.

Step 3: turn on GitHub Pages

Follow the steps from Section 46:

1. On the GitHub repo page → Settings → Pages.
2. Source: Deploy from a branch → Branch: main / Folder: / (root) → Save.
3. Wait 1–3 minutes for the first build. The Actions tab shows the build progress.
4. Refresh Settings → Pages. At the top: "Your site is live at https://your-username.github.io/cv-website/."

Open the URL. Your CV is now on the public internet.

Step 4: the day-after-tomorrow workflow

When you want to change something — fix a typo, add a job, swap the photo — use the safe habit from Section 39, with a branch as Section 40 recommends:

cd ~/Downloads/cvwebsite
git switch main
git pull
git switch -c update-2026-role
# Edit files yourself, or ask Claude:
#   "Change the role in the hero to 'Senior Data Engineer' and add a 2026 entry to Experience."
git status
git add .
git commit -m "Update hero role and add 2026 experience"
git push -u origin update-2026-role

On GitHub, open the Compare & pull request banner, write a short description, click Create pull request, then Squash and merge. GitHub Pages rebuilds within a couple of minutes. Pull the merged change back to your laptop:

git switch main
git pull
git branch -d update-2026-role

You now have the full engineering loop: branch, change, push, PR, merge, redeploy. Use it for every edit, however small.

Tip: This small project is the perfect ground to practise every habit in this part. Make a one-character change on GitHub directly (edit index.html in the browser, commit), then on your laptop run git pull and watch the change appear. Then make a conflicting edit on both sides at once and resolve the conflict (Section 43). You will internalise the workflow much faster than by reading about it.

Worked example: build a personal portfolio and publish it on GitHub Pages

A portfolio site is the bigger sibling of the CV from the previous section. Where a CV is a single page summarising who you are, a portfolio is a small website built around the projects you have shipped — with a hero, a photo, an about section, a projects grid, and a contact block. Recruiters and clients look at portfolios before they look at CVs. Building one in an evening is one of the highest-leverage things you can do as an engineer.

We will reuse everything you have learned so far: Claude Code drafts the site, you commit it to a fresh GitHub repo, GitHub Pages serves it on a free public URL. The whole thing should take 30–60 minutes including content.

Before you start

Put four things in ~/Documents/portfolio-content/ on your laptop:

• A square headshot photo named me.jpg (or .png). Roughly 800×800 px works well. If you do not have one, take a clear well-lit photo against a plain wall on your phone and crop it to a square.
• A short bio in bio.md: one paragraph about who you are and what you do. Plain English, 2–4 sentences.
• A list of projects in projects.md. For each project: a name, a one-line description, two or three tech tags (e.g. React, Tailwind, Supabase), and a link (live demo URL, repo URL, or both). Three to six projects is ideal.
• A list of skills in skills.md: grouped if you can (Languages / Frameworks / Tools / Other). Comma-separated is fine.

Then create an empty repository on GitHub called portfolio (Public, no readme, no licence). Copy the SSH URL — git@github.com:your-username/portfolio.git.

The Claude prompt

Open Claude Code in your home folder:

cd ~
claude

Paste the whole block below, replace the LinkedIn URL with your real handle (or leave the placeholder for Claude to fill in later), then press Enter:

Read the files in ~/Documents/portfolio-content/: me.jpg (or me.png), bio.md, projects.md, and skills.md. Use that content to build a personal portfolio website following these rules.

1. Location. Create a new folder at ~/Documents/portfolio/ and put every file inside it. Copy me.jpg/me.png into the folder as me.jpg so it can be referenced by relative path.

2. Stack. Plain index.html, Tailwind CSS via the official CDN (https://cdn.tailwindcss.com), and a small amount of vanilla JavaScript in script.js. No build step, no framework, no Node packages. Opening index.html in a browser must just work.

3. Sections, in order:
a. Hero — my circular headshot photo (around 160 px on mobile, 220 px on desktop), my name as the largest heading, a one-line tagline taken from bio.md, and two CTA buttons: "View projects" (smooth-scrolls to the projects section) and "Get in touch" (smooth-scrolls to contact).
b. About — the full paragraph from bio.md, presented as a single readable column of text (max-width around 65 ch).
c. Projects — a responsive grid (1 column on mobile, 2 on tablet, 3 on desktop) of cards. Each card shows the project name as a heading, the one-line description, the tech-tag pills, and a "Visit →" or "View code →" link. Hover state: gentle lift and shadow.
d. Skills — grouped tag clusters under sub-headings.
e. Contact — a short paragraph, an email link with mailto:, a LinkedIn link (https://www.linkedin.com/in/your-handle — leave this placeholder if you cannot find a real one in my content), and a GitHub link (https://github.com/your-username — same placeholder rule).

4. Mobile-first and fully responsive. Design for 320 px first, then scale up. Test the layout at 320, 768, and 1280 px in dev tools.

5. Navigation. On screens below 768 px, use a fixed bottom navigation bar (about 64 px tall, four items: About, Projects, Skills, Contact — icon plus label, large tap targets at least 48×48 px, fixed to the bottom of the viewport with iOS safe-area inset respected). On screens 768 px and above, hide the bottom bar and show a sticky top navigation header instead. Both navs smooth-scroll between sections.

6. User-centred design. Strong visual hierarchy, generous whitespace, one primary CTA per viewport, WCAG AA colour contrast, body text 16 px or larger, visible focus states on keyboard navigation, prefers-reduced-motion respected, alt text on every image, and the photo wrapped in an accessible figure.

7. Polish. A subtle dark/light look using one accent colour, a clean modern font pair from Google Fonts (display sans for headings, neutral sans for body), and a small "back to top" button that appears after the user scrolls past the hero.

Before you write any code, do three things and wait for my answer: (a) Tell me the bio paragraph, the project list, and the skills you extracted from the files. (b) Propose the visual style in one short paragraph: colour palette (3–4 hex codes), font pair, and a one-line "feel" description. (c) List the files you intend to create.

When I say "go ahead," create the folder, write the files, and finish by showing me the file tree and the command to open the site (I am on macOS).

Review, approve, open

Claude replies with the three preview items. Read each carefully:

• If a project description is wrong or out of date, paste the correction in plain English.
• If the proposed colour feels wrong for you, say so: "Use a deep navy as the accent, not green."
• If the file list misses something you want, add it: "Also include a print.css so I can print the page to PDF cleanly."

Only when you are happy do you say "go ahead." Claude writes the files. Open it locally:

open ~/Documents/portfolio/index.html

(start index.html on Windows.) Resize the browser narrower than 768 px and the bottom nav should appear; wider, and the top header takes over. Tap the headshot — it should not navigate anywhere (your face is not a button). Tap "View projects" — the page should smooth-scroll to the projects grid.

Push to GitHub and turn on Pages

Same workflow as the CV example. Inside the project folder:

cd ~/Documents/portfolio
git init
git add .
git commit -m "Initial portfolio site"
git branch -M main
git remote add origin git@github.com:your-username/portfolio.git
git push -u origin main

Then follow Section 46 to turn on GitHub Pages for the new repo (Settings → Pages → Source: Deploy from a branch → Branch: main / / (root) → Save). In 1–3 minutes your portfolio is live at https://your-username.github.io/portfolio/.

Iterating after launch

Adding a new project is now a five-command habit:

cd ~/Documents/portfolio
git pull
# Tell Claude: "Add a new project card to the projects grid: 'Sales Forecaster',
#   a 2026 Python+Streamlit tool that predicts monthly revenue.
#   Tech tags: Python, Streamlit, Pandas. Link to https://github.com/me/forecaster."
git add .
git commit -m "Add Sales Forecaster project card"
git push

GitHub Pages rebuilds in a minute or two and the new card is live. Over time the site grows with your career — every shipped project becomes another tile on the grid.

Tip: A photo on a personal site dramatically increases the time visitors spend on the page and the chance they remember you. Use a recent photo, well-lit, neutral background, looking at the camera. Re-take it every couple of years — the version of you from 2021 is not selling 2026-you anywhere near as well.

Tip: When you point recruiters or clients at the site, send them the GitHub Pages URL (https://your-username.github.io/portfolio/), not the repo URL. The repo is for engineers; the rendered site is for everyone else.

---

← Part 8 of 9: After Launch and Working Well with Claude Code · All parts