Making a change
Written by a person. Last read by a person on 2026-09-04, 4 days ago. Its facts were checked by the eval suite on 2026-09-07.
You need to change a file and get that change to other people, and you want to understand each step rather than memorize it.
This page assumes you have the three-places model. If commit and push still sound like two words for the same act, read that first; this page will otherwise be a sequence of incantations.
The shape of every change
Whatever you are changing, the shape is the same five moves:
- Start a branch, so your work is separate until you decide otherwise.
- Edit the files.
- Choose what to record together.
- Record it, with a message saying why.
- Send it to GitHub.
Steps three and four look like one step and are not. That separation is the thing beginners find most pointless and experienced people find most useful: it lets you make a mess on your disk and still record a clean, explicable change.
Doing it, three times over
The same task appears below three times. The first has every step explained, the second withdraws the explanations, and the third withdraws most of the commands as well.
Work down them in order. The third one is the only one that tells you anything about whether you have understood it, because reading an explanation and being able to act without it are different abilities and only the second one is any use on a Tuesday afternoon.
Fixing a typo in a file
Change one word in a file and get that change onto GitHub.
Worked through, every step explained
-
1
git switch -c fix-typoⓘStart a branch. A branch is a name for a line of work, so the change you are about to make is separate from what everyone else is doing until you decide otherwise.
-
2
(edit the file in your editor, save it)This is the only step that changes the file on your disk. Saving in your editor is not saving in git, which is the whole confusion this runbook exists to fix.
-
3
git add README.mdⓘChoose what goes in the next commit. You are not saving yet, you are pointing at the changes you want to save together.
-
4
git commit -m "Fix typo in README"Record the chosen changes as one entry in the history, with a note about why. This is on your computer only. Nobody else can see it yet.
-
5
git push -u origin fix-typoⓘSend the branch to GitHub. This is the step that makes it visible to anyone else, and the first one that is hard to take back quietly.
The same task, on your own
Do the whole thing yourself. Hover a line number for a hint.
Example source: data/examples/first-change.yaml, provenance
human. The two faded versions are generated from the first, so they
cannot drift from it. Notes live in
data/annotations/first-change.yaml; each is anchored to the text it explains and
the build fails if an anchor stops resolving.
How this fails
Every runbook should say what it looks like when it goes wrong, in language you can match against what is actually on your screen. Here are the failures that actually happen on this task.
You pushed and nothing appeared on GitHub
What you see. The push command finished without complaint, but the branch is not on the site.
What is usually true. You pushed to a different remote or a different branch name than the one you are looking at, or you are looking at the wrong repository. The push reported success because it did succeed — somewhere else.
What to do. Run git remote -v to see where "origin" actually points, and git branch --show-current to confirm which branch you are on. Compare both against the page you have open.
It refuses to push because the remote has changes
What you see. A message declining the push and mentioning that the remote contains work you do not have locally.
What is usually true. Somebody else pushed to the same branch after you last pulled. This is git protecting you: accepting your push would discard their work.
What to do. Pull first, resolve anything it asks you about, then push. This is a normal event, not a fault, and it happens more often the better a team is working.
You committed to the wrong branch
What you see. Your commit exists, but it is sitting on main or on somebody else's branch.
What is usually true. You forgot step one and started editing on whatever was checked out.
What to do. This is recoverable and common, and it is covered under undoing things. Do not try to fix it by deleting files and starting again — that turns a small tidy-up into a real problem.
Not yours to fix
Some failures are not about you and no amount of care on your part prevents them: the repository is archived or read-only, your access was not granted, a required check is misconfigured, the service is down. The signal is that the same operation fails identically no matter what you change about how you do it.
When you hit one of these, the correct action is to stop and tell someone with administrative access, and to say exactly what you ran and exactly what came back. Continuing to retry is how a five-minute permissions fix becomes an afternoon.