Fast-forward merge in Git - Commands & Configuration

Introduction

When you work on a feature branch and want to add your changes back to the main branch, a fast-forward merge moves the main branch pointer forward without creating a new commit. This keeps the history simple and linear.

When your feature branch is directly ahead of the main branch with no new commits on main.

When you want to keep the commit history clean and linear without extra merge commits.

When you finished a small fix or feature and want to quickly update the main branch.

When you want to avoid unnecessary merge commits that clutter the history.

When you want to update your local main branch to match the remote after pulling.

Commands

Switch to the main branch where you want to merge the changes.

Terminal

git checkout main

Expected Output

Switched to branch 'main'

Merge the feature-branch into main. If main has no new commits, this will perform a fast-forward merge moving main forward.

Terminal

git merge feature-branch

Expected Output

Updating 1a2b3c4..5d6e7f8

Fast-forward

 file.txt | 2 ++

 1 file changed, 2 insertions(+)

Show the recent commit history with a graph to verify the fast-forward merge happened and history is linear.

Terminal

git log --oneline --graph --decorate -5

Expected Output

* 5d6e7f8 (HEAD -> main) Add new feature

* 1a2b3c4 Initial commit

Key Concept

If the main branch has no new commits, merging a feature branch just moves the main pointer forward without creating a new merge commit.

Common Mistakes

Trying to fast-forward merge when the main branch has new commits.

Git cannot fast-forward because the histories have diverged, so it creates a merge commit instead.

Either rebase your feature branch onto main before merging or accept the merge commit.

Not switching to the main branch before merging.

Merging from the wrong branch will not update main and can cause confusion.

Always checkout the branch you want to update before running git merge.

Summary

Switch to the main branch with git checkout main.

Run git merge feature-branch to merge changes; if possible, this will fast-forward main.

Use git log --oneline --graph to verify the merge was fast-forward and history is linear.