From c3d9d3337cad895bcc101b7730e5f85ff18656f0 Mon Sep 17 00:00:00 2001
From: Bjarke Sporring <work.bjarke@gmail.com>
Date: Thu, 15 Jan 2026 13:47:30 +0100
Subject: [PATCH] refactor: add better instructions for branching and merging

---
 .../03-branching-and-merging/README.md        | 94 +++++++++----------
 1 file changed, 42 insertions(+), 52 deletions(-)

diff --git a/01-essentials/03-branching-and-merging/README.md b/01-essentials/03-branching-and-merging/README.md
index f40ef70..18c8f97 100644
--- a/01-essentials/03-branching-and-merging/README.md
+++ b/01-essentials/03-branching-and-merging/README.md
@@ -14,7 +14,7 @@ By the end of this module, you will:
 
 Create the challenge environment:
 
-```bash
+```pwsh
 .\setup.ps1
 ```
 
@@ -39,7 +39,7 @@ This creates a repository with a realistic project history showing multiple merg
 
 First, explore the existing history to see what merging looks like:
 
-```bash
+```pwsh
 cd challenge
 git log --oneline --graph --all
 ```
@@ -55,7 +55,7 @@ You'll see a visual graph showing:
 - Find the merge commits (they have two parent lines converging)
 
 **Explore the branches:**
-```bash
+```pwsh
 # See all branches
 git branch --all
 
@@ -66,7 +66,7 @@ git ls-tree --name-only main
 ```
 
 **View specific merges:**
-```bash
+```pwsh
 # See all merge commits
 git log --merges --oneline
 
@@ -78,7 +78,7 @@ git show <merge-commit-hash>
 
 Now practice creating your own branch:
 
-```bash
+```pwsh
 # Create and switch to a new branch
 git switch -c my-feature
 
@@ -92,50 +92,45 @@ The `*` shows which branch you're currently on.
 
 Add some changes to your branch:
 
-```bash
-# Create a new file or modify an existing one
-echo "# My Feature" > my-feature.md
-
+Create or edit a file then add and commit
+```pwsh
+# Create a new file or modify an existing one.
 # Stage and commit
+git status # see the files that are untracked or changed
 git add .
 git commit -m "Add my feature"
 
+# Create or edit another file
 # Make another commit
-echo "More details" >> my-feature.md
+git status # see the files that are untracked or changed
 git add .
 git commit -m "Expand feature documentation"
+
+git log --oneline --graph --all # see how your branch is moving forward from main
 ```
 
 **Important:** Changes on your branch don't affect main!
 
-```bash
-# Switch to main
-git switch main
-
-# Notice your my-feature.md doesn't exist here
-ls
-
-# Switch back to your branch
-git switch my-feature
-
-# Now it exists again!
-ls
-```
+1. Change back to the `main` branch `git switch main`
+2. Check the changes you committed before. You'll notice that they're gone!
+3. Now edit a file or create a new file and add it and commit it on your `main` branch (hint: `git add .`, `git commit -m`)
+    - This way we create diverging branches. The `main` branch has changes as well as your new `my-feature` branch.
+    - Run `git log --oneline --graph --all` to see how the tree is looking
+4. Switch back to your branch `git switch my-feature` 
+5. The changes from the `main` branch are now gone. Check the changes you committed before. You'll notive they're back!
 
 ### Part 4: Merge Your Branch
 
 Bring your work into main:
 
-```bash
-# Switch to the branch you want to merge INTO
-git switch main
-
-# Merge your feature branch
-git merge my-feature
-
-# View the result
-git log --oneline --graph --all
-```
+1. Go back to the main branch `git switch main`
+2. Run a `git log --oneline --graph --all` to see that the `HEAD` is on your `main` branch
+3. It might be wise to first ensure that we're using Visual Studio Code to handle merge messages. If you haven't already set `git config --global core.editor "code --wait"` this sets Visual Studio Code to be the default editor for anything Git related.
+4. Let's merge the recently created branch `git merge my-feature`
+5. Visual Studio Code should open with a commit message. In order to solidify the commit simply close the window. That tells Git that the commit message has been written and the change should be committed.
+6. Now run `git log --oneline --graph --all` and see your changes merge into the `main` branch!
+7. Now let's clean up a bit, run `git branch -d my-feature` to remove the recently merged branch.
+    - If you hadn't merged the branch first this command would fail as Git will warn you that you have changes not merged into the `main` branch
 
 You should see your feature branch merged into main!
 
@@ -143,7 +138,7 @@ You should see your feature branch merged into main!
 
 Create additional branches to practice:
 
-```bash
+```pwsh
 # Create another feature
 git switch -c another-feature
 
@@ -156,7 +151,7 @@ git merge another-feature
 ```
 
 **Verify your work:**
-```bash
+```pwsh
 # From the module directory (not inside challenge/)
 .\verify.ps1
 ```
@@ -182,7 +177,7 @@ my-feature:     D---E
 
 `HEAD` points to your current branch. It's Git's way of saying "you are here."
 
-```bash
+```pwsh
 # HEAD points to main
 git switch main
 
@@ -226,7 +221,7 @@ If main hasn't changed, Git just moves the pointer forward. No merge commit need
 
 ### Branching
 
-```bash
+```pwsh
 # List all branches (* shows current branch)
 git branch
 
@@ -251,7 +246,7 @@ git branch -D feature-name
 
 ### Merging
 
-```bash
+```pwsh
 # Merge a branch into your current branch
 git merge branch-name
 
@@ -264,7 +259,7 @@ git merge --no-ff branch-name
 
 ### Viewing History
 
-```bash
+```pwsh
 # Visual branch graph
 git log --oneline --graph --all
 
@@ -285,7 +280,7 @@ git branch --no-merged main
 
 ### Creating a Feature
 
-```bash
+```pwsh
 # Start from main
 git switch main
 
@@ -305,7 +300,7 @@ git commit -m "Improve awesome feature"
 
 ### Merging a Feature
 
-```bash
+```pwsh
 # Switch to main
 git switch main
 
@@ -318,7 +313,7 @@ git branch -d feature-awesome
 
 ### Keeping Main Updated While Working
 
-```bash
+```pwsh
 # You're on feature-awesome
 git switch feature-awesome
 
@@ -337,7 +332,7 @@ git pull origin main
 
 ### "I'm on the wrong branch!"
 
-```bash
+```pwsh
 # Switch to the correct branch
 git switch correct-branch
 
@@ -349,7 +344,7 @@ git branch
 
 Don't panic! You can move commits to another branch:
 
-```bash
+```pwsh
 # Create the correct branch from current state
 git branch correct-branch
 
@@ -363,7 +358,7 @@ git switch correct-branch
 
 ### "The merge created unexpected results!"
 
-```bash
+```pwsh
 # Undo the merge
 git merge --abort
 
@@ -373,7 +368,7 @@ git reset --hard HEAD~1
 
 ### "I want to see what changed in a merge!"
 
-```bash
+```pwsh
 # Show the merge commit
 git show <merge-commit-hash>
 
@@ -384,15 +379,10 @@ git diff main..feature-branch
 ## Tips for Success
 
 💡 **Branch often** - Branches are cheap! Create one for each feature or experiment.
-
 💡 **Commit before switching** - Always commit (or stash) changes before switching branches.
-
 💡 **Keep branches focused** - One feature per branch makes merging easier.
-
 💡 **Delete merged branches** - Clean up with `git branch -d branch-name` after merging.
-
 💡 **Use descriptive names** - `feature-login` is better than `stuff` or `branch1`.
-
 💡 **Visualize often** - Run `git log --oneline --graph --all` to understand your history.
 
 ## What You've Learned
@@ -412,7 +402,7 @@ After completing this module, you understand:
 Ready to continue? The next module covers **merge conflicts** - what happens when Git can't automatically merge changes.
 
 To start over:
-```bash
+```pwsh
 .\reset.ps1
 .\setup.ps1
 ```