Git: track your work

1 · The three areas essential

Everyone has a folder like this somewhere. report_final.py, report_final_v2.py, report_FINAL_actually.py, report_use_this_one.py. It's how you "keep versions" before you know Git — and it's a nightmare: you can't tell what changed between them, you can't collaborate without emailing zips, and the moment you delete the wrong one, that work is gone forever. Git exists to end that folder. It gives you an unlimited, labelled undo history for your whole project — and the very first thing to understand is where a change lives on its way into that history.

Here's the mental model that makes every other command in this lesson obvious. Think of Git like a photographer assembling a group photo. Your working directory is the room full of people milling about — that's your project folder, where you actually edit files. Before you take the shot, you call certain people onto the riser: that's staging, deciding exactly who's in this particular photo. Then you press the shutter — that's the commit, a permanent snapshot saved forever with a caption. The people not on the riser simply aren't in this photo; they're still in the room, ready for the next one.

The part beginners find surprising — and the reason the staging area earns its own box — is that middle step. Most tools save everything that changed, all at once. Git deliberately makes you choose what goes into each snapshot. That feels like extra work until the day you've fixed a bug and half-written a feature in the same file, and you want to commit only the bug fix cleanly. Staging is what lets each commit be one coherent, reviewable idea instead of a jumbled "misc changes" dump. The common mistake is treating git add as a meaningless ritual you type before every commit — staging blindly with git add . every time — and then wondering why your history is a mess of unrelated changes lumped together. Staging is a decision, not a formality.

A change lives in one of three places, and Git commands move it between them: edit → git add (stage) → git commit (save to history).

init.shgit init
git config user.name "You"; git config user.email "you@example.com"
echo "# Project" > README.md
git status                        # README.md is untracked
git add README.md                 # stage it
git commit -m "Add README"
git log --oneline

2 · The everyday loop & good messages essential

Setting up a repo is a one-time event; this loop is the rest of your career. The git init ceremony you just did happens once per project. What you'll actually do thousands of times — every real day of coding — is the tiny rhythm below: change something, stage it, snapshot it. If §1 was learning where the three rooms are, this is learning to walk between them without thinking, the way you stopped consciously spelling words once you could read.

The analogy that sticks: a commit is a save point in a video game. You don't save after every footstep — you save when you've reached somewhere you'd be annoyed to have to redo. A commit is the same instinct: make one small, complete unit of progress ("the login form validates now"), then snapshot it. Do that and your history becomes a series of safe places you can always jump back to. Skip it — code for three hours and commit once at the end — and you've thrown away the whole point, because you can only ever roll back to that one distant save point, not to "just before I broke the parser."

Which brings us to the half of this that people undervalue for years: the commit message. A message isn't paperwork for Git — it's a letter to a stranger, and that stranger is you, six months from now, staring at a line of code with no idea why it's there. The code already tells the reader what it does; the message is your one chance to record why you did it. The near-universal beginner mistake is writing messages that describe the mechanics you can already see — update file, changes, fix, or the infamous stuff — instead of the intent. Compare "fixed it" against "Fix off-by-one so the last page of results is no longer dropped": only one of those saves the next person (you) an hour of archaeology. Write messages in the imperative mood ("Add", "Fix", "Remove") as if completing the sentence "This commit will…", and you'll thank yourself every time you run git log or git blame.

loop.shecho "print('hi')" > app.py
git add app.py                    # or `git add -p` to stage hunks interactively
git commit -m "Add entrypoint"
git log --oneline --stat          # what changed in each commit

3 · Inspecting history intermediate

A bug appeared this week that definitely wasn't there last month. Nobody remembers touching that code. On a project without version control this is where you start guessing and re-reading everything. With Git, it's a five-minute investigation: the history knows exactly which commits changed those lines, who wrote them, when, and — if the messages were good — why. Learning to read that history is what turns Git from "a thing that saves my files" into a genuine debugging superpower.

Think of your commit history as a security-camera archive for your codebase. Every commit is timestamped footage of exactly what the project looked like at that moment, and the commands in this section are the different ways you review the tapes. git log is scrubbing through the timeline of events; git show is playing one clip in full; git diff is a split-screen comparing two moments side by side; and git blame is the frame-by-frame that tells you which recording last touched a specific spot. Crucially, every command here is read-only — like reviewing footage, you can't damage anything by looking, so you should reach for these constantly and without fear whenever you're confused.

The one distinction worth burning in before you start, because it's the source of endless confusion, is the difference between git diff and git diff --staged. Remember the three areas from §1: plain git diff compares your working directory against staging ("what have I changed but not yet added?"), while git diff --staged compares staging against the last commit ("what will actually go into my next snapshot?"). The classic mistake is running git diff, seeing nothing, and concluding you have no changes — when in fact you already staged them, so they've moved out of git diff's view and into git diff --staged's. The two diffs answer two different questions about two different gaps; knowing which is which is what lets you review a commit precisely before you make it.

inspect.shgit log --oneline --graph --all      # visual history
git show HEAD                         # the last commit's full diff
git diff                              # unstaged changes
git diff --staged                     # staged changes
git blame app.py                      # who last touched each line (and when/why)

4 · Undoing mistakes safely intermediate

The reason people are scared of Git is that they think they can break it. They've heard the horror stories — someone ran a command, lost a day's work, and swore off touching the terminal. So they cling to a safe subset of three commands and never experiment. That fear is almost entirely misplaced, and getting rid of it is the single biggest confidence upgrade in this whole chapter, because Git is built to make mistakes recoverable. Once you trust that, you stop tiptoeing and start using it properly.

Here's the reassuring truth: a commit, once made, is almost impossible to truly destroy. Even when you "delete" one with a reset, Git doesn't shred it — it just stops pointing at it, like a library book pulled from the catalogue but still sitting on the shelf. git reflog is the shelf: a private log of every position your HEAD has ever been at, so you can walk back to a "lost" commit and check it out again. The mistakes that are unrecoverable are the ones involving work you never committed — discarding un-staged edits with git restore, for instance, genuinely throws them away, because Git never had a snapshot to fall back to. The lesson that follows: commit early and often, and almost nothing can hurt you.

The table below is your recovery menu, and the mental model for reading it is to match the fix to which of the three areas the mistake is in — the same map from §1. Staged something by accident? git restore --staged pulls it back out of staging without touching your edit. Want to abandon changes in your working directory? git restore the file. Wrote a bad commit message? git commit --amend. Committed too early? git reset --soft HEAD~1 undoes the commit but keeps the work staged, as if you never pressed the shutter. The one genuine trap — and the reason this section says "safely" — is that these commands rewrite local history, which is fine until a commit has been pushed and pulled by teammates; rewriting shared history breaks their clones. The rule of thumb: reset and amend freely on commits that are still only yours, but undo a shared commit with git revert (which adds a new, inverse commit rather than erasing the old one). We'll return to that distinction in DF3.

5 · .gitignore — never commit junk or secrets advanced

There is a genre of news story that ruins careers: "developer accidentally commits AWS keys to public GitHub, wakes up to a $50,000 bill." It is astonishingly common, and it almost always happens the same way — someone runs git add ., sweeping every file in the folder into a commit without looking, and a .env file full of secrets rides along. Bots scan public repos for exactly this within minutes of a push. The humble .gitignore file is the guardrail that stops it, and this is the section where "commit everything" habits get corrected before they cost you.

A .gitignore is a plain text list of patterns for files Git should pretend don't exist — it never stages them, never nags you about them, never lets a careless git add . sweep them in. Think of it as the bouncer's "do not admit" list at the door of your repository. Two broad categories belong on that list. First, junk that's generated, not authored: virtual environments (.venv/), compiled caches (__pycache__/, *.pyc), build output (dist/, build/), and OS clutter (.DS_Store). These are big, machine-specific, and regenerated on demand — committing them just bloats history and creates pointless merge conflicts. Second, and far more important, secrets: API keys, passwords, tokens, anything in a .env file. Those must never enter history at all.

And that word — history — is the trap that makes this section "advanced" rather than trivial. Here is the mistake that catches even experienced developers: they assume that adding a secret to .gitignore after it's already been committed will hide it. It will not. .gitignore only prevents files from being tracked in the future; a file Git is already tracking keeps getting committed regardless. Worse, Git history is permanent and additive — deleting the secret in a later commit doesn't remove it, it's still sitting in the earlier snapshot for anyone who checks out that commit. So the discipline is: write your .gitignore before your first commit, so the secret never gets in. If one does slip through, the only correct response is to assume it's compromised, rotate the credential immediately (generate a new key, revoke the old one), and only then worry about scrubbing history. Ignoring is prevention, not a cure — as the danger note below hammers home.

.gitignore.venv/
__pycache__/
*.pyc
.env                 # secrets/API keys — NEVER commit
.DS_Store
dist/
build/
*.log

6 · Advanced — read Git from Python advanced

Somebody on your team is writing the release notes by hand, and it shows. Every release, they scroll back through the commits, try to remember what shipped, and paste a half-remembered summary into an email. It's tedious, it's error-prone, and it's completely unnecessary — because the information is already there, structured, in the commit history. This is the moment Git stops being something you type at and becomes something you program against: the same history you've been browsing by eye, a script can read and turn into changelogs, version bumps, dashboards, and repo analytics.

The key realization is that Git is, at heart, a database of your project's history — and like any database, you can query it from code instead of clicking through it. You don't need a special library to start; the plainest, most durable approach is to shell out: have your Python run the exact same git commands you'd type by hand and capture their text output, using the subprocess module you met in DF1. Think of it as your program picking up the same tools you use manually — it's just automation of the commands you already know. The trick that makes it clean is --pretty=format: (and its cousin --format=), which tells git log to print exactly the fields you want in a shape that's trivial to parse, rather than the human-friendly default.

Reading Git this way opens a door, but it comes with one habit worth forming early. The common mistake is parsing raw, unstructured commit messages and hoping they're consistent — they never are, because humans wrote them freehand ("fixed the thing", "WIP", "asdf"). The lab below sidesteps this by using conventional commits — messages with a machine-readable type: description shape (feat: login, fix: null check) — which is precisely why the parsing is a one-liner. That's the whole thesis of this chapter's back half: if you impose a small convention on how commits are written (§9 enforces it), you get automation like this and semantic versioning (§7) almost for free. One more practical note about the code: it builds a throwaway repo in a temp folder and commits into it, so the example runs anywhere with zero setup and can't touch your real work — a pattern worth stealing whenever you want to demo Git behaviour safely.

Release tooling and dashboards read Git programmatically. Shell out with subprocess (DF1) and parse. This builds a throwaway repo so it runs anywhere, error-free.

changelog.pyimport subprocess, tempfile
from pathlib import Path

repo = Path(tempfile.mkdtemp())
def git(*a): return subprocess.run(["git", *a], cwd=repo, capture_output=True, text=True).stdout.strip()
git("init", "-q"); git("config","user.email","a@b.c"); git("config","user.name","D")
for msg in ["feat: login", "fix: null check", "feat: logout", "chore: bump deps"]:
    (repo/"f.txt").write_text(msg); git("add","."); git("commit","-q","-m",msg)

log = git("log", "--pretty=format:%s").splitlines()
groups = {}
for line in log:
    kind = line.split(":")[0]
    groups.setdefault(kind, []).append(line.split(": ",1)[1])
for kind in ("feat", "fix", "chore"):
    if groups.get(kind):
        print(f"## {kind}"); [print(" -", x) for x in groups[kind]]

## feat
 - login
 - logout
## fix
 - null check
## chore
 - bump deps

7 · Professional — semantic versioning from commits professional

Ever updated a library from 3.2.1 to 3.2.2 without a second thought, but hesitated before jumping to 4.0.0? That instinct is semantic versioning working exactly as designed. Those three numbers aren't arbitrary — they're a promise the author is making to you about how risky the upgrade is. A change in the last number means "safe, just bug fixes"; the middle means "new stuff, but nothing you relied on broke"; the first means "watch out, I changed something you'll have to adapt to." Learning to read and set those numbers correctly is a mark of professional maturity, and this section shows how to compute them automatically from your commits.

The scheme is MAJOR.MINOR.PATCH, and the cleanest way to remember it is as a set of promises in decreasing order of importance. PATCH (the rightmost) is "I fixed a bug; your code should still work exactly as before." MINOR (the middle) is "I added a feature; your existing code still works, but there's new capability if you want it." MAJOR (the leftmost) is the serious one: "I broke backward compatibility; upgrading may require you to change your code." A useful analogy is editions of a textbook: fixing typos is a patch reprint, adding a new chapter is a minor edition, but renumbering all the chapters so every reference in your notes is now wrong — that's a new major edition. The rule that ties it together: a bigger bump always wins over a smaller one in the same release, and bumping a higher number resets the lower ones to zero (1.4.2 with a new feature becomes 1.5.0, not 1.5.2).

Now the payoff, and the reason this sits right after the changelog section: if your commits already declare their type via conventional commits, a program can decide the version bump for you with no human judgement at all. A fix: commit means patch, a feat: means minor, and a commit flagged BREAKING means major — so the highest-severity change since the last release dictates the next number. The mistake to avoid — and it trips people up because these numbers look like decimals — is thinking 1.9.0 is "almost 2.0" or that 2.9 rolls over to 3.0. They aren't decimals; each field is an independent counter, so the minor after 2.9.0 with a new feature is 2.10.0, not 3.0.0. The version only crosses to a new major when something actually breaks, never by "running out of" minor numbers. The lab below is a compact version of the exact engine inside real release tools like semantic-release.

Conventional commits let you compute the next version automatically: a feat bumps minor, a fix bumps patch, a breaking change bumps major. This is how release automation works.

semver.pydef next_version(current, commits):
    major, minor, patch = map(int, current.split("."))
    bump = "patch"
    for c in commits:
        if "BREAKING" in c: bump = "major"; break
        if c.startswith("feat") and bump != "major": bump = "minor"
        elif c.startswith("fix") and bump == "patch": bump = "patch"
    if bump == "major": return f"{major+1}.0.0"
    if bump == "minor": return f"{major}.{minor+1}.0"
    return f"{major}.{minor}.{patch+1}"

print(next_version("1.4.2", ["fix: typo"]))                    # 1.4.3
print(next_version("1.4.2", ["feat: new endpoint", "fix: x"])) # 1.5.0
print(next_version("1.4.2", ["feat: x", "BREAKING: drop v1"])) # 2.0.0

1.4.3
1.5.0
2.0.0

8 · Professional — connect to GitHub professional

Everything you've built so far lives in exactly one place: the hard drive in front of you. Spill coffee on the laptop, and the entire project — every commit, every carefully written message — is gone. And nobody else can see it, review it, or contribute. A repository that only exists on your machine is a diary; connecting it to a remote turns it into a shared, backed-up, collaborative project. This is the step where your local Git becomes a team sport, and where "GitHub" (the website most people conflate with Git itself) finally enters the picture.

The crucial thing to understand is that a remote is just another full copy of your repository that happens to live on a server. It's not special or authoritative by nature — GitHub holds the same commits your laptop does, and your laptop is every bit as complete a copy. This is what "distributed" means in "distributed version control": there's no single master machine everyone depends on, just clones that sync with each other. By convention the primary remote is nicknamed origin (that's just a friendly label for a long URL), and the primary branch is called main. The mental model to hold: think of the remote as a shared cloud drive for your history, and push/pull as the sync buttons in both directions.

Which is exactly where the beginner mistake hides. push and pull are not automatic — Git never talks to the remote behind your back. Nothing you commit locally appears on GitHub until you explicitly push, and no teammate's work reaches you until you pull. New developers routinely commit all day, assume it's "saved to GitHub," and are baffled when a colleague can't see any of it — because it never left the laptop. The -u flag in git push -u origin main is a small kindness: it links your local branch to its remote counterpart once, so afterwards a bare git push and git pull know where to go without you respelling the destination every time. And git clone is simply this whole relationship established in reverse — it downloads a complete existing repository (all its history included) onto your machine, which is how you start working on any project that already lives on GitHub. Collaboration proper — branches, pull requests, resolving conflicts — is DF3; this section is just getting your history off the island.

remote.shgit remote add origin git@github.com:you/proj.git
git branch -M main
git push -u origin main            # push + set upstream
git push                           # thereafter
git pull                           # get others' commits
git clone git@github.com:you/other.git

9 · Tech-lead — enforce conventions with a hook tech-lead

Here's a pattern every tech lead learns the hard way. You introduce conventional commits to the team, everyone nods, and for two weeks the history is beautiful. Then a new engineer joins, doesn't know the rule, and writes update. A senior in a hurry writes fix. Someone commits asdf at 2am. Within a month your changelog automation is producing garbage and your version bumps are wrong — because a convention that depends on everyone remembering is a convention that's already failing. The lead's job in this final section is to stop relying on discipline and start relying on enforcement.

The tool for this is a Git hook: a script Git runs automatically at a specific moment in its workflow, without anyone asking. The one we want is commit-msg, which fires the instant you finish writing a commit message and gets handed the message to inspect — it can approve the commit or reject it outright. The mental model is a spell-checker that refuses to let you send the email: instead of catching the bad message later in code review (by which point it's already in someone's history), the hook catches it at the source, at commit time, and simply won't let a non-conforming message through. How does a hook say "no"? Through the oldest convention in Unix: its exit code. Exit 0 means "all good, proceed"; any non-zero exit (typically 1) means "stop," and Git aborts the commit. That single number is the entire mechanism.

Two things about hooks routinely surprise people, and both matter if you're the one setting this up. First, enforce at the right layer: a local hook is instant feedback for the developer, but the well-known mistake is trusting it alone — hooks live in each person's local repo, so someone can bypass one with --no-verify or simply not have it installed. The professional setup pairs the local hook (fast feedback) with the same check running in CI (the real gate nobody can skip). Second, and this catches nearly everyone: the .git/hooks directory is not part of your repository — it doesn't get committed, so cloning the repo doesn't give teammates your hook. To share a hook you commit the script into a tracked folder (say hooks/) and point Git at it with git config core.hooksPath hooks, or adopt a framework like pre-commit that manages this for you. Get this right and the whole back half of the chapter clicks into place: enforced conventions (§9) make the changelog (§6) and semantic versioning (§7) automatic and trustworthy — which is exactly the leverage that separates a tech lead from an individual contributor.

A lead makes history useful and automatable by mandating a commit convention and enforcing it with a hook (and in CI). Then changelogs (§6) and versioning (§7) come for free.

commit_msg_hook.pyimport re
PATTERN = re.compile(r"^(feat|fix|docs|refactor|test|chore)(\(.+\))?: .{1,72}$")

def valid(message: str) -> bool:
    first = message.strip().splitlines()[0] if message.strip() else ""
    return bool(PATTERN.match(first))

for msg in ["feat: add login", "fixed stuff", "fix(auth): handle null token", "wip"]:
    print(f"{'OK    ' if valid(msg) else 'REJECT'}  {msg}")
# real hook (.git/hooks/commit-msg):  sys.exit(0 if valid(open(sys.argv[1]).read()) else 1)

OK      feat: add login
REJECT  fixed stuff
OK      fix(auth): handle null token
REJECT  wip

git init
echo "hello" > hello.txt
git status            # hello.txt is untracked (working tree)
git add hello.txt     # now staged
git commit -m "Add hello.txt with a greeting"
git log --oneline     # one commit in history

git diff                 # unstaged changes across all files
git add report.py        # stage just this one
git diff --staged        # exactly what will go into the commit
git status               # report.py staged, notes.txt still modified
git commit -m "Fix off-by-one in report totals"

# 1. unstage but keep the edit in the working tree
git restore --staged secrets.env

# 2. throw away local edits to a tracked file (irreversible for that edit)
git restore config.py

# 3. reword the most recent (unpushed) commit
git commit --amend -m "Add rate limiter to the API client"

# .gitignore
__pycache__/
*.pyc
.venv/
.env
*.key
.DS_Store

git rm --cached .env
git commit -m "Stop tracking .env; add to .gitignore"

import subprocess, re

def sh(*args):
    return subprocess.run(["git", *args], capture_output=True,
                          text=True).stdout.strip()

def last_tag():
    t = sh("describe", "--tags", "--abbrev=0")
    return t or "v0.0.0"

def commits_since(tag):
    rng = f"{tag}..HEAD" if tag != "v0.0.0" else "HEAD"
    log = sh("log", rng, "--format=%s%n%b")
    return log.splitlines()

def next_version():
    tag = last_tag()
    major, minor, patch = map(int, re.findall(r"\d+", tag)[:3] or (0, 0, 0))
    lines = commits_since(tag)
    bump = "patch"
    for ln in lines:
        if "BREAKING" in ln:
            bump = "major"; break
        if ln.startswith("feat") and bump != "major":
            bump = "minor"
    if bump == "major":  major, minor, patch = major + 1, 0, 0
    elif bump == "minor": minor, patch = minor + 1, 0
    else:                 patch += 1
    return f"v{major}.{minor}.{patch}"

print("current:", last_tag(), "-> next:", next_version())

#!/usr/bin/env python3
import sys, re

PATTERN = re.compile(
    r"^(feat|fix|docs|refactor|test|chore|perf)(\(.+\))?: .{1,}")

msg = open(sys.argv[1]).readline().rstrip("\n")
if not PATTERN.match(msg):
    print("commit rejected: message must be Conventional Commits, e.g.")
    print("  feat(auth): add token refresh")
    print(f"got: {msg!r}")
    sys.exit(1)

Knowledge check check yourself