Reviewing, applying and reverting changes
Reading a diff properly, using codex review on uncommitted work, applying output deliberately, keeping commits small, and reverting cleanly when a run goes wrong.
Reading the diff
# 1. scope before content: which files moved at all?
git diff --stat
git status --short
# 2. look at deletions first: what was removed is where silent damage hides
git diff --diff-filter=D --name-only # deleted files
git diff -U0 | grep '^-' | grep -v '^---' # every removed line, compactly
# 3. test files get their own pass
git diff -- tests/
# 4. dependency manifests get their own pass
git diff -- package.json package-lock.json requirements.txt pyproject.toml uv.lock
# 5. then read the whole patch in one sitting
git diff --color=never | less -R| Check | Catches | Command |
|---|---|---|
| File list | Unrelated edits and reformatting | git diff --stat |
| Removed lines | Weakened assertions, deleted validation | git diff -U0 filtered |
| Test diff | Skipped, loosened or deleted tests | git diff -- tests/ |
| Manifest diff | A new dependency nobody approved | git diff -- '*lock*' |
| Config diff | CI, Dockerfile, permissions changes | git diff -- .github Dockerfile |
| Generated files | Committed build output or lockfile churn | git status --short |
- Read deletions before additions. An agent that has achieved its goal by removing a check produces a small, plausible diff that all the tests pass.
- Treat a change to a test file as a change to the contract of the system. If an assertion was adjusted, ask whether the behaviour or the expectation was wrong.
- Check the total line count against your own limit. If a review is too large to read carefully, request a smaller change instead of skimming it.
- Look for a reverted test marker: a skip, an xfail or a commented-out block is the most common way a failing test becomes a passing one.
Using codex review
# review the working tree before committing anything
codex review
# ask for a focused review of a specific concern
codex review "check that every new database column has a reversible migration, \
and that no endpoint returns 500 on missing input"
# review a branch against its merge base
git switch -c agent/orders-pagination
git merge-base HEAD main
codex review --base "$(git merge-base HEAD main)"
# a review is advisory: it is a second reader, not a gate
git diff --stat && codex review- A review run is another probabilistic process. It finds real problems and it invents plausible ones, so treat its output as a list of things to check rather than a verdict.
- Review the merged result, not the agent's earlier summary: what matters is the code that exists now, with every change applied.
- Run the review before committing. Once something is committed, the temptation is to keep it and fix forward rather than fix properly.
- Ask for a specific concern. A generic "review this" returns generic commentary; a targeted question returns something you can act on.
Applying and reverting
# stage deliberately, hunk by hunk, so unrelated changes never enter the commit
git add -p
git diff --cached --stat
git commit -m "Add cursor pagination to the orders API"
# keep commits small: one idea, one commit, one revertable unit
git log --oneline -5
# revert the whole run: discard everything not committed
git restore .
git clean -fd # remove new untracked files the agent created
# revert one commit that is already in history
git revert --no-edit <sha>
# if a run is tangled with your own work, save the useful part first
git stash push -m "useful work" -- src/useful.py
git restore . && git clean -fd
git stash pop
# last resort, and only on a branch you own
git reset --hard origin/agent/orders-pagination⚠️
Before any destructive command, confirm there is nothing you need on the floor.
git clean -fd deletes untracked files with no undo, and git reset --hard discards uncommitted work. Check git status and git stash list first, and never run either against a branch someone else is using.FAQ
The change is nearly right. Should I fix it by hand?
If the fix is smaller than the diff, fix it by hand and commit. Asking for another run risks rewriting the parts that were already correct and multiplies review effort.
How do I review a very large agent change?
Ask for a smaller slice. A change nobody can read carefully is a change nobody has reviewed, regardless of how many tests pass. Split it into independent commits and review them in sequence.
Related
Reviewing output and its limits Using Codex in a real workflow
Last refreshed 2026-09-18.