249 lines
6.7 KiB
Markdown
249 lines
6.7 KiB
Markdown
# 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:
|
|
|
|
```powershell
|
|
.\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:
|
|
|
|
```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 continuing
|
|
- `/` and `\` = Branch splitting or merging
|
|
- `(HEAD -> main)` = Current branch position
|
|
- The merge commit has two lines coming into it
|
|
|
|
## Useful Commands
|
|
|
|
### Merging
|
|
|
|
```bash
|
|
git merge <branch> # Merge branch into current branch
|
|
git merge --abort # Cancel a merge in progress
|
|
```
|
|
|
|
### Viewing Merge History
|
|
|
|
```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 <commit> # 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 <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:
|
|
```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:
|
|
|
|
```powershell
|
|
.\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:
|
|
|
|
```powershell
|
|
.\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`.
|