Skip to main content

​
What is Merging?

Merging is the first method to combine work from two different branches. The git merge command creates a special commit that has two unique parents, effectively saying:
“I want to include all the work from this parent over here AND this one over here, and the set of all their parents.”
Merge commits are unique because they have two parent commits instead of one, allowing Git to preserve the complete history of both branches.

​
How Merge Works

​
Creating a Merge Commit

When you merge one branch into another:
  1. Git creates a new commit with two parents
  2. This commit points to both branch tips
  3. The current branch moves forward to this new commit
  4. The merged branch stays where it was

​
Visual Example

Before merge: 
       C3 (main*)
      /
C0-C1
      \
       C2 (bugFix)
After git merge bugFix: 
       C3
      /  \
 C0-C1    C4 (main*)
      \  /
       C2 (bugFix)
Commit C4 has two parents: C3 and C2.

​
The Merging in Git Level

The introductory level teaches merge fundamentals:

​
Level Goal

Create a divergent history and merge it back together:
1

Create and commit on bugFix

git checkout -b bugFix
git commit
Creates branch bugFix with commit C2.
2

Commit on main

git checkout main
git commit
Creates commit C3 on main.
3

Merge bugFix into main

git merge bugFix
Creates merge commit C4 combining both branches.

​
Expected Result

main* --> C4 (merge commit with two parents)
         /  \
       C3    C2 (bugFix)
         \  /
          C1
          |
          C0

​
Merge Direction

​
Merging INTO the Current Branch

The command git merge <branch> always merges INTO the currently checked-out branch: 
git checkout main  # Current: main
git merge bugFix   # Merges bugFix INTO main
The branch you’re merging FROM stays unchanged. Only the current branch (HEAD) moves forward.

​
Completing the Merge

After merging bugFix into main, you might want to do the reverse: State after first merge: 
main* --> C4
         /  \
       C3    C2 (bugFix)
After git checkout bugFix; git merge main: 
main --> C4 (bugFix*)
        /  \
      C3    C2
Since bugFix was an ancestor of main, Git simply moved bugFix forward. This is called a fast-forward merge.

​
Types of Merges

​
Three-Way Merge

When branches have diverged, Git creates a new merge commit: 
       A (branch-a)
      /  \
 C0-C1    M (merge commit)
      \  /
       B (branch-b)
The merge commit M has two parents: A and B.

​
Fast-Forward Merge

When one branch is directly ahead of another: Before: 
main --> C1
         |
         C2 --> C3 (feature*)
After git checkout main; git merge feature: 
main* --> C3
          |
          C2
          |
          C1
No merge commit needed - main just moves forward.

​
Merge in the Visualization

​
Color Blending

Learn Git Branching uses colors to show merge relationships:
  • Each branch has a unique color
  • Commits are colored by which branches contain them
  • After merging, colors blend together
Example:
  • main (blue) + bugFix (orange) = merged commits appear purple
Color blending helps you understand which branches contributed to each commit.

​
Following the Arrows

After a merge, you can follow arrows from the merge commit back through ALL ancestors: 
main* --> C4
         /  \
       C3    C2
         \  /
          C1
Starting at C4, you can reach C3, C2, C1, and C0.

​
Merge Implementation

From the source code, merges create special commit structures: 
{
  id: "C4",
  parents: ["C3", "C2"],  // Two parents!
  rootCommit: false
}

​
Practical Examples

​
Example 1: Feature Integration

1

Develop feature independently

git checkout -b feature
git commit  # C2
git commit  # C3
2

Main progresses meanwhile

git checkout main
git commit  # C4
3

Merge feature when ready

git merge feature  # Creates C5 (merge commit)

​
Example 2: Bug Fix Integration

# Create and fix bug
git checkout -b bugfix
git commit

# Merge into main
git checkout main
git merge bugfix

​
Merge vs. Rebase

Merging preserves the complete history of both branches:

Advantages

  • Preserves exact history
  • Shows when branches were integrated
  • Non-destructive operation
  • Clear branch points

Disadvantages

  • Creates extra merge commits
  • History can become complex
  • Commit graph less linear
  • More commits to navigate
Compare with Rebasing for an alternative approach.

​
Common Merge Patterns

​
Feature Branch Workflow

1. Create feature branch
2. Develop feature (multiple commits)
3. Merge back to main when complete
4. Delete feature branch

​
Release Branch Merges

main (development)
  |
  v
release (testing)
  |
  v  
hotfix (merged back to both)

​
Best Practices

Merge Forward

Regularly merge main into your feature branches to stay updated.

Clean Working Directory

Ensure no uncommitted changes before merging.

Test Before Merging

Verify your branch works before merging into main.

Meaningful Messages

Write clear merge commit messages explaining what was integrated.

​
Understanding Merge Conflicts

While Learn Git Branching doesn’t simulate conflicts, in real Git:

​
When Conflicts Occur

  • Same file modified in both branches
  • Same line changed differently
  • File deleted in one branch, modified in other

​
Resolving Conflicts

git merge feature
# If conflicts occur:
# 1. Edit conflicted files
# 2. Stage resolved files
# 3. Complete merge with commit

​
Advanced Merge Options

​
Merge Without Fast-Forward

Force creation of merge commit even when fast-forward is possible: 
git merge --no-ff feature
Useful to preserve that a feature branch existed.

​
Squash Merge

Combine all branch commits into one: 
git merge --squash feature
Creates a single commit instead of preserving branch history.

​
Merge Commit Messages

Merge commits typically include:
  • Source and destination branches
  • Brief description of what was integrated
  • Any notable changes or decisions
Example: 
Merge branch 'feature-login'

Integrates user authentication system
- OAuth support
- Password reset functionality

​
Verifying Merges

​
Check Branch Contains All Changes

After merging bugFix into main, the main branch now contains:
  • All commits from main’s original history
  • All commits from bugFix
  • All commits both branches shared (common ancestors)

​
Visual Verification

In Learn Git Branching, look for:
  1. Merge commit with two parent arrows
  2. Current branch pointing to merge commit
  3. Color blending showing combined history

​
Common Mistakes

Wrong branch checked out: Always verify you’re on the correct branch before merging. The branch you’re ON will be updated.
Forgetting to commit: You must commit your changes before merging. Git won’t merge with uncommitted changes.
  • Branching - Creating separate lines of development
  • Rebasing - Alternative to merging for linear history
  • Commits - Understanding what merges combine

​
Next Steps

After mastering merge:
  1. Learn rebasing for an alternative integration strategy
  2. Practice resolving complex branch structures
  3. Understand when to use merge vs. rebase
  4. Explore remote branch merging

Build docs developers (and LLMs) love

Get started for freeTalk to us