The Conflict of Kingdoms

Introduction

"Apprentice, you have learned to open parallel timelines - branches. But what happens when those timelines must converge? When two kingdoms tell the same battle, but with different versions? That is where the merge comes in - the fusion of chronicles. Sometimes, the merge happens naturally. Sometimes, the accounts contradict each other, and it takes an Archivist to reconcile the versions. That is your mission today."

What is a merge?

A merge (fusion) is the operation that reunites two branches into one. It is like gathering the chronicles of two archivists who worked in parallel on different subjects - or sometimes on the same one.

Imagine two chroniclers sent to different kingdoms:

• One heads East and records the history of the Kingdom of the Dawn.
• The other heads West and records the history of the Kingdom of the Dusk.

When they return, their chronicles must be merged into a single great register. If each wrote about different subjects, it is simple. But if they wrote about the same battle with contradictory versions... there is a conflict.

Merging a branch: git merge

To merge a branch into the current branch:

git merge <branch>

git switch main
git merge my-branch

This takes the commits from my-branch and integrates them into main.

Types of merge

The fast-forward - The simple merge

When the target branch (main) has received no new commits since the working branch was created, Git can simply "advance" the main pointer to the last commit of the branch. This is the fast-forward.

Before:
main:        A --- B
                    \
my-branch:           C --- D

After git merge my-branch (from main):
main:        A --- B --- C --- D

No merge commit is created - Git simply moves main forward. This is the simplest case.

The three-way merge

When both branches have evolved since their point of divergence, Git cannot simply advance a pointer. It must combine the changes from both sides. If the changes affect different files or different lines, Git handles it on its own and creates a merge commit:

Before:
main:        A --- B --- E
                    \
my-branch:           C --- D

After git merge my-branch (from main):
main:        A --- B --- E --- M
                    \         /
my-branch:           C --- D

Commit M is a merge commit - it has two parents (E and D). Git created it automatically because the changes did not overlap.

Merge conflicts

When two branches have modified the same lines of the same file, Git cannot decide on its own which version to keep. It stops and asks you to make the call. This is a merge conflict.

Anatomy of a conflict

When a conflict occurs, Git modifies the affected file by inserting conflict markers:

<<<<<<< HEAD
King Aldric won the battle thanks to his cavalry.
=======
King Aldric lost the battle against the enemy archers.
>>>>>>> chroniques-est

Here is what these markers mean:

• <<<<<<< HEAD: start of your version (the current branch)
• =======: separator between the two versions
• >>>>>>> chroniques-est: end of the other branch's version

Resolving a conflict

To resolve a conflict, follow these steps:

1. Open the file containing the conflict in your editor
2. Choose which version to keep, or combine both versions into a coherent narrative
3. Remove all conflict markers (<<<<<<<, =======, >>>>>>>)
4. Save the file
5. Mark the conflict as resolved with git add
6. Create the merge commit with git commit

# After manually editing the file:
git add chroniques.txt
git commit -m "Merge chroniques-est: reconcile the battle accounts"

Abort a merge in progress

If you feel overwhelmed by a conflict and want to go back:

git merge --abort

This aborts the merge and restores everything to the state before. You can try again later when you are ready.

Tips to avoid conflicts

Practical exercise - The Conflict of Kingdoms

Step 1 - Retrieve the archive

git clone archive.bundle le-conflit-des-royaumes
cd le-conflit-des-royaumes

Step 2 - Explore the branches

git branch -a
git log --oneline --all --graph

You should see the main branch and the remote branches origin/chroniques-est and origin/chroniques-ouest. Since the repository was cloned from a bundle, the chroniclers' branches are remote branches - they are referenced with the origin/ prefix.

Step 3 - First merge (no conflict)

First, merge the origin/chroniques-ouest branch into main:

git switch main
git merge origin/chroniques-ouest

This merge should go smoothly - Gareth added his report and wrote his version of the battle. Since main has also evolved on its own, Git will automatically create a merge commit.

Step 4 - Second merge (with conflict!)

Now, merge the origin/chroniques-est branch:

git merge origin/chroniques-est

This time, Git stops with a conflict message! Elowen and Gareth wrote different versions of the same section in chroniques.txt. Git cannot choose on its own.

Step 5 - Resolve the conflict

1. Open chroniques.txt in your text editor
2. Look for the markers <<<<<<<, ======= and >>>>>>>
3. Read both versions of the battle's account
4. Write a narrative that combines both perspectives into a coherent and balanced version - as a good Archivist, you do not take sides!
5. Remove all conflict markers
6. Save the file

Step 6 - Finalize the merge

git add chroniques.txt
git commit -m "Merge chroniques-est: reconcile the battle accounts"

Step 7 - Verify

Run the verification script to validate your quest:

Bash (Linux / macOS / Git Bash on Windows):

bash verifier.sh

PowerShell (Windows):

.\verifier.ps1

The script checks:

1. You are in a Git repository
2. A merge has been performed (merge commit present)
3. No conflict markers remain in the files
4. No merge is in progress (no unresolved conflict)
5. The merge commit has a descriptive message (at least 10 characters)

Command summary