Branches, Merging and Conflicts

In lesson 0 you saw that a branch is a file with one hash. This lesson uses that fact. We create branches, merge them in the two ways Git has (fast-forward and merge commit), then make a real conflict on purpose and fix it step by step. You will also learn the one command that gets you out when you panic: git merge --abort.

Words used in this lesson

• A branch is a label that points to a commit. It moves forward when you commit.
• main is the usual name of the main branch. Some old projects use master. The name is only a convention.
• To merge is to join the work of another branch into the one you are on.
• A fast-forward is a merge where the current branch just moves forward to the other branch's tip, because nothing happened on the current branch in the meantime. No new commit is made.
• A merge commit is a new commit with two parents. It records that two lines of work were joined.
• A conflict happens when both branches changed the same lines (or one deleted what the other changed) and Git cannot choose.
• Conflict markers are the lines <<<<<<<, ======= and >>>>>>> that Git writes into the file to show both versions.
• The merge base is the latest commit that both branches have in common. Git compares each side with it.
• A topic branch is a short-lived branch for one feature or fix.

Create and switch branches

git -c init.defaultBranch=main init -q site && cd siteprintf '<h1>My Site</h1>\n<p>Welcome</p>\n' > index.htmlprintf 'Title: My Site\nColor: blue\nLanguage: en\n' > config.txtgit add . && git commit -q -m "Initial site"git branch

* main

The star marks the branch you are on. Make a new branch and switch to it in one step:

git switch -c add-footerprintf '<footer>Contact us</footer>\n' >> index.htmlgit commit -qam "Add footer"git log --oneline --graph --decorate --all

Switched to a new branch 'add-footer'* 539ccc5 (HEAD -> add-footer) Add footer* b4f8188 (main) Initial site

git switch is the modern command for changing branch. You will also meet git checkout <branch>, which does the same and much more (it is older and more confusing, which is why switch and restore were added). git switch -c name creates the branch. Use git switch - to jump back to the previous branch.

main still points to b4f8188. The footer exists only on add-footer. If you switch back, the footer line disappears from index.html, because Git rewrites your files to match the branch.

Merge 1: fast-forward

Switch to main and merge:

git switch maingit merge add-footergit log --oneline --graph --decorate --all

Switched to branch 'main'Updating b4f8188..539ccc5Fast-forward index.html | 1 + 1 file changed, 1 insertion(+)* 539ccc5 (HEAD -> main, add-footer) Add footer* b4f8188 (main) Initial site

The last two lines show that main and add-footer now point to the same commit. Git said Fast-forward. Nobody had committed on main, so Git only moved the main label forward. No new commit was created, and the history is a straight line:

before:   b4f8188 <- 539ccc5          after:   b4f8188 <- 539ccc5             ^           ^                                    ^           main     add-footer                       main, add-footer

Merge 2: a merge commit

Now both branches get new work. I branch off for an about page, then also commit on main:

git switch -c about-pageecho "<p>About us</p>" > about.html && git add about.html && git commit -qm "Add about page"git switch mainprintf 'Contact: hi@example.com\n' >> config.txt && git commit -qam "Add contact to config"git log --oneline --graph --decorate --all

* 5f295d8 (about-page) Add about page| * bd2a10a (HEAD -> main) Add contact to config|/  * 539ccc5 (add-footer) Add footer* b4f8188 Initial site

The history has forked. The two lines share 539ccc5 (the merge base). A fast-forward is impossible, because main has a commit that about-page does not. Merge:

git merge about-page -m "Merge branch 'about-page'"git log --oneline --graph --decorate --all

Merge made by the 'ort' strategy. about.html | 1 + 1 file changed, 1 insertion(+) create mode 100644 about.html*   ab4a3b0 (HEAD -> main) Merge branch 'about-page'|\  | * 5f295d8 (about-page) Add about page* | bd2a10a Add contact to config|/  * 539ccc5 (add-footer) Add footer* b4f8188 Initial site

Git made a new commit, ab4a3b0, with two parents. It joined the changes automatically, because they touched different files. The word ort is the name of Git's default merge algorithm in this version. You do not need to choose it.

If you want a merge commit even when a fast-forward is possible (some teams like to keep a record that a feature branch existed), use git merge --no-ff. If you want to refuse anything but a fast-forward, use --ff-only. I ran --no-ff on a small branch nf; Git printed Merge made by the 'ort' strategy. and the log showed the diamond shape.

Clean up merged branches

A branch label is cheap, but old ones create clutter. Check which are merged and delete them:

git branch --mergedgit branch -d about-page add-footergit branch

  about-page  add-footer* mainDeleted branch about-page (was 5f295d8).Deleted branch add-footer (was 539ccc5).* main

-d (lowercase) deletes only if the branch is fully merged. This is a safety check. I tried it on an unmerged branch experiment:

error: the branch 'experiment' is not fully merged.If you are sure you want to delete it, run 'git branch -D experiment'

-D (capital) forces it. Deleting a branch deletes the label, not the commits. The commits stay in the repository for a while and can be recovered with the reflog (lesson 4).

A real conflict, step by step

A conflict needs two branches that change the same line differently. In config.txt the line is Color: blue. One branch will make it green. main will make it red.

git switch -c blue-to-greensed -i 's/Color: blue/Color: green/' config.txtgit commit -qam "Change color to green"git switch mainsed -i 's/Color: blue/Color: red/' config.txtgit commit -qam "Change color to red"

Both branches now changed line 2 of config.txt away from blue, to different values. Merge:

git merge blue-to-green

Auto-merging config.txtCONFLICT (content): Merge conflict in config.txtAutomatic merge failed; fix conflicts and then commit the result.

Git stopped half-way. Do not panic. Nothing is lost. Ask what state we are in:

git status

On branch mainYou have unmerged paths.  (fix conflicts and run "git commit")  (use "git merge --abort" to abort the merge)Unmerged paths:  (use "git add <file>..." to mark resolution)	both modified:   config.txtno changes added to commit (use "git add" and/or "git commit -a")

Git tells you exactly what to do: fix the file, git add it, then git commit, or abort. Open the file:

cat config.txt

Title: My Site<<<<<<< HEADColor: red=======Color: green>>>>>>> blue-to-greenLanguage: enContact: hi@example.com

How to read it:

• Everything outside the markers merged fine (Title, Language, Contact).
• Between <<<<<<< HEAD and ======= is our side: the branch we are on (main) says Color: red.
• Between ======= and >>>>>>> blue-to-green is their side: the other branch says Color: green.

Git cannot know which colour you want. Maybe red, maybe green, maybe orange. You decide. A few helpers:

git diff                       # a special 3-way diff of the conflictgit log --oneline --merge      # commits from both sides that touch the conflict

7382a1e Change color to redfb24269 Change color to green

Option A: abort and think

If you are not ready, go back to the state before the merge:

git merge --abortgit statuscat config.txt

On branch mainnothing to commit, working tree cleanTitle: My SiteColor: redLanguage: enContact: hi@example.com

Everything is as it was before git merge. This is the safest way out. Use it freely.

Option B: resolve it

I run the same merge again, then edit the file. Resolving means producing the final text you want, with all the marker lines removed. I decide on green:

git merge blue-to-green          # conflicts again, same as before# edit config.txt so that it reads:cat config.txt

Title: My SiteColor: greenLanguage: enContact: hi@example.com

I wrote the file with an editor (in the run I replaced the whole file with printf). Then tell Git the conflict is resolved by adding the file, and check:

git add config.txtgit status

On branch mainAll conflicts fixed but you are still merging.  (use "git commit" to conclude merge)Changes to be committed:	modified:   config.txt

Finish the merge. If you run git commit without -m, Git opens an editor with a ready message. I give one directly:

git commit -m "Merge blue-to-green: use green"git log --oneline --graph --decorate -6

[main f154fa8] Merge blue-to-green: use green*   f154fa8 (HEAD -> main) Merge blue-to-green: use green|\  | * fb24269 (blue-to-green) Change color to green* | 7382a1e Change color to red|/  *   ab4a3b0 Merge branch 'about-page'|\  | * 5f295d8 Add about page* | bd2a10a Add contact to config|/  

Done. The merge commit f154fa8 has parents 7382a1e (red) and fb24269 (green), and its content is your decision.

The checklist for any conflict

1. Read git status. It lists the files with both modified.
2. Open each file. Search for <<<<<<<.
3. Decide the final text. Sometimes it is one side, sometimes the other, sometimes a mix. Delete all three marker lines.
4. Run the project's tests or at least start the app. A conflict can be resolved into code that does not work.
5. git add file, then git commit.
6. If it goes wrong: git merge --abort.

See the original too: diff3

By default Git shows only the two sides. With git config merge.conflictStyle diff3 it also shows the common ancestor between ||||||| and =======. I tried it on a new conflict:

<<<<<<< HEADColor: gray||||||| f154fa8Color: green=======Color: pink>>>>>>> a1

Now you can see that both sides changed green (the original), one to gray and one to pink. That often makes the right answer obvious. It is a good setting to turn on once for all repositories.

Keep conflicts small

• Merge often. A branch that lives for two days has few conflicts. One that lives for two months has many.
• Pull the latest main into your branch regularly (lesson 3).
• Keep commits and files focused. If everyone edits one giant file, everyone conflicts.
• Format code with a shared formatter so that "conflicts" are not just whitespace.
• Tell your team before you rename or move many files.

Git can also record how you solved a conflict and replay it (git rerere), but that is an advanced topic and I did not run it here.

Try it

Use a new empty repository.

1. Make a commit with a file menu.txt containing three lines: Soup, Salad, Pasta. Create a branch spicy, change Soup to Hot soup, commit. Switch to main and merge spicy. Is it a fast-forward? Check with git log --oneline --graph.
2. From main, create dessert, add a line Cake, commit. On main, change Pasta to Pizza, commit. Merge dessert. Do you get a merge commit? Why?
3. Make a conflict: on branch a change Salad to Green salad; on branch b (from the same starting commit) change Salad to Caesar salad. Merge a into main, then b into main. What do you see?
4. Abort that merge. Check that git status is clean.
5. Do the merge again and resolve it by keeping Caesar salad. Commit.
6. Try git branch -d on a branch with a commit that was never merged. What happens, and what is the option to force it?

Answers

1. Yes. main had no new commits, so Git only moves the label: you see Fast-forward and a straight line.
2. Yes. Both branches have a new commit since they split, so a fast-forward is impossible. Git creates a commit with two parents. The two edits touched different lines, so there is no conflict.
3. The first merge (a) is a fast-forward or clean merge. The second (b) stops with CONFLICT (content): Merge conflict in menu.txt, because both changed the Salad line from the same base.
4. git merge --abort returns to the state before the merge. git status shows nothing to commit, working tree clean.
5. Run the merge again, edit menu.txt to the one line Caesar salad, remove the markers, then git add menu.txt and git commit.
6. error: the branch '...' is not fully merged. Use git branch -D name to force it. The commits remain recoverable through the reflog for a time.

Interview questions

Key takeaways

• A branch is a label. git switch -c name creates one and moves you onto it.
• If the current branch did not move, merge is a fast-forward (just a label move). Otherwise Git makes a merge commit with two parents.
• A conflict means both sides changed the same lines. Git writes markers and waits for you.
• Fix: edit the file to the final text, remove the markers, git add, git commit. Escape: git merge --abort.
• git branch -d is the safe delete, -D forces it.
• Turn on merge.conflictStyle diff3 to see the original as well.
• A merge with no conflict can still break the build. Run the tests.

What's next

Next: Remotes, pull requests and code review, Lesson 3. Everything so far was on one computer. Next you share work: clone, push, fetch, pull, forks and the pull request flow on GitHub. Practise now: make a conflict on purpose three times until the markers feel boring.