git-workshop/01_essentials/04-merging/README.md

Module 04: Merging Branches

Learning Objectives

In this module, you will:

• Understand what merging means in Git
• Merge divergent branches together
• Understand merge commits and their purpose
• Use git merge to combine branches
• Visualize merge history with git log --graph

Challenge

Setup

Run the setup script to create your challenge environment:

.\setup.ps1

This will create a challenge/ directory with a Git repository that has two divergent branches ready to merge.

Your Task

You have two branches that have diverged - both main and feature-login have new commits since they split. Your task is to merge them back together.

Scenario:

• You're working on a team project
• You created a feature-login branch to add login functionality
• While you were working, your teammate added documentation to main
• Now you need to merge your login feature back into main

Steps:

1. Navigate to the challenge directory: cd challenge
2. Check current branch: git branch (should be on main)
3. View the branch structure: git log --oneline --graph --all
4. Merge the feature-login branch: git merge feature-login
5. View the merge result: git log --oneline --graph --all
6. Examine the merge commit: git show HEAD

Important Notes:

• When both branches have new commits, Git creates a merge commit
• The merge commit has TWO parent commits (one from each branch)
• Git will open an editor for you to write a merge commit message
• You can use the default message or customize it
• The --graph option helps visualize how branches merged

Key Concepts

What is Merging?

Merging combines changes from different branches into one branch. When you merge, you're telling Git: "Take all the changes from branch X and incorporate them into my current branch."

Divergent Branches

When two branches have different commits since they split, they are divergent:

main:    A---B---C
              \
feature:       D---E

• Both branches split from commit B
• main has commit C
• feature has commits D and E
• They have diverged - each has unique work

The Merge Commit

When you merge divergent branches, Git creates a special merge commit:

Before merge:
main:    A---B---C
              \
feature:       D---E

After merge (on main):
main:    A---B---C-------M
              \         /
feature:       D---E---/

Merge commit (M) is special because:

• It has two parent commits: C and E
• It represents the point where branches came back together
• It contains the combined changes from both branches

How Git Merges

Git uses a three-way merge algorithm:

1. Common ancestor (B) - Where the branches split
2. Your branch (C) - Latest commit on main
3. Their branch (E) - Latest commit on feature

Git compares all three to figure out what changed on each branch and combines them intelligently.

Understanding Merge Output

When you run git merge feature-login, you'll see:

Merge made by the 'ort' strategy.
 login.py | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)
 create mode 100644 login.py

What this means:

• "Merge made by the 'ort' strategy" - Git used its merge algorithm to combine changes
• The summary shows what files changed in the merge
• A new merge commit was created

The Merge Commit Message

Git will open your editor with a default message:

Merge branch 'feature-login'

# Please enter a commit message to explain why this merge is necessary,
# especially if it merges an updated upstream into a topic branch.

Tips for merge messages:

• The default message is usually fine for simple merges
• For important merges, explain WHY you're merging
• Example: "Merge feature-login - adds user authentication system"

Visualizing Merges

Use git log --graph to see the branch structure:

git log --oneline --graph --all

Example output:

*   a1b2c3d (HEAD -> main) Merge branch 'feature-login'
|\
| * e5f6g7h (feature-login) Implement login validation
| * h8i9j0k Add login form
* | k1l2m3n Update README with setup instructions
|/
* n4o5p6q Initial project structure

Reading the graph:

• * = A commit
• | = Branch line continuing
• / and \ = Branch splitting or merging
• (HEAD -> main) = Current branch position
• The merge commit has two lines coming into it

Useful Commands

Merging

git merge <branch>              # Merge branch into current branch
git merge --abort               # Cancel a merge in progress

Viewing Merge History

git log --oneline --graph       # Simple graph view
git log --oneline --graph --all # Show all branches
git log --merges                # Show only merge commits
git show <commit>               # View details of a merge commit

Branch Management

git branch                      # List local branches
git branch -a                   # List all branches (including remote)
git branch -d <branch>          # Delete a merged branch

Common Questions

"What if the merge fails?"

Sometimes Git can't automatically merge changes (this is called a merge conflict). Don't worry! We'll cover this in the next module (Module 05: Merge Conflicts).

If you see a conflict and want to cancel:

git merge --abort

"Can I undo a merge?"

Before you've pushed to remote:

git reset --hard HEAD~1    # Undo the merge commit

We'll cover more advanced undoing in later modules.

"Should I delete the feature branch after merging?"

It's common practice to delete feature branches after merging:

git branch -d feature-login    # Safe delete (only works if merged)

This cleans up your branch list. The commits are still in the history - the branch pointer is just removed.

"What does 'ort strategy' mean?"

Git uses different merge algorithms:

• ort (default in Git 2.34+) - Newer, faster merge algorithm
• recursive (older) - Traditional merge algorithm

You don't need to worry about this - Git picks the best one automatically!

Verification

Once you've completed the merge, verify your solution:

.\verify.ps1

The verification script will check that you've successfully merged the feature branch.

Need to Start Over?

If you want to reset the challenge and start fresh:

.\reset.ps1

This will remove the challenge directory and run the setup script again, giving you a clean slate.

What's Next?

Now that you understand basic merging, the next module covers Merge Conflicts - what happens when Git can't automatically merge changes and how to resolve them manually.

Advanced Topic: In Module 06 (Advanced section), you'll learn about different merge strategies including fast-forward merges and when to use --no-ff.