The Git and GitHub Picture Book
firstHEAD mainfeature/login GitHub · originthe shared copy push
PLATE 0 — History is a chain of snapshots. Branches are just labels on it.
A picture book for grown-ups · with commands

Git and GitHub, Finally Making Sense

Nine spreads. Each has a picture, the idea, and the exact commands, from your first commit to pull requests and fixing mistakes.

Say it like a pro

"Small commits on a branch, a pull request for review, rebase or merge into main, and I can always get back to a known-good state."

Git is the tool on your computer. GitHub is a website that hosts Git repositories and adds collaboration. Use the tabs or ← → keys.

Workingfiles you edit Stagingnext commit Local repo.git history RemoteGitHub addcommitpush pull = fetch + merge · checkout/restore A commit is a snapshot, not a diff each has an ID (hash), author, message, and a parent a branch is a movable label · HEAD is "where you are now"
PLATE 1 — Edit, stage what you want, commit it, then share it.
Chapter 1 · The mental model

Four places your changes live

The staging area lets you build a commit deliberately: choose which changes go together, even from the same file.

First-time setup, then a repo
$ git config --global user.name  "Your Name"
$ git config --global user.email "you@example.com"
$ git config --global init.defaultBranch main
$ git init                    # start tracking this folder
$ git status                  # what's changed? (use it constantly)
$ git add index.html          # stage one file (git add -p: by chunk)
$ git commit -m "Add homepage"
$ git log --oneline --graph --all
.gitignore
files git should skip: node_modules/, .env, build output
good message
imperative and specific: "Fix login redirect loop"
Say it like a pro

"One logical change per commit, with a message that explains why."

status edit diff add commit push repeat When unsure, run:git status · git diff · git log --oneline -5
PLATE 2 — Most days are just this loop.
Chapter 2 · Daily commands

Look before you leap

$ git status -s                 # short status
$ git diff                      # unstaged changes
$ git diff --staged             # what the next commit will contain
$ git add -p                    # review each chunk, stage or skip
$ git commit -m "Validate email on signup"
$ git commit --amend            # fix the last commit (unpushed only)
$ git log --oneline -10
$ git show a1b2c3d             # one commit in detail
$ git blame app.js             # who changed each line, and when
$ git rm old.txt ; git mv a.js b.js
HEAD~1
the commit before the current one
hash
the first 7 characters are enough: a1b2c3d
Say it like a pro

"I always read git diff --staged before I commit."

merge merge commit rebase your commits, replayed on top merge keeps the true history · rebase makes it a straight line never rebase commits other people already pulled
PLATE 3 — Two ways to bring a branch's work back together.
Chapter 3 · Branches & merging

Work in parallel without stepping on each other

A branch is cheap: just a pointer. Make one for every feature or fix, and keep main always working.

$ git branch                      # list (git branch -a for remotes too)
$ git switch -c feature/login      # create and move to it
$ git switch main
$ git merge feature/login         # bring it into main
$ git branch -d feature/login      # delete after merging
$ git switch feature/login ; git rebase main   # replay onto latest main

Resolving a conflict

Two branches edited the same lines. Git marks the file; you choose the final text.

<<<<<<< HEAD
const limit = 10;
=======
const limit = 25;
>>>>>>> feature/login
# edit the file, delete the markers, keep the right code, then:
$ git add file.js ; git merge --continue   # or: git rebase --continue
$ git merge --abort                         # bail out safely
Say it like a pro

"Short-lived branches, rebase onto main before the PR, and resolve conflicts in the editor, then re-run the tests."

You GitHuborigin/main Teammate push pull origin is just a nickname for the URL fetch = download, don't change my files pull = fetch + merge into my branch push rejected? someone pushed first: pull, then push
PLATE 4 — The remote is a meeting point. Everyone syncs through it.
Chapter 4 · Remotes & GitHub

Put your work somewhere shared

Connect a local repo to GitHub
# 1. create an empty repo on github.com (or: gh repo create)
$ git remote add origin https://github.com/you/project.git
$ git branch -M main
$ git push -u origin main        # -u remembers the upstream
$ git remote -v
Get someone else's repo, and stay in sync
$ git clone https://github.com/org/project.git
$ git fetch ; git pull --rebase
$ git push

Logging in

GitHub no longer accepts account passwords for git. Use HTTPS with the GitHub CLI or a credential manager, or SSH keys.

$ gh auth login
# or SSH:
$ ssh-keygen -t ed25519 -C "you@example.com"
$ cat ~/.ssh/id_ed25519.pub         # paste into GitHub → Settings → SSH keys
$ ssh -T git@github.com
Say it like a pro

"Pull with rebase before pushing, and never commit secrets or tokens."

1 push 2 open PR 3 checks 4 review changes requested → push more commits to the same branch 5 update 6 approve + merge A good PR is small and explained title says what · description says why · link the issue "Closes #42" auto-closes the issue when merged under ~400 changed lines gets reviewed properly
PLATE 5 — A pull request is a conversation about a change before it lands.
Chapter 5 · Pull requests

Propose, review, merge

$ git switch -c fix/cart-total
$ git commit -am "Fix rounding in cart total"
$ git push -u origin fix/cart-total
$ gh pr create --fill --body "Closes #42"
$ gh pr status ; gh pr checks
$ gh pr checkout 57          # try someone's PR locally
$ gh pr merge --squash --delete-branch
Merge buttonResult
Merge commitkeeps every commit plus a merge commit
Squash and mergeone tidy commit on main (popular)
Rebase and mergestraight line, commits replayed
fork
your own copy of someone else's repo, for contributing to projects you can't push to
draft PR
"work in progress, not ready for review"
Say it like a pro

"Small PR, clear description, green checks, and one approval before I squash-merge."

I made a mistake… not stagedrestore stagedrestore --staged committedamend / reset pushedrevert The safety net: reflog git remembers where HEAD has been for ~90 days "lost" commits after a bad reset are almost always recoverable pushed to shared history? add a new commit that undoes it (revert) instead of rewriting what others already pulled
PLATE 6 — Pick the undo by asking: how far did the mistake travel?
Chapter 6 · Undoing things

Almost nothing in git is truly lost

$ git restore file.js                 # discard unstaged edits (permanent!)
$ git restore --staged file.js        # unstage, keep the edits
$ git commit --amend -m "Better msg"  # fix last commit, unpushed only
$ git reset --soft HEAD~1            # undo commit, keep changes staged
$ git reset --hard HEAD~1            # undo commit AND delete the changes
$ git revert a1b2c3d               # new commit that reverses it (safe)
$ git stash ; git stash pop         # shelve work, bring it back
$ git reflog                        # find a "lost" commit
$ git switch -c rescue a1b2c3d      # give it a branch again
--hard
the dangerous one. It throws away uncommitted work.
force push
rewrites the remote; use --force-with-lease, and never on shared branches
leaked secret
revoke and rotate it first. Deleting the commit doesn't un-leak it.
Say it like a pro

"On shared branches I revert. I only rewrite history on my own unpushed work."

Trunk-based (most teams) short branches, merge daily, deploy from main Release branches (versioned software) main = released develop release/2.1 → tag v2.1.0 more ceremony; fits slow, supported releases
PLATE 7 — Pick the lightest workflow that fits how you ship.
Chapter 7 · Team workflows

Agree on a few rules, then keep them

  1. main is always deployable. Protect it: require PRs, reviews and passing checks.
  2. Branch names say what and why: feature/…, fix/…, chore/….
  3. Commit messages follow a convention, like feat: add search or fix: handle empty cart.
  4. Tag releases so you can find or roll back to them.
$ git tag -a v1.2.0 -m "Release 1.2.0"
$ git push origin v1.2.0
$ git log v1.1.0..v1.2.0 --oneline     # what shipped
$ git cherry-pick a1b2c3d            # copy one commit onto this branch
$ git bisect start ; git bisect bad ; git bisect good v1.1.0   # find the commit that broke it
semver
MAJOR.MINOR.PATCH: breaking · feature · fix
CODEOWNERS
auto-requests review from the right people
Say it like a pro

"Protected main, conventional commits, tagged releases, and bisect when something regresses."

Repositorycode + history Issues Actions Pages Security Releases Projects
PLATE 8 — GitHub wraps your repo with planning, automation, and safety tools.
Chapter 8 · GitHub's extras

More than a place to store code

Issues
bugs and tasks; label, assign, link to PRs
Projects
kanban boards over issues and PRs
Actions
automation that runs on push or PR: tests, builds, deploys
Pages
free static site hosting from a repo
Releases
tagged versions with notes and downloads
Dependabot
opens PRs to update vulnerable dependencies
Secret scanning
warns when a token is committed
.github/workflows/ci.yml
name: ci
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test
$ gh issue create --title "Search is slow" --label bug
$ gh issue list ; gh run list ; gh release create v1.2.0 --generate-notes
$ gh repo view --web
Say it like a pro

"Every change links to an issue, CI must pass, and Dependabot keeps the dependencies fresh."

rejected: non-fast-forwardremote has commits you don't → git pull --rebase CONFLICT (content)edit markers → git add → --continue detached HEADnot on a branch → git switch -c my-work Permission denied (publickey)SSH key missing → add key to GitHub, ssh -T git@github.com file too large / secret committedrotate the secret · git filter-repo · use .gitignore / LFS
PLATE 9 — Read the error. Git usually tells you the fix.
Chapter 9 · The fix-it guide

When git yells at you

# "I committed to main by mistake"
$ git branch fix/oops ; git reset --hard origin/main ; git switch fix/oops

# "I need to undo a bad merge that's not pushed"
$ git reset --hard ORIG_HEAD

# "I want to see what's different from main"
$ git diff main...HEAD ; git log main..HEAD --oneline

# "Stop tracking a file but keep it on disk"
$ git rm --cached .env ; echo ".env" >> .gitignore

# "Clean untracked files" (preview first!)
$ git clean -nd ; git clean -fd
  1. Stop and run git status. Don't guess.
  2. Read the error; it often names the command.
  3. Branch before doing anything risky: git branch backup is free insurance.
  4. Reflog if you think you lost work.
Say it like a pro

"I made a backup branch, then reset. If it goes wrong, the reflog has my old HEAD."