diff --git a/01_essentials/04-merging/README.md b/01_essentials/04-merging/README.md index cf151b5..b3c388c 100644 --- a/01_essentials/04-merging/README.md +++ b/01_essentials/04-merging/README.md @@ -4,10 +4,9 @@ In this module, you will: - Understand what merging means in Git -- Merge divergent branches together -- Understand merge commits and their purpose +- Merge a feature branch back into main - Use `git merge` to combine branches -- Visualize merge history with `git log --graph` +- Visualize merged branches with `git log --graph` ## Challenge @@ -19,121 +18,97 @@ 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. +This will create a `challenge/` directory with a Git repository that has a main branch and a feature branch. ### 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. +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'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 +- 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 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` +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` -> **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 +> **That's it!** Merging is how you bring work from one branch into another. -## Key Concepts +## What is Merging? -### What is Merging? +**Merging** is the process of taking changes from one branch and bringing them into another branch. -**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." +Think of it like combining two streams into one river - all the water (code) flows together. -### Divergent Branches +### Before Merging -When two branches have different commits since they split, they are **divergent**: +You have two branches with different work: ``` -main: A---B---C - \ -feature: D---E +main: A---B---C + \ +feature-login: 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 +- Main branch has commits A, B, and C +- Feature-login branch has commits D and E +- They split apart at commit B -### The Merge Commit +### After Merging -When you merge divergent branches, Git creates a special **merge commit**: +You bring the feature branch into main: ``` -Before merge: -main: A---B---C - \ -feature: D---E - -After merge (on main): -main: A---B---C-------M - \ / -feature: D---E---/ +main: A---B---C---M + \ / +feature-login: D-E ``` -**Merge commit (M)** is special because: -- It has **two parent commits**: C and 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 -- 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: +- Git writes a message like "Merge branch 'feature-login'" +You can view the merge commit just like any other commit: +```bash +git show HEAD ``` -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: +Use `git log --graph` to see how branches merged: ```bash git log --oneline --graph --all @@ -152,84 +127,82 @@ git log --oneline --graph --all **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 +- `|` = 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 -### Merging - ```bash -git merge # Merge branch into current branch -git merge --abort # Cancel a merge in progress -``` +# Merging +git merge # Merge a branch into current branch -### Viewing Merge History +# Viewing +git log --oneline --graph # See branch history visually +git log --oneline --graph --all # Include all branches -```bash -git log --oneline --graph # Simple graph view -git log --oneline --graph --all # Show all branches -git log --merges # Show only merge commits -git show # View details of a merge commit -``` - -### Branch Management - -```bash -git branch # List local branches -git branch -a # List all branches (including remote) -git branch -d # Delete a merged branch +# Branch management +git branch # List branches +git switch # Switch to a branch +git branch -d # Delete a branch (after merging) ``` ## Common Questions -### "What if the merge fails?" +### "What if I'm on the wrong branch when I merge?" -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). +Don't worry! The branch you're currently on is the one that receives the changes. -If you see a conflict and want to cancel: +**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 ``` -### "Can I undo a merge?" - -Before you've pushed to remote: -```bash -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: - -```bash -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: +Once you've merged the feature-login branch, verify your solution: ```powershell .\verify.ps1 ``` -The verification script will check that you've successfully merged the feature branch. +The verification script will check that you've successfully merged. ## Need to Start Over? @@ -239,10 +212,18 @@ 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. +**Next module:** Merge Conflicts - Learn what to do when Git can't automatically merge changes. -**Advanced Topic:** In Module 06 (Advanced section), you'll learn about different merge strategies including fast-forward merges and when to use `--no-ff`. +**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 ` +✅ 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! 🎉