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 a feature branch back into main
- Use `git merge` to combine branches
- Visualize merged branches with `git log --graph`

## Challenge

### Setup

Run the setup script to create your challenge environment:

```powershell
.\setup.ps1
```

This will create a `challenge/` directory with a Git repository that has a main branch and a feature branch.

### Your Task

You've been working on a new login feature in a separate branch. Now it's time to merge your work back into the main branch!

**Scenario:**
- You created a `feature-login` branch to add login functionality
- You made some commits on that branch
- Meanwhile, your teammate updated the README on main
- Now you need to bring your login feature back into main

**Steps:**

1. Navigate to the challenge directory: `cd challenge`
2. Check which branch you're on: `git branch`
3. View all branches: `git log --oneline --graph --all`
4. Merge the feature-login branch into main: `git merge feature-login`
5. View the result: `git log --oneline --graph --all`

> **That's it!** Merging is how you bring work from one branch into another.

## What is Merging?

**Merging** is the process of taking changes from one branch and bringing them into another branch.

Think of it like combining two streams into one river - all the water (code) flows together.

### Before Merging

You have two branches with different work:

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

- Main branch has commits A, B, and C
- Feature-login branch has commits D and E
- They split apart at commit B

### After Merging

You bring the feature branch into main:

```
main:         A---B---C---M
                   \   /
feature-login:      D-E
```

- Commit M is a **merge commit** - it combines both branches
- Main now has all the work from both branches
- Your login feature is now part of main!

## How to Merge

Merging is simple - just two steps:

**1. Switch to the branch you want to merge INTO**
```bash
git switch main
```
This is the branch that will receive the changes.

**2. Merge the other branch**
```bash
git merge feature-login
```
This brings changes from feature-login into main.

**That's it!** Git does the work of combining the changes.

## Understanding the Merge Commit

When you merge, Git creates a special commit called a **merge commit**.

**What makes it special?**
- It has TWO parent commits (one from each branch)
- It represents the point where branches came back together
- Git writes a message like "Merge branch 'feature-login'"

You can view the merge commit just like any other commit:
```bash
git show HEAD
```

## Visualizing Merges

Use `git log --graph` to see how branches merged:

```bash
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
- `/` and `\` = Branches splitting or joining
- `(HEAD -> main)` = You are here

The graph shows how the branches split and came back together!

## Useful Commands

```bash
# Merging
git merge <branch-name>         # Merge a branch into current branch

# Viewing
git log --oneline --graph       # See branch history visually
git log --oneline --graph --all # Include all branches

# Branch management
git branch                      # List branches
git switch <branch-name>        # Switch to a branch
git branch -d <branch-name>     # Delete a branch (after merging)
```

## Common Questions

### "What if I'm on the wrong branch when I merge?"

Don't worry! The branch you're currently on is the one that receives the changes.

**Example:**
```bash
git switch main              # Go to main
git merge feature-login      # Bring feature-login INTO main
```

Always switch to the destination branch first!

### "Can I undo a merge?"

Yes! Before you push to a remote:
```bash
git reset --hard HEAD~1
```

This removes the merge commit. (We'll cover this more in later modules)

### "What happens to the feature branch after merging?"

The feature branch still exists! The merge just copies its commits into main.

You can delete it if you're done:
```bash
git branch -d feature-login    # Safe delete (only if merged)
```

The commits are still in history - you're just removing the branch label.

### "What if Git can't merge automatically?"

Sometimes Git needs your help when the same lines were changed in both branches. This is called a **merge conflict**.

Don't worry - we'll learn how to handle conflicts in the next module!

If you encounter a conflict now and want to cancel:
```bash
git merge --abort
```

## Verification

Once you've merged the feature-login branch, verify your solution:

```powershell
.\verify.ps1
```

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

## Need to Start Over?

If you want to reset the challenge and start fresh:

```powershell
.\reset.ps1
```

## What's Next?

**Next module:** Merge Conflicts - Learn what to do when Git can't automatically merge changes.

**Later:** In the advanced modules, you'll learn about different merging strategies and when to use them. For now, understanding basic merging is all you need!

## Quick Summary

✅ **Merging** combines work from one branch into another
✅ Switch to the destination branch, then run `git merge <source-branch>`
✅ Git creates a **merge commit** to record the merge
✅ Use `git log --graph` to visualize how branches merged
✅ The feature branch still exists after merging - you can delete it if you want

That's all there is to basic merging! 🎉