Version control

Git: a save button you can rewind, branch, and share.

Git records snapshots of your project over time. That means you can go back to any earlier version, try risky things without fear, and work alongside other people on the same code. It's the safety net under everything else.

#The mental model

You've already been on the receiving end of Git. Groundwork itself lives in a Git repository on GitHub, and this page is a file inside it. When this page gets improved, Jason, who created and maintains Groundwork (in Git terms, its maintainer), edits the file, stages it (picks it for the next snapshot), commits it (saves the snapshot, with a note saying why), and pushes it to GitHub. The next time your machine updates Groundwork, it pulls: the new snapshot comes down, and the page you're reading quietly gets better. Every project you'll ever touch moves the same way; only the names change.

That's the whole model: four places. Three live on any machine doing the writing: the working files being edited, the staging area where the next snapshot is assembled, and the history of saved snapshots. The fourth, GitHub, is the shared copy every machine pushes to and pulls from. Every command on this page just moves change between these four places, and when it's your project, you're the one on the laptop at the top of the diagram.

#The daily loop

Ninety percent of Git is five commands. Check what changed, stage it, commit it with a message, and sync with GitHub.

$ git status              # what changed?
$ git add .               # stage everything
$ git commit -m "message" # save a snapshot
$ git push                # send it to GitHub
$ git pull                # get others' changes

Write commit messages that say what changed and why, not "stuff" or "fix". Future-you reads them constantly.

#Branches — the superpower

A branch is a parallel line of work. You split off from main, build something without touching the working version, and merge it back when it's ready. This is how you try ideas — and how teams avoid stepping on each other.

$ git switch -c new-feature  # create and move onto a branch
$ git switch main            # hop back to main
$ git merge new-feature      # fold the branch into main

#GitHub and the gh command

GitHub is where repositories live online. The gh command talks to it from the terminal — sign in once, then clone repos and open pull requests without leaving the shell.

$ gh auth login --git-protocol https  # one-time sign-in
$ gh auth status                     # see the active account
$ gh repo clone owner/name   # download a repo
$ gh pr create               # propose your branch for merge

A pull request is how you propose a branch be merged — others review it, discuss, and approve. It's the heart of working together on GitHub.

#When something goes wrong

Committed work is very hard to truly lose — Git keeps almost everything. Most "mistakes" have a calm fix:

#lazygit: a picture of Git, not a replacement for it

Now that the commands are in your hands, meet lazygit: a keyboard-driven view of the same repository, where every keystroke maps to a command you already know. Its value is that you can see the model this page taught: files moving from unstaged to staged to committed, branches as a live graph, and every line an agent touched, reviewable one hunk at a time. Learn the commands first (they're the shared language between you, the docs, and your agents); use lazygit to watch what they do and to move faster at things that are genuinely visual, like staging individual lines or reading history. It's the same app however you open it:

Finding your way around

The left side holds five panels; the right shows the details of whatever you've selected.

The everyday actions

#What's already configured

Your Git arrives pre-tuned, so the sensible behavior is just the default. You never set this up — but it's worth knowing what's on, because it quietly removes a lot of papercuts.

Readable diffs — delta

Plain git diff is a wall of red and green. delta reformats every diff Git shows — syntax highlighting, line numbers, and word-level highlighting of exactly what changed on a line. It's wired in as Git's pager, so git diff, git show, and git log -p all use it automatically.

Fetch vs pull, and what "prune" really removes

Two commands bring things from GitHub to you, and they are politely different. git fetch downloads what's new and updates your local bookmarks of the remote (the origin/* names you see in branch lists) while touching nothing of yours: it is purely "go look". git pull is fetch plus "and fold it into the branch I'm on". Prune is bookkeeping on those bookmarks: after a branch is deleted on GitHub (normally because its pull request merged), your local origin/that-branch bookmark points at something that no longer exists. Pruning removes the stale bookmark, and only the bookmark: never your local branches, never your edits, never a commit. Despite the alarming name, it cannot delete work.

$ git fetch           # download news; change nothing of yours
$ git pull            # fetch + bring it into your current branch
$ git fetch --prune   # also drop origin/* bookmarks for deleted branches
$ git branches        # local branches with state (see the next section)

Seeing your branches clearly

Plain git branch -a does mark the current branch with * (and branches checked out in other worktrees with +), but its default view doesn't combine recency, tracking health, merge evidence, unique work, worktree use, and pull-request state. When you're directing agents that spin up a branch per task, that flat list fills with noise fast. Groundwork adds three read-only aliases that answer the real questions. They never change anything — they only look.

$ git fetch --prune   # refresh remote-tracking refs; drop upstreams gone from the remote
$ git branches        # the full picture, newest first
$ git gone            # just the safe-to-review candidates

If git gone lists names, their configured upstream tracking refs are absent from your local remote-tracking refs after the latest fetch/prune — which does not by itself prove the work merged. Look at each with git branches before removing anything, or open the repo in lazygit (lg) to see them visually.

The sensible defaults

A handful of config choices that make day-to-day Git smoother and the history cleaner:

Signed commits

If you set a signing key during setup, every commit is signed automatically — a cryptographic stamp that it really came from you, shown as a "Verified" badge on GitHub. This uses your SSH key from the password manager (1Password or Bitwarden), so there's no separate key to manage and nothing private ever touches disk.

Pulling without prompts — the gh credential helper

GitHub stopped accepting passwords years ago, so Git authenticates through gh for HTTPS remotes. The setup bakes gh in as Git's credential helper (in the managed git config, so it survives every chezmoi apply) for your own GitHub repos after you run gh auth login --git-protocol https. SSH remotes are still fine when your ~/.ssh/config clearly maps the right key to the right GitHub account.

#Going deeper: a ladder, not a pile

Pick your entry point by where you are, not by what looks most authoritative. The classic mistake is starting with Pro Git (the "Git bible"): it is the definitive reference and a rough first week, because it covers internals, hooks, and server setup alongside the basics. This ladder runs from first hour to deep mechanics. Step on at your level, step off when you have what you need, and come back a rung higher later.

First week: the on-ramp (hands-on, about an hour each)

1. GitHub Skills: Introduction to GitHub: branches, commits, pull requests, and merging in under an hour, inside a real repo, no prerequisites.
2. GitHub Skills: Introduction to Git: the Git side proper, on the command line and VS Code, still hands-on.
3. freeCodeCamp's Git & GitHub crash course: one free video covering the real daily workflow: staging, commits, branches, merge conflicts, push/pull, stash, revert, rebase, and pull requests.
4. Learn Git Branching (beginner levels): the visual sandbox. Type real commands, watch the graph move. This is where branching clicks.

Second stage: depth without the reference manual

• freeCodeCamp's beginner-friendly handbook: plain-English long form, from "what is Git" gradually into branching, merging, conflicts, and safely undoing mistakes.
• Git for Professionals (free video): crafting good commits, choosing a branching strategy, and merge versus rebase. Watch it once the commands feel comfortable, not on day one.
• Oh My Git!: an open-source game that shows Git's internals as you play.
• GitHub for Beginners: GitHub's own blog-plus-video series on its features, for when you want the official voice.

Reference: for looking things up, not reading through

• Atlassian Git tutorials: the practical team-workflow reference; clearer than Pro Git for day-to-day questions.
• Pro Git: the definitive, free, complete book. Superb once you have real mileage; internals, hooks, and refspecs live here.
• Oh Shit, Git!?!: copy-paste recipes for escaping common messes.
• Julia Evans' Git cheat sheet: a friendly one-page "how I actually use git."
• Official Git docs: the authoritative command reference.