Use this tutorial when your branch is out of date with the master branch

git-rebase.md

git-rebase

---

This guide explains how to safely update a feature branch from master in Git, using either merge or rebase, before creating or completing a pull request. Use this tutorial when your branch is out of date with the master branch, or when modifications are frequently made to the master branch during this time period.

Understanding ahead and behind

GitHub often shows messages like:

• "This branch is 20 commits ahead of master and 1 commit behind master".

This means:

• Ahead: Number of commits on your feature branch that do not exist on master yet (your new feature work).
• Behind: Number of commits on master that do not exist on your feature branch (changes from other teams).

Before merging your pull request, you should bring those behind commits from master into your feature branch.

git Procedures

1. Update the local master branch

First, ensure your local master branch matches the remote master:

git checkout master
git pull origin master

This downloads the latest commits from origin/master so that you can use this up‑to‑date master as the base for your feature branch.

2.1 Option A – Update by merging master into your feature branch

This option keeps all history, adding an explicit merge commit. It is simple and safe for shared branches.

From your repository:

git checkout feature # feature is my branch
git pull --ff-only origin feature   # optional safety check
git merge master

If there are conflicts:

1. Open the reported files and resolve the conflicts manually.
2. Mark them as resolved and create the merge commit:

git add <file1> <file2> ...
git commit   # completes the merge

Push the updated feature branch:

git push origin feature

After this, GitHub should show your branch as up to date with master, and your pull request can be merged according to your repository’s merge settings.

2.2 Option B - Update by rebasing onto master

This option rewrites the feature branch history so your commits appear "on top" of the latest master, creating a linear history.

From your repository:

git checkout feature
git pull --ff-only origin feature   # optional safety check
git rebase master

If conflicts occur:

# edit files to fix conflicts
git add <file1> <file2> ...
git rebase --continue

Repeat until the rebase finishes. If you need to cancel the rebase:

git rebase --abort

Because rebase rewrites commit history, you must force‑push the branch:

git push --force-with-lease origin feature

Use --force-with-lease instead of --force to reduce the risk of overwriting others’ work on the same branch.