Version control

A system that keeps every saved version of a project, with who changed what and when, so you can compare any two versions or go back to one. Git is the one this course uses, and the one you will keep meeting.

An agent can be confidently wrong across a whole project in a minute. Version control is what makes that cheap: you can see precisely what it did, throw away what you don't want, and return to the last state that worked. Without it, every agent mistake is a manual repair job.

One project under version control: your files, plus a hidden folder called .git that holds the entire history. Run git init in a folder and it becomes a repository. Delete .git and the history is gone.

The whole history sits on your machine, in a folder an agent can reach. Reading it is how an agent catches up at the start of a session, and damaging it is one of the few ways it can really hurt you, which is why agent tools treat that folder as special.

A saved snapshot of the whole project, with a message, an author, a time, and a link to the commit before it. Its name is a hash: a long fingerprint worked out from all of that, so identical contents always get the same name.

Committed work is the only agent work that is safe, because anything uncommitted can be overwritten by one command. And since each hash includes the hash before it, nobody can alter the past without every later hash changing, so a history can serve as evidence.

A list of exactly what changed between two versions: the lines removed, the lines added, and a few around them for context. Removed lines start with a minus sign and added lines with a plus.

An agent's summary is a story it tells afterwards. The diff is the thing itself, and it shows what the summary left out: a deleted test, a changed setting, a file you never asked it to touch. Learning to read one is the first skill of supervising an agent.

A holding area between your files and the next commit. git add puts a copy of a file there, exactly as it is at that moment, and git commit records only what is there. This lets you commit one change while others wait.

Agents like sweeping commands. git add -A stages whatever is in the folder, including the .env it just created and the debug file it forgot about. Naming each file keeps the commit to what you meant, and it is much the easiest way to keep a secret out of history.

A name that points at one commit, and moves forward each time you commit on it. It lets you work on one thing without touching the main line. HEAD is git's marker for which branch you are on.

A branch is how you give an agent room to be wrong. If the work goes badly, you switch back and delete the branch, and the main line never knew. Since branches cost almost nothing, one for each task is a sensible default.

The branch everyone treats as the real version of the project. Work happens elsewhere and joins it when it is ready. The name is only a convention: many older projects call it master.

An agent working on main is one bad commit away from breaking what everyone depends on. Don't assume your tools protect it. Claude Code's auto mode, as of November 2026, allows pushes to the default branch (sending your commits to a shared server, coming shortly) unless your own rules or the server stop them.

Bringing one branch's work into another. If only one side has moved, git simply slides the branch forward. If both have, it finds the commit they share, combines the two sets of changes, and makes a new commit with two parents.

Once several agents are working, the merge is where their work meets, and where two individually correct changes can stop being correct together. Merge a branch that has passed its checks, then run those checks again on the result.

What happens when two branches changed the same lines. Git can't choose, so it stops and writes both versions into the file between markers, and someone has to decide what the file should really say.

Agents resolve conflicts quickly and often pick wrong, because making the markers go away is easy and looks finished. So ask what each side was trying to do. And the opposite danger is real: a merge with no conflict can still be broken, since git compares text and knows nothing about code.

Moving your commits so they start from a newer point, by replaying them one at a time. The result looks as if you began today and worked in a straight line. But each replayed commit is a new commit, with a new hash.

It lets an agent's messy branch become a clean series before anyone reads it. The risk comes from the same place as the benefit: it rewrites history, so it is only safe on commits nobody else has. An agent won't know who else has them unless you say.

Another copy of the repository, usually on a server, which yours knows by name. The usual name is origin. Your machine also keeps its last-known note of where the server's branches were, called origin/main.

Work you haven't sent to a remote exists on one disk only. And origin/main is a memory, not a fact: it was true the last time you checked with the server. An agent reasoning about what is on the server from an out-of-date origin/main can be confidently wrong, so have it fetch first.

Push sends your commits to the remote. Pull fetches the remote's commits and brings them into your branch. Fetch only downloads, and changes none of your work. Nothing travels until you do one of these.

A push is where a local mistake becomes everyone's, so it deserves more care than anything else an agent runs in a normal day. You can't quietly take back what others have already pulled. Decide in advance whether your agent may push at all.

A request, on a hosting site such as GitHub, to merge one branch into another. It shows the diff, collects comments and check results, and keeps the whole discussion attached to the change.

This is the gate between an agent and the real project. Checks run, someone reads it, and the decision goes on the record. It is also where you write what you checked and why you believe it, which makes it proof that a person was in charge.

A clone is a full copy of a repository on your machine, history included. A fork is your own copy on the hosting site, which you can change without asking anyone and later propose changes from.

Cloning is also how someone else's instructions reach your agent: a repository can hold files an agent reads and obeys, such as AGENTS.md or tool settings. Read those before you let it run anything. And an agent with a fork, and no write access to the original, is limited in what it can break.

A file listing the names and patterns git should not track, such as dependencies, build output and secrets. Git then behaves as if those files weren't there. It only applies to files git isn't already tracking.

Without one, git add -A commits node_modules and your keys. One line here is a small permanent rule, and better than asking an agent to remember. But it can't undo anything: a secret already committed stays in the history.

The note attached to a commit. Its first line says what changed, short enough to read in a list, and the body says why. Conventional Commits is a common format for that first line: fix(cart): stop charging VAT twice.

The next session's agent starts knowing nothing and reads git log to catch up, so this is the memory you leave it. It also matters for you: a message giving a real reason shows you understood the change, and "fix stuff" shows nothing. An agent will write vague ones unless told otherwise.

A commit that does one thing and leaves the project working. If you need the word "and" to describe it, it is probably two commits. A rename, a bug fix and a reformat are three, even if they happened in the same hour.

Left alone, an agent makes one huge commit at the end, which can't be reviewed or undone in part, and which hides the moment any bug arrived. Small commits fix all of that. A series also shows the order you thought in, such as failing test, fix, tidy, which is the kind of evidence a single large commit can't give.

Undoing a commit by adding a new commit that does the opposite. The mistake stays in the history along with its undoing, and nobody else's copy is disturbed.

This is the undo for anything already pushed. It needs no force, it can't lose anyone's work, and it leaves a record of what went wrong and that someone dealt with it. Make it your agent's default, because left to itself it may reach for something worse.

Moving the current branch to a different commit. Soft leaves your files and staged work alone. Mixed, the default, also clears what is staged. Hard also overwrites your files to match that commit, which destroys uncommitted work.

git reset --hard is the fastest way for an agent to destroy hours of work, because it looks like tidying up. Commits it drops can usually be rescued. Uncommitted changes can't, because git never saved them. Never let an agent run it without asking first.

Telling the server to replace a branch with yours, even when that throws away commits it has. A normal push can only add. This one can delete other people's work from the server, and it barely mentions it.

This is the git command whose damage lands on other people. An agent reaches for it when a normal push is refused, and a refused push often means someone else's work is in the way. On your own branch after a rebase it is routine. On a shared one, it needs a person.

A shelf for unfinished work. git stash puts your changes to tracked files aside and returns your folder to the last commit, and git stash pop brings them back. New files git isn't tracking yet stay where they are unless you add -u.

A stash has no branch and no reminder, and agents don't remember across sessions, so work stashed "to get a clean tree" can sit there unnoticed for ever. Anything you care about belongs in a commit on a branch, which costs no more and shows up in the history.

A permanent name for one commit, usually a release such as v1.2.0. Unlike a branch, it doesn't move when you commit. An annotated tag also records who made it, when, and a message.

A tag gives you and your agent a fixed point: compare against v1.2.0, go back to the last release. An agent that moves a published tag breaks that promise for everyone who already has it, so treat tags as write-once.

A view of a file showing, for each line, the last commit that changed it and who made it. The name is unfortunate: you use it to find out why a line exists, not whose fault it is.

Before an agent changes a strange line, it should read why that line is there, since it may be preventing something invisible. That only works if the history is good, and an agent that reformats a file while fixing it makes itself the author of every line.

A way to find the commit that introduced a bug by halving the range. You name a good commit and a bad one, git checks out the middle, you say good or bad, and it halves again. A thousand commits takes about ten tests.

When an agent is stuck guessing at a bug, bisect stops the guessing, because its answer is one commit. It can run unattended too: give it a script, and it finds the commit while you do something else. It depends on every commit building, and on the commit it names being small enough to read.

A second working folder attached to the same repository, on its own branch. The folders share one history, but each has its own files, its own staged changes, and its own idea of which branch is current.

Two agents in one folder interfere without any error: one switches branch under the other, and a commit picks up files it shouldn't have. A worktree for each agent stops that, and it is much lighter than a full clone. Files git ignores, such as .env and node_modules, aren't there until you add them.

A script git runs by itself at certain moments, such as just before a commit or a push. If the script exits with anything other than 0, git stops. Hooks live in your own copy of the repository and aren't part of its history.

A hook turns "please run the linter", a tool that checks code for known bad habits, into something that happens every time, and its error goes straight to the agent. But it only guards one machine, and a single flag skips it, which an agent under pressure may well use. Treat it as a fast helper, and run the same checks on the server.

A website that hosts git repositories and adds what git lacks: pull requests, reviews, issues, permissions and automated checks on every push. Git is the tool. GitHub is one company's service built around it, and GitLab is another.

Everything on your machine can be skipped by whoever is at the keyboard, and that includes your agent. The server is where rules really hold: branch protection, required checks, required review. An agent with limited access can't talk its way past any of them.

Git's private diary of everywhere HEAD has been: each commit, checkout, reset and rebase. When a commit seems lost, it is usually listed here, and you can walk straight back to it.

This is the real undo, and what makes it reasonable to let an agent move fast: anything it committed can usually be recovered, even after a bad reset or rebase. Its limits matter as much. It is local to one machine, it expires, and it knows nothing about work that was never committed.

Rules at three levels that stop dangerous git commands: a deny rule in the agent's settings, a script that inspects each command before it runs, and protection on the server. Each one catches things the others miss.

A line in an instructions file is a request, and an agent trying hard to finish will do what looks like progress. Local rules catch local damage, such as reset and clean, which no server ever sees. The server catches whatever reaches it, however it was spelled. You need both, and each needs testing.