When things go wrong

The most useful habit: read the message

Most Git "disasters" come with instructions. Git's error messages are unusually helpful: they say what went wrong, and lines starting with hint: or in brackets often give you the exact command to run next. You've already seen it: "Please commit your changes or stash them" in Lesson 4, and "use 'git pull' before pushing again" in Lesson 5.

So before searching the internet, read the whole message, slowly, and run git status. Between them, they explain most situations. Everything in this lesson starts from that.

Set work aside: git stash

In Lesson 4, Git refused to switch branches because your uncommitted changes were in the way, and suggested you "commit your changes or stash them". Committing isn't always right: the work might be half-finished. git stash sets your uncommitted changes aside on a shelf, leaves your folder clean, and lets you bring them back later.

In your git-practice folder, make a branch with a change to ideas.txt, then go back to main and make a different, uncommitted change to the same file:

git switch -c more-notes
echo "- learn git stash" >> ideas.txt
git commit -am "Add git stash to the ideas"
git switch main
echo "- learn git log" >> ideas.txt
git switch more-notes

error: Your local changes to the following files would be overwritten by checkout:
	ideas.txt
Please commit your changes or stash them before you switch branches.

Stash the change instead:

git stash
git status --short

Saved working directory and index state WIP on main: 07b7b15 ...

git status --short shows nothing: your folder is clean, and the change is on the shelf. (WIP means "work in progress".) Now you can switch freely:

git switch more-notes
git switch main

Back on main, take your change off the shelf:

git stash pop
git status --short

 M ideas.txt

Your edit is back, exactly as it was. pop reapplies the most recent stash and removes it from the shelf. A few more you'll use:

• git stash list shows everything on the shelf. You can stash several times; each gets a number, like stash@{0}.
• git stash -u also stashes untracked files. Plain git stash only takes changes to files Git already tracks, so a brand-new file is left behind. If git stash says "No local changes to save" but you know you've made a new file, that's why.
• git stash drop throws away the latest stash, when you've decided you don't need it.

Throw away the practice edit, and delete the branch:

git restore ideas.txt
git branch -D more-notes

Back out of a merge

Lesson 4 showed how to finish a merge conflict. Sometimes you'd rather not: the conflict is bigger than you expected, or you merged the wrong branch. Set up a conflict:

git switch -c clash
echo "- learn git stash" >> todo.txt
git commit -am "Add git stash to the to-do list"
git switch main
echo "- learn git log" >> todo.txt
git commit -am "Add git log to the to-do list"
git merge clash

CONFLICT (content): Merge conflict in todo.txt
Automatic merge failed; fix conflicts and then commit the result.

Now ask Git where you stand:

git status

You have unmerged paths.
  (fix conflicts and run "git commit")
  (use "git merge --abort" to abort the merge)

The answer is right there in brackets. git merge --abort puts everything back exactly as it was before you typed git merge:

git merge --abort
git status --short

Nothing listed: no conflict, no half-merged file, as if the merge never happened. When a merge gets confusing, aborting and starting again calmly is always an option. Delete the practice branch, and push the to-do list commit you made on main, so main matches GitHub again before the next part:

git branch -D clash
git push

Detached HEAD

This message alarms almost everyone the first time. Look at an old commit directly, by going back three commits:

git checkout HEAD~3

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

Nothing is broken. In Lesson 3, HEAD was the "you are here" pin, normally attached to a branch: it points at main, and main points at a commit. Now HEAD points straight at an old commit, with no branch in between. That's all "detached" means. It's a perfectly good way to look at an old version: your files now look exactly as they did three commits ago (cat todo.txt to check).

The one catch is making commits here. A commit always moves the branch HEAD is attached to, but HEAD isn't attached to any branch, so a new commit has nothing holding on to it:

Try it. Make a commit while detached, then go back to main:

echo "an experiment" >> ideas.txt
git commit -am "Experiment on an old commit"
git switch main

Warning: you are leaving 1 commit behind, not connected to
any of your branches:

  88be1c0 Experiment on an old commit

If you want to keep it by creating a new branch, this may be a good time
to do so with:

 git branch <new-branch-name> 88be1c0

Git warns you, and even gives you the fix. So there are two ways out of detached HEAD:

• Just looking? git switch main (or any branch), and you're back.
• Made commits you want to keep? Before leaving, give them a branch: git switch -c experiment. The new branch points at your commits, and you're attached again.

And if you've already left, like you just did, the warning shows the commit's ID, and the reflog from Lesson 3 remembers it too. git branch experiment 88be1c0, with your own ID, rescues it. (This one was only practice, so you can leave it.)

Committed on the wrong branch

A very common one: you meant to start a branch, forgot, and committed straight onto main.

echo "- learn branches properly" >> todo.txt
git commit -am "Start a new idea"
git status

On branch main
Your branch is ahead of 'origin/main' by 1 commit.

You haven't pushed yet, so this is easy to fix. First, put a branch label on the commit, so it's safe:

git branch new-idea

git branch without switch creates the branch but keeps you on main. Now move main back one commit, to where it was:

git reset --hard HEAD~1
git status

On branch main
Your branch is up to date with 'origin/main'.

main is back to matching GitHub, and the commit lives on new-idea, right where it belongs:

git switch new-idea
git log --oneline -1

The order matters: branch first, then reset. The branch is what keeps the commit safe while you move main. And this only applies before you push: once a commit on main is on GitHub, revert it instead (Lesson 3). Clean up with git switch main and git branch -D new-idea.

If you commit a secret

Lesson 1 warned that a committed password stays in the history even after you delete the file. If it happens:

1. Treat the secret as leaked, and change it. Make a new password or API key, and turn off the old one. This is the step that actually protects you, and it's the one people skip.
2. If you haven't pushed yet, remove it from the commit: take it out of the file, add the file to .gitignore (Lesson 2), and git commit --amend (Lesson 3).
3. If you have pushed, removing it from the history takes special tools, like git filter-repo, and rewrites shared history, with all the trouble from Lesson 3. That's why step 1 comes first: once a secret has been pushed, assume someone has it.

GitHub also scans pushes for common kinds of secrets, like API keys, and can block a push that contains one. Treat that as a safety net, not a plan.

Break it on purpose

Stash a new file the wrong way. Create a new file, and stash without -u:

echo "a brand-new note" > notes.txt
git stash

No local changes to save

Git saved nothing, because notes.txt is untracked: plain git stash ignores it. The file is still in your folder (ls), but anyone who expected it to be safely stashed would be surprised. Use -u:

git stash -u
ls
git stash pop
ls

The first ls shows notes.txt is gone, safely on the shelf. After pop, it's back. Delete it with rm notes.txt (rm removes a file, permanently, with no undo).

You've finished Git basics

That's the end of the track. You can save history, undo mistakes, work on branches, collaborate through GitHub with pull requests, and get yourself out of the usual messes. For the next step, the CI/CD track covers what happens automatically when you push: tests, builds and deploys.

Check yourself

Key terms

• git stash / git stash pop: set uncommitted changes aside / bring the latest set back. -u includes untracked files.
• git merge --abort: cancels a merge in progress, putting everything back as it was.
• Detached HEAD: HEAD pointing straight at a commit instead of a branch.
• git checkout commit: an older command that, given a commit, moves you into detached HEAD to look at it.
• git branch name: creates a branch at the current commit without switching to it.
• Autostash: Git stashing and restoring your changes by itself, for example during git pull.
• Rotate a secret: replace a password or key with a new one, and turn off the old one.

Go deeper

• Chapter 7.3 of Pro Git (opens in a new tab) covers stashing and cleaning in more depth.
• Dangit, Git!?! (opens in a new tab) is a short, famous list of common Git mistakes and exactly how to fix each one.
• GitHub's guide to removing sensitive data from a repository (opens in a new tab).