Lesson 3 of 9 · about 15 minutes

Merge and clean up

Bringing a branch home, then throwing away the pointer.

Two kinds of merge

A merge brings another branch's commits into the branch you are on. You always merge into HEAD, so first switch to the branch that should receive the work (usually main), then run git merge <branch>.2

• Fast-forward. If main hasn't moved since the branch started, there's nothing to combine. Git just moves the pointer, "because there is no divergent work to merge together — this is called a 'fast-forward.'"1
• Merge commit. If both branches gained commits, Git does a three-way merge using the two branch tips and their common ancestor. The result "is referred to as a merge commit, and is special in that it has more than one parent."1

git merge --no-ff <branch> means "Create a merge commit in all cases," even when a fast-forward was possible.2 GitHub's default Merge pull request button does exactly this.5 You'll meet it in lesson 4.

Deleting a branch is deleting a pointer

Once a branch is merged, its commits live on in main. The branch is just a leftover label, so delete it with git branch -d <branch>.1 The lowercase -d is the safe version. The branch "must be fully merged," and if it isn't, Git refuses:3

$ git branch -d try-polars
error: the branch 'try-polars' is not fully merged
hint: If you are sure you want to delete it, run 'git branch -D try-polars'

Uppercase -D ("--delete --force") deletes it anyway.3 That's the right move for a failed experiment, such as an agent attempt you've decided to abandon, but it throws those commits away. Read the error before reaching for -D.

Try it: one fast-forward, one merge commit

main has two commits, and add-cleaning is one commit ahead. Watch which tasks move a pointer and which create a new commit.

Compare the two merges in the terminal output: Fast-forward versus Merge made by the 'ort' strategy. Then compare the graph. Only the second merge drew a new node with two incoming lines.

Do it: merge in penguins-lab

1. In penguins-lab, switch to the receiving branch and merge your lesson-2 work:

   $ git switch main
   $ git merge add-cleaning
   Updating 1d28f0e..3ef57a2
   Fast-forward
    clean.py | 5 +++++
    1 file changed, 5 insertions(+)

2. Delete the now-merged branch:

   $ git branch -d add-cleaning
   Deleted branch add-cleaning (was 3ef57a2).

Your first merge conflict

Git can't decide for you when "you changed the same part of the same file differently in the two branches."1 That's a merge conflict. It isn't an error, just a question Git needs you to answer. GitHub has the same rule: the Merge pull request button stays disabled until conflicts are resolved.4 Make one on purpose so it's familiar before an agent hands you one.

1. Branch one: change line 1 of README.md to # Palmer Penguins Analysis, then commit.

   $ git switch -c readme-title
   #   ...edit line 1 of README.md...
   $ git commit -am "Retitle README"
   $ git switch main

2. Branch two, also started from main: change the same line to # Penguin Data Lab, then commit.

   $ git switch -c readme-title-2
   #   ...edit line 1 of README.md...
   $ git commit -am "Rename project in README"
   $ git switch main

3. Merge both. The first fast-forwards and the second collides:

   $ git merge readme-title
   Fast-forward
   $ git merge readme-title-2
   Auto-merging README.md
   CONFLICT (content): Merge conflict in README.md
   Automatic merge failed; fix conflicts and then commit the result.

4. Practise the escape hatch first. git merge --abort tries "to reconstruct the pre-merge state."2 Run it, confirm git status is clean, then run git merge readme-title-2 again.
5. Open README.md. Git has written both versions into the file:

   <<<<<<< HEAD
   # Palmer Penguins Analysis
   =======
   # Penguin Data Lab
   >>>>>>> readme-title-2

   Above ======= is the version from HEAD, the branch you're on. Below it is the branch you're merging in.1 Edit the block until it says what you actually want, for example # Palmer Penguins Data Lab, and delete all three marker lines.

6. Tell Git it's resolved, and finish the merge. "Staging the file marks it as resolved."1

   $ git add README.md
   $ git commit -m "Merge readme-title-2, combine titles"
   $ git branch -d readme-title readme-title-2

Recall the commands

Check yourself

Want more practice before moving on? Paste the branch practice tutor prompt into Claude. It finds your level and drills merges and conflicts in a throwaway repository until you can do them without hints.