Merging Branches

Merging is how the work done on one branch gets incorporated into another. You develop a feature on a branch, confirm it is working, then merge it into main so the feature becomes part of the main line of history.

The merge workflow

Merging always happens into the branch you are currently on. The typical workflow is:

1. Finish work on the feature branch
2. Switch to the target branch (usually main)
3. Run git merge <branch-to-merge-in>

git switch main
git merge feature/add-river-canyon

Fast-forward merges

When main has not received any new commits since the feature branch was created, the merge is a fast-forward. There is no divergent history to reconcile — Git simply moves the main pointer forward to the feature branch’s latest commit.

Before merge:

* c2a1d08 (feature/add-river-canyon) Add River Canyon trail description
* b7e9d03 (HEAD -> main) Add difficulty and gear notes

After a fast-forward merge:

* c2a1d08 (HEAD -> main, feature/add-river-canyon) Add River Canyon trail description
* b7e9d03 Add difficulty and gear notes

main simply moved to where feature/add-river-canyon already was. No merge commit was created. The history is linear.

Git tells you when this happens:

Updating b7e9d03..c2a1d08
Fast-forward
 river-canyon.txt | 1 +
 1 file changed, 1 insertion(+)

Merge commits

When both branches have commits since they diverged — for example, you added a hotfix to main while the feature was in development — Git cannot fast-forward. It creates a merge commit with two parents: one from each branch.

git merge feature/tour-descriptions

Output:

Merge made by the 'ort' strategy.
 pine-ridge.txt | 1 +
 1 file changed, 1 insertion(+)

A merge commit appears in history with two parent pointers:

*   d4f2a01 (HEAD -> main) Merge branch 'feature/tour-descriptions'
|\
| * c2a1d08 (feature/tour-descriptions) Add viewpoint note to Pine Ridge
* | e9b3c07 Fix typo in summit challenge notes
|/
* b7e9d03 Add difficulty and gear notes

The |\ and |/ in the graph show where the branches diverged and rejoined.

Merge conflicts

A merge conflict occurs when the same part of the same file was changed on both branches. Git cannot automatically decide which version to use, so it stops the merge and asks you to resolve the conflict manually.

You will see something like:

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

Open pine-ridge.txt. Git marks the conflict:

<<<<<<< HEAD
Best time to visit: spring or fall
=======
Best time to visit: late spring after snow melts
>>>>>>> feature/tour-descriptions

• Everything between <<<<<<< HEAD and ======= is the version from your current branch (main)
• Everything between ======= and >>>>>>> feature/tour-descriptions is from the incoming branch

To resolve the conflict:

1. Edit the file to keep what you want (delete the conflict markers and unwanted content)
2. Save the file
3. Stage the resolved file: git add pine-ridge.txt
4. Complete the merge: git commit

Git opens your editor with a pre-filled merge commit message. Accept or edit it, then save and close.

After resolving, the file contains exactly what you wrote — no conflict markers, no duplicated content.

Aborting a merge

If you want to cancel a merge that has conflicts and go back to the state before you ran git merge:

git merge --abort

This restores your working tree and staging area to the pre-merge state.

Exercise

1. Make sure you are on main in your git-practice folder and that your feature/add-river-canyon branch has at least one commit.

2. Merge the feature branch:

git switch main
git merge feature/add-river-canyon

3. Run git log --oneline --graph --all and note whether the merge was a fast-forward or produced a merge commit.

4. Create a conflict deliberately: switch to a new branch, edit the first line of pine-ridge.txt, commit. Then switch back to main, edit the same first line differently, commit. Now merge the branch. Read the conflict markers and resolve them.

5. Stage the resolved file and complete the merge commit.

Recap

• Merge always happens into your current branch. Switch to main, then git merge <branch>.
• A fast-forward merge occurs when main has not diverged from the feature branch — Git simply moves the pointer forward. No merge commit.
• A merge commit occurs when both branches have commits since they diverged — Git creates a new commit with two parents.
• A merge conflict occurs when the same region of the same file was changed on both branches. Resolve it by editing the conflict markers, staging, and committing.
• git merge --abort cancels an in-progress merge and restores the pre-merge state.

The next lesson covers branch naming conventions — how teams structure their branch names to make repositories understandable at a glance.