A

Your AI Just Changed 30 Files. Do You Dare Hit Accept?

#Technology#Learning#AI Literacy#Workflow#Agents

TL;DR

Git stopped being a programmer's tool. Agents change dozens of files at once, run several tasks in parallel, and now edit your notes as well — all three need a foundation you can trace and roll back. You don't have to memorise commands: understand the four places (working directory, staging, local repo, remote), let the agent type, and keep the reviewing for yourself. The interactive handbook below is clickable: a four-zone simulator, a branch sandbox, 25 commands with what each one actually touches, and ready-made prompts.

Three situations, to start with.

One: vibe coding. People with no programming background are now getting agents to build web pages and small tools for them. But an agent changes dozens of files in a single go, and when you’re halfway through and realise the direction is wrong, you need a way back to how things looked before it started. That undo button is git.

Two: how the agents themselves work. The mainstream coding agents borrow git’s machinery directly. Claude Code, for instance, uses git worktrees so several tasks can run at once without overwriting each other — and what changed, and when, stays traceable in the commit history.

Three: your personal knowledge base. Karpathy has written about an LLM wiki: a set of interlinked Markdown notes that an agent keeps organising and maintaining. As he puts it in his own notes, the wiki is essentially a git repo, so version history and branching come for free. If an agent edits your notes every day, you need to know what it changed — and whether you can get the old version back.

So the question isn’t whether to learn git. It’s how to learn it without it being a slog.

Who this handbook is for

I put together an interactive Git handbook for people with no programming background. It starts with four places. The working directory holds the files you’re editing. Staging is where you pick out the changes that go into this save. The local repository is the permanent history on your machine. The remote is the shared backup in the cloud. Every git command, without exception, is moving content between those four places.

You don’t have to memorise anything. Click through the simulator and you’ll see it. And for the situations that actually come up — branching off, running tasks in parallel, reviewing what came back, merging, undoing, pushing at the end of the day — the handbook has prompts ready to copy. Your agent types the commands.

How to use it

Start with the map and get the four places straight. Then go to the simulator and the branch sandbox and push the buttons a few times. When a real situation comes up, grab a prompt from the command library or the section on talking to agents. And if something goes wrong, skip straight to rescue.

The handbook is right below. Go ahead and click.

Nexus · Interactive handbook

Git: how it actually works

Snapshots, pointers, and a safe way to let agents work in parallel.

You do not need to memorise commands. You do need to understand what an agent just did to your repo. This handbook breaks git into four places and four ideas, and for every command tells you the same four things: how it works, when to reach for it, what it changes, and what to say to your agent.

Click an arrow to see the commandPush the buttons in the simulatorCopy any prompt in one click

01 · The map

Four places, one pipeline

Every git command is really just moving content between these four places. Learn this picture and every command later has somewhere to sit.

Working Directory

The files you can see and edit

Staging Area

The draft of your next commit

Local Repository

The full history on your machine (.git)

Remote Repository

The copy that lives on GitHub

Think of online shoppingThe working directory is the stuff you are browsing. Staging is your cart — what you picked out for this one order. The local repo is the receipt, and once it is printed you cannot edit it. The remote is that receipt synced to the company cloud, where other people can finally see it. add puts things in the cart, commit checks out, push uploads the receipt.
One thing about where you put reposKeep git repos in a plain local code folder. Putting a .git folder inside a sync service like iCloud or Dropbox is a classic trap — a sync conflict can quietly corrupt the repo internals.

02 · The model

Four ideas and you are done

Get these four and you will see why branches are cheap, and why "rewriting history" is really just making new commits.

Git does not store "which lines changed". It stores a snapshot of the whole project at each commit. Unchanged files are not duplicated — the snapshot just points at the existing copy — so this wastes far less space than it sounds like it would.

The diff you look at is computed on the spot from two snapshots. It was never stored.

Snapshot ASnapshot BSnapshot C
git cat-file -p HEAD         # what the last commit holds
git cat-file -p HEAD^{tree}  # the directory it points at

Every commit has a fingerprint like 5d6a2d, computed from its content, its parent, the author, the time and the message.

Change any one of those and the hash changes completely. Which is why rebase and amend — the "rewrite history" commands — really just build new commits. The old ones are still there, with nothing pointing at them.

93d4265d6a2d3ja3ro

Each commit records its parent’s hash, which chains them together. Alter anything in the middle and every hash after it changes too — which is also how git notices a file that was quietly tampered with.

A branch is a small file containing one commit hash. Creating one costs essentially nothing — it is one more label.

When you commit, the label on your current branch moves forward to the new commit. That is the entire secret of branching.

…5d6a2d3ja3ro
main → 3ja3rofeature → 5d6a2d
cat .git/refs/heads/main    # one line: a hash

HEAD is the pointer for "where you are standing right now", and it usually points at a branch. git switch is really just moving HEAD and swapping your working directory for the snapshot there.

When HEAD points straight at a commit instead of a branch, that is a detached HEAD. Commits made there have no branch protecting them and are easy to lose once you switch away. To keep them: git switch -c a-new-branch.

HEADmain3ja3ro
cat .git/HEAD
# ref: refs/heads/main

03 · Simulator

Push it through yourself

Click in order: edit a file, add, commit, push. Then try "a teammate pushed" and hit push again to see what happens.

04 · Branches

Branch sandbox: fork and merge

Dots are commits, labels are branch pointers, and the orange one is where HEAD is sitting. Commit a few times on main, make a branch, commit on each, then merge.

05 · Parallel

Why worktrees matter in the agent era

Several agents editing the same folder will step on each other. A worktree lets one repo be checked out into several directories at once, each sitting on a different branch.

The .git database (only one)All commits, branches and history are shared

~/Code/app

main

Your own main directory. Keep it clean — it is your reference point and where things finally merge.

~/Code/wt-auth

agent/auth

Agent A works here. Login code only, and it cannot disturb your main directory.

~/Code/wt-docs

agent/docs

Agent B works here. Docs only, running on its own clock.

git worktree add ../wt-auth -b agent/auth   # new directory + new branch
git worktree list                           # see your worktrees
git worktree remove ../wt-auth              # clean up when done

How this maps to your tools

Coding agents on your machine：Give each background session its own worktree, so two sessions never overwrite each other.

Cloud sessions：Each thread is its own session on its own branch. Conflicts are ordinary merge conflicts. One task, one thread, one branch.

Delegating to sub-agents：Isolate each sub-task in its own worktree and branch, and merge when you collect the results.

Six rules for running things in parallel

  1. Name branches after the task — agent/auth, not session-2.
  2. The same branch cannot be checked out in two worktrees at once.
  3. Each worktree needs its own dependency install.
  4. Write the scope down before you hand out work. Out-of-scope edits are the hardest to review.
  5. Read the diff before you merge, and merge one branch at a time.
  6. Start with two or three in parallel. Do not get greedy.

06 · Command library

Every command: how, when, what it touches, what to say

The four little tags under "what it changes" are the four places from the first diagram. The ones that light up are what this command actually touches.

Working dirStagingLocal repoRemote

  • git initCreates the hidden .git folder here
  • git init -b mainSame, but names the default branch
How it works

It creates a .git directory, which is the whole repository database: the object store, the branch pointers, the config. Your own files are not touched at all.

When to use it

The first time a new project should be under version control.

What it changes

Adds .git and nothing else. Delete .git and you delete the entire history — the files themselves survive.

Prompt for your agent
Initialise a git repo here with main as the default branch. Add a .gitignore suited to this project’s language. Before the first commit, show me what would be tracked and wait for my OK, then commit with the message init.

Working dirStagingLocal repoRemote

  • git clone <URL>Full history, and names the remote origin
  • git clone --depth 1 <URL>Latest snapshot only — fast, but no real history
How it works

It downloads every object in the remote repo, checks the default branch out into a working directory, and records the remote as origin. What you get is a complete, independent copy, not a shortcut.

When to use it

Picking up someone else’s project for the first time — an open-source repo, say.

What it changes

Creates a directory locally. The remote is untouched.

Prompt for your agent
Clone <repo URL> into my local code folder. When it is done tell me the default branch, the last 5 commits, and the setup steps from the README. Do not run any install or start commands.

Working dirStagingLocal repoRemote

  • git statusThe full report
  • git status -sbShort form, one line per file
How it works

It compares three things — working directory, staging area, and the last commit — lists the differences, and tells you which branch you are on and how far ahead or behind the remote you are.

When to use it

Before and after literally anything. This is the one habit worth building.

What it changes

Read-only. It changes nothing.

Prompt for your agent
Run git status and then tell me in plain English: which branch I am on, what is unstaged versus staged, whether there are untracked files, and how many commits I am ahead or behind origin.

Working dirStagingLocal repoRemote

  • git diffWorking directory vs staging (what you have not added yet)
  • git diff --stagedStaging vs last commit (what you are about to commit)
  • git diff main...agent/xWhat agent/x added since it forked
How it works

Diffs are not stored anywhere — git computes them on the spot from two snapshots. The different flags are just different ways of choosing which two.

When to use it

Checking yourself before a commit, and reviewing an agent’s work before a merge. Reviewing is the most important thing you do in a parallel workflow.

What it changes

Read-only.

Prompt for your agent
Use git diff main...agent/<branch> to show me what this branch changed relative to main. Group it by file and explain in plain English what each file does now and why it was probably done that way. Call out anything outside the task scope, any deleted files, and any config or dependency changes.

Working dirStagingLocal repoRemote

  • git log --oneline --graph --allThe shape of every branch on one screen
  • git log -p <file>How one file changed over time
  • git show <commit>Everything about one commit
How it works

Every commit records its parent, so log is simply walking back along that chain.

When to use it

When you want to know who changed something, when, and why.

What it changes

Read-only.

Prompt for your agent
Run git log --oneline --graph --all -20 and summarise for me: which branches exist, how far ahead of main each one is, and when the last merge happened.

Working dirStagingLocal repoRemote

  • git add <file>Stage one file
  • git add -pWalk through the changes and pick hunk by hunk
  • git add -AStage everything — watch out for files that should not go in
How it works

It photographs the file as it is right now and writes that into staging. Edit the file again afterwards and staging still holds the old shot — you have to add again.

When to use it

Whenever you want precise control over what goes into this commit. Three unrelated edits, two commits, that sort of thing.

What it changes

Only staging changes. Your files are untouched and no history is created.

Prompt for your agent
Stage only the files related to "<task>", then run git status and show me the list. Do not use git add -A, and never stage .env, keys, logs or large files — if you find any, stop and tell me.

Working dirStagingLocal repoRemote

  • git commit -m "message"One line of explanation
  • git commit --amendFix the last commit (only if it has not been pushed)
How it works

It bundles the staged snapshot together with the author, the time, the message and a pointer to the parent commit into one immutable object, then moves the current branch pointer onto it.

When to use it

Whenever one logically complete step is finished. The rule of thumb: one commit does one thing.

What it changes

Adds one entry to local history. Until you push it is yours alone and still adjustable.

Prompt for your agent
Commit what is staged. Write the message in the imperative and say why the change was made, not just what changed. Run the tests first — if they fail, do not commit, tell me why they failed.

Working dirStagingLocal repoRemote

  • .gitignoreOne rule per line: node_modules/, .env, *.log
  • git rm --cached <file>For files git is already tracking — remove from the index first
How it works

It is an ordinary text file that git consults during status and add. The catch: it only applies to files git is not already tracking.

When to use it

Dependency folders, build output, secrets, OS junk files.

What it changes

Does not touch history. A secret that was already committed stays in the history no matter what rule you add now.

Prompt for your agent
Check whether the project root has a .gitignore. Fill it out for the languages and tools this project actually uses, and make sure it covers .env, key files, dependency folders, build output and OS temp files. Tell me if any of those are already tracked — do not delete anything yourself.

Working dirStagingLocal repoRemote

  • git fetchUpdate every origin/* reference
  • git fetch --pruneAlso clear out references to branches deleted on the remote
How it works

It downloads the remote’s new commits and records them under remote-tracking branches like origin/main. Your own branches and working directory are not touched at all.

When to use it

When you want to see what other people did before deciding how to merge it. Steadier than pull.

What it changes

Only updates remote-tracking references. Safe.

Prompt for your agent
Run git fetch, then tell me whether local main and origin/main have diverged, which commits are new on the remote, who made them and which files they touched. Do not merge yet — wait for me.

Working dirStagingLocal repoRemote

  • git pullfetch + merge
  • git pull --rebasefetch + rebase
  • git pull --ff-onlyFast-forward or fail — the safest of the three
How it works

It fetches, then merges the remote branch into yours. If you have unpushed commits of your own, you get a merge commit or a conflict.

When to use it

When you have decided you want the latest code right now.

What it changes

Changes files in your working directory, and can produce a merge commit or a conflict.

Prompt for your agent
Sync with the remote using git pull --ff-only. If it cannot fast-forward, local and remote have diverged — do not merge automatically, tell me which commits each side has.

Working dirStagingLocal repoRemote

  • git push -u origin <branch>First push, and sets up tracking
  • git pushEvery push after that
  • git push --force-with-leaseA safer force push — still high-risk
How it works

It uploads the commits the remote does not have and moves the remote branch pointer forward. If the remote has commits you do not, git refuses — that refusal is protecting someone else’s work.

When to use it

When a chunk of work is done and you want it backed up or visible.

What it changes

Affects every collaborator. A force push overwrites remote history and other people’s commits can disappear.

Prompt for your agent
Push the current branch to origin. Check first that I am not on main, and do not use any force flag. If the push is rejected, explain why and stop — do not try to work around it.

Working dirStagingLocal repoRemote

  • git remote -vSee the remote URLs
  • git remote add origin <URL>Add a remote
How it works

origin is only a name pointing at a URL. One repo can have several — origin and upstream, for instance.

When to use it

Connecting a fresh local repo to GitHub, or keeping a fork in sync with the project it came from.

What it changes

Config only.

Prompt for your agent
Run git remote -v and tell me which remotes this repo has, what their URLs are, and which remote branch the current branch is tracking.

Working dirStagingLocal repoRemote

  • git branchList local branches
  • git branch <name>Create one at the current commit without switching
  • git branch -d <name>Delete a branch that has been merged
How it works

A branch is literally a small file containing one commit hash. Creating one is sticking on another label — essentially free. When you commit, the label on your current branch moves forward by itself.

When to use it

Before starting anything new. The habit: one task, one branch.

What it changes

Adds or removes a pointer. No commit content is touched.

Prompt for your agent
Create branch agent/<task> from the latest main and switch to it. Everything after this happens on that branch only — do not touch main.

Working dirStagingLocal repoRemote

  • git switch <branch>Go to an existing branch
  • git switch -c <new>Create it and go there
  • git checkout <branch>The old spelling — does too many jobs, easy to confuse
How it works

It points HEAD at another branch and swaps your working directory and staging area for the snapshot at that branch’s tip. checkout is the old command that did far too much; since 2.23 it has been split into switch (branches) and restore (files).

When to use it

Moving between tasks.

What it changes

Files in your working directory change. If uncommitted work would be clobbered, git refuses and says so.

Prompt for your agent
Before switching to <branch>, run git status. If there are uncommitted changes, stop and ask me whether to commit, stash or discard — do not decide on your own.

Working dirStagingLocal repoRemote

  • git merge <branch>Merge it into the current branch
  • git merge --no-ff <branch>Keep a merge commit even when it could fast-forward
  • git merge --abortBack out of a conflicted merge
How it works

It finds the common ancestor of the two branches and does a three-way comparison. If your branch has no new commits, it just fast-forwards the pointer. Otherwise it creates a commit with two parents. If both sides touched the same spot, it stops and waits for you.

When to use it

When a task branch is finished and reviewed and goes back into main. One branch at a time.

What it changes

Changes the history of the current branch, and on a conflict leaves markers in your files.

Prompt for your agent
I am on main. First run git diff main...agent/<branch> and give me a plain-English summary, then wait for my OK before merging. Run the tests after. If there is a conflict, list the conflicting files and explain what each side was going for — do not pick a side yourself.

Working dirStagingLocal repoRemote

  • git rebase mainReplay this branch’s commits on top of main
  • git rebase --abortBack out
How it works

It lifts your commits off and replays them one by one on a new base. The content is the same, but every commit has a new parent and therefore a new hash — you have really made a fresh set of commits.

When to use it

When you want your branch history to stay in a straight line and nobody else is using that branch.

What it changes

Rewrites history. Never rebase a branch that has been pushed and that other people are working on.

Prompt for your agent
My branch agent/<name> has never been pushed. Rebase it onto the latest main. Before you start, tell me how many commits ahead of main it is. Pause and explain any conflict instead of resolving it yourself, and confirm afterwards that nothing was pushed.

Working dirStagingLocal repoRemote

  • git cherry-pick <commit>Apply that commit’s change to the current branch
How it works

It takes the change one commit introduced and creates an equivalent new commit — new hash — on your current branch.

When to use it

You want one fix from another branch without merging the whole thing.

What it changes

Adds a commit to the current branch, and can conflict.

Prompt for your agent
Cherry-pick commit <hash> onto the current branch. Show me what it changed with git show first, then apply it. If it conflicts, stop and tell me.

Working dirStagingLocal repoRemote

  • git stashShelve your changes, working directory goes clean
  • git stash listSee what you shelved
  • git stash popBring it back and remove the entry
How it works

It saves the uncommitted changes from your working directory and staging into a temporary commit on a stack, then resets the working directory to the last commit.

When to use it

Work is half done and something urgent needs you elsewhere.

What it changes

Your changes vanish from the working directory for now. Remember to get them back — stashes are easy to forget.

Prompt for your agent
I need to switch tasks. Stash the uncommitted changes with git stash push -m "<description>", tell me the stash number, then switch branches. Remind me to pop it when I come back.

Working dirStagingLocal repoRemote

  • git restore <file>Discard working-directory changes (not recoverable)
  • git restore --staged <file>Unstage it — the change stays in your working directory
How it works

It overwrites the file in your working directory (or staging) with the version from staging or the last commit.

When to use it

You made a mess and want the last clean state back, or you staged the wrong file.

What it changes

Once working-directory changes are discarded, uncommitted content is gone.

Prompt for your agent
I want to undo my changes to <file>. Run git diff <file> first and show me what would be lost, then wait for my OK before running git restore <file>. That one file only.

Working dirStagingLocal repoRemote

  • git reset --soft HEAD~1Undo the last commit, changes stay staged
  • git reset HEAD~1Undo it, changes go back to the working directory (the default)
  • git reset --hard HEAD~1Undo it and throw the changes away
How it works

It moves the current branch pointer backwards. soft moves only the pointer; mixed resets staging too; hard resets the working directory as well, which is where data goes missing.

When to use it

A commit you have not pushed yet and want to redo. For anything already pushed, use revert instead.

What it changes

Rewrites local history. hard destroys uncommitted work.

Prompt for your agent
I want to undo the last commit but keep the changes. Use git reset --soft HEAD~1 and not --hard. Confirm first that the commit has never been pushed — if it has, stop and tell me.

Working dirStagingLocal repoRemote

  • git revert <commit>Create a new commit that undoes that one
How it works

It does not touch history. It adds a commit that applies the old change in reverse, so the record clearly shows it was done and then undone.

When to use it

Something that has already been pushed turned out wrong, and rewriting shared history is off the table.

What it changes

History only grows, never changes. The safest option for collaborators.

Prompt for your agent
Commit <hash> is already on the remote and needs to be undone. Use git revert — no reset, no force push. Tell me first what that commit changed and which files the revert will affect.

Working dirStagingLocal repoRemote

  • git reflogEvery recent move of HEAD
  • git reset --hard <hash from reflog>Go back to that point
How it works

Git quietly records every position HEAD has held on this machine. Even after a bad reset or a deleted branch, the commits are usually still there — they just have no label pointing at them any more.

When to use it

After a mistake, when you want your work back. It is local only, never syncs to the remote, and gets cleaned up eventually (about 90 days by default).

What it changes

Read-only in itself. The reset you use to recover does change your state.

Prompt for your agent
I think I lost some commits. Do not change anything — just run git reflog and show me the last 15 moves of HEAD, help me spot the position from before the mistake, and propose a recovery plan. Wait for my OK before running it.

Working dirStagingLocal repoRemote

  • git worktree add ../wt-auth -b agent/authNew directory plus new branch
  • git worktree listSee your worktrees
  • git worktree remove ../wt-authClean up when done
How it works

Several working directories share one .git object store, each with a different branch checked out. No duplicate clones, no stepping on each other.

When to use it

Running several agents in parallel, or reviewing one branch while you keep building on another.

What it changes

Adds directories. The same branch cannot be checked out twice, and each worktree needs its own dependency install.

Prompt for your agent
Set up a worktree for a parallel task: create ../wt-<task> with a new branch agent/<task> based on the latest main. Tell me the path when it is done and remind me to install dependencies in the new directory.

Working dirStagingLocal repoRemote

  • git tag v1.0Lightweight tag
  • git tag -a v1.0 -m "message"Annotated tag, with a note
  • git push origin v1.0Tags have to be pushed separately
How it works

Like a branch, a tag is a name pointing at a commit — except a tag never moves when you commit.

When to use it

Releases, or the finished state of the code for each lesson in a course.

What it changes

Adds a pointer, nothing else.

Prompt for your agent
Put an annotated tag lesson-03 on the current commit with the note "final code for lesson 3". Tell me which commit that is first and wait for my OK, and remind me that pushing a tag takes its own command.

Working dirStagingLocal repoRemote

  • gh pr createOpen a PR from the terminal with the GitHub CLI
How it works

A PR is GitHub’s idea: one branch formally asks to be merged into another so people and automated checks can review it first. Git itself has no concept of a PR.

When to use it

Team work, or any time you want a review record and automated tests before a merge.

What it changes

Creates a review record on the platform. Nothing changes on the main branch until it is merged.

Prompt for your agent
Push branch agent/<name> to origin, then open a PR against main with gh pr create. Make the title say what was done, and in the body cover: background, what changed, how to test it, known risks.

07 · Talking to agents

How to talk to an agent about git

Your job is to assign work and review results, not to type commands. These patterns keep an agent fast without letting it wander.

The universal shape: five blocks

GoalWhat needs to be true when this is done
ScopeWhich files or directories it may touch
LimitsWhat it must not touch, and which commands are off the table
Done meansHow we know it worked, and which tests to run
Report backWhat I want to see when it finishes
Example: all five blocks filled in
Goal: add error messages to the login page of the course demo.
Scope: only src/login/ and its tests.
Limits: work on a new branch called agent/login-error; do not touch main; no force push; never commit .env; do not change dependencies.
Done means: all existing tests pass, plus one new test covering the error message.
Report back: a plain-English summary of git diff main...HEAD, flagging anything outside the scope above. Do not push.

Plain English in, commands out

You sayIt will probably runWatch for
"Save a checkpoint"add + commitLocal only — nothing is uploaded yet
"Put it up"pushOther people can see it now
"Show me what changed"status / diffRead-only, ask freely
"Go back to yesterday"revert or resetWhether it was pushed decides which one
"Park this, I need to switch"stash or a new branchAsk where it parked it — stashes get forgotten
"Bring that branch in"mergeAsk for the diff summary first
"Sync with the latest"fetch / pullFetching first is the safer habit

Prompts by situation

Before you start: a checkup

Have the agent read the room before every new task

Prompt
Before we start, check things without changing anything: 1) does git status show uncommitted work; 2) how far is this branch from origin; 3) git log --oneline -5 for the recent commits. Report back in plain English, then ask me what we are doing today.
Branch off for one small task

One task, one branch, off the latest main

Prompt
Task: <description>. Run git fetch first, then create branch agent/<task> from the latest origin/main. Work only on that branch and only inside <directory>. Run the tests when you are done and give me a plain-English summary of git diff main...HEAD. Do not push.
Fan out to three parallel tracks

Pairs with worktrees or cloud threads

Prompt
Handle these three independent tasks in parallel, each on its own branch and its own working directory: 1) <task A> on agent/a; 2) <task B> on agent/b; 3) <task C> on agent/c. Each one stays inside its own scope and never touches another’s files. When all three are done, give me one table: branch, files changed, test result, risk. Do not merge anything.
Review what the agent produced

Your real job: read the diff, not the "all done" message

Prompt
I want to review branch agent/<name>. Give me: 1) the list of files changed relative to main; 2) what each change was trying to do; 3) anything outside the original scope; 4) deletions, config changes and dependency changes; 5) the three spots you think I should look at closely. Plain English, and do not modify any code.
Merge one branch

One at a time, read before you merge, test after

Prompt
Review passed. Merge agent/<name> into main: confirm main is up to date first, use merge, pause and explain if there is a conflict, run the tests afterwards, and tell me when they pass. I decide whether we push.
Work through a merge conflict

Make it explain before it edits

Prompt
The merge conflicted. Do not change anything yet: list the conflicting files, and for each spot explain what the current branch and the merged branch were each trying to do, then recommend an approach and say why. Wait for my OK, then edit and run the tests.
Something broke and I want it undone

Stop first, let it diagnose

Prompt
Do not run anything that modifies the repo. Tell me: 1) whether the commit I want to undo has been pushed; 2) which branches it is on; 3) the safest way to undo it — revert if pushed, reset --soft if not — and what each would do. Wait for my OK.
Wrapping up: summarise and push

The same closing move every day

Prompt
End-of-session check: 1) run git status and confirm nothing is missing and nothing is in there that should not be; 2) summarise what we committed today; 3) push the current branch to origin, no force; 4) write a PR description covering background, changes, testing and risks.

Git rules to put in your project instructions

Drop these in the instruction file at the root of your repo (CLAUDE.md, for example). Coding agents read it at the start of every session, so you write it once and every session behaves.

Git rules (paste as-is)
## Git rules
- Never commit straight to main. Every task gets a branch named agent/<task>.
- One commit does one thing. The message says why, not just what.
- Before committing, show me git status and a diff summary and wait for my OK.
- Never commit .env, secrets or large files. If one shows up, stop and tell me.
- git push --force, git reset --hard, git clean -fd and git branch -D are forbidden unless I say yes in this conversation.
- Never rebase a branch that has been pushed.
- On a merge conflict, explain what each side was trying to do and propose an approach. Do not pick a side on your own.
- At the end of each session, report in plain English: what changed, why, and what is still risky.

Red lines: see these and slow down

CommandWhat it doesSafer move
push --forceOverwrites the remote with your history — other people’s commits can vanishfetch, then merge or rebase, then push normally
reset --hardThrows away every uncommitted change, unrecoverablystash first, or branch off as a backup
clean -fdPermanently deletes every untracked fileRun clean -n first to preview what goes
restore . / checkout .Discards everything in the working directoryRead the diff first, then restore one file at a time
branch -DForce-deletes a branch that was never mergedUse -d — it refuses when the branch is unmerged
rebase a pushed branchRewrites shared history and dislocates everyone elseUse merge
--no-verifySkips the pre-commit checksFix whatever the check is complaining about

Learning mode: make the agent teach while it works

Teaching-mode prompt
From now on, run all git operations in teaching mode. Before each command, tell me in one sentence which of the four places it will change — working directory, staging area, local repository, remote — and then run it. After it runs, confirm the result in one sentence. Any term I might not know, explain it once with an everyday analogy.

08 · Rescue

When something goes wrong

Almost anything in git history can be recovered. The trick is to stop, look at the state, and only then act. Every rescue starts the same way: do not touch anything yet.

Just committed and realised a file or the message is wrong (not pushed)

Use git commit --amend to fold the new change into the previous commit, or to fix the message alone. It builds a new commit and drops the old one, so it is only safe before a push.

Say this to your agent
I just committed but left out <file>. Confirm the commit has not been pushed, then add that file and fold it into the last commit with git commit --amend, keeping the message as it is.
Committed on the wrong branch (not pushed)

Do not panic. The commits are fine, they are just standing in the wrong place. The move is: create a branch here to hold them, then walk the original branch back. That second step is a reset, so make the agent explain the plan first.

Say this to your agent
I committed on main when it should have been a new branch. Do not touch anything yet: tell me the hashes of those commits and propose a plan — create branch agent/<name> to keep them, then bring main back to origin/main. Explain the effect of each step and wait for my OK.
Need to undo something that is already pushed

Use git revert to create an opposite commit. The history will show it was done and then undone, which is the safest possible outcome for everyone else. Do not reset and force push.

Say this to your agent
Commit <hash> is already on the remote and needs undoing. Use git revert. No reset, no force push. Tell me which files the revert will change.
Ran reset --hard by mistake, or deleted a branch

git reflog is the safety net: find the hash HEAD was at before the mistake and go back there. One catch — working-directory changes that were never committed cannot be recovered, because git never recorded them.

Say this to your agent
I may have lost work. Run git reflog only, show me the last 20 moves of HEAD, and help me work out which one is from before the mistake. Propose a recovery plan and wait for my OK.
A merge conflicted

Open the conflicted file and you will see three markers: <<<<<<<, ======= and >>>>>>>. Delete the markers, keep the content that is right, then git add and git commit. Want out entirely: git merge --abort.

Say this to your agent
The merge conflicted. Do not edit anything yet: list the conflicting files, explain both sides at each spot, and recommend an approach. Once I approve, make the edits, run the tests, and finish the merge commit.
The push was rejected

This is git protecting you: the remote has commits you do not. The right move is fetch, look at the difference, merge or rebase, then push again. Do not reach for --force.

Say this to your agent
My push was rejected. Run git fetch first, tell me which commits the remote has that I do not and which files they touched, then propose how to merge. Force is not allowed.
A secret got committed

Step one is to invalidate the key — go to the platform and rotate it. That matters far more than cleaning the history. Deleting the file is not enough; the old version is still in there. Scrubbing history is a delicate operation, so rotate first and assess after.

Say this to your agent
I think a secret got committed. Do not change anything yet: find which file, which commit, and whether it has been pushed. Tell me where I need to go to revoke that key, then propose a history-cleanup plan for me to evaluate.
Detached HEAD

You are standing on a commit with no branch. To keep the work here: git switch -c a-new-branch. To drop it: git switch main.

Say this to your agent
Git says detached HEAD. Tell me which commit I am on and whether there are unsaved commits here, then give me two options — keep them on a new branch, or go back to main. Wait for me to choose.
Half-finished work and I need to switch tasks

git stash shelves the changes, you go deal with the other thing, then git stash pop brings them back. The sturdier alternative: make a scratch commit on your branch and tidy it up later.

Say this to your agent
I need to switch to something else. Stash my uncommitted changes with a name, tell me the stash number, then switch branches.