How to rebase local branch onto remote master

How to Rebase Your Local Git Branch Onto a Remote Master

Learn the essential Git rebase workflow to keep your local feature branches up-to-date with the remote master, ensuring a clean and linear commit history.

Keeping your local feature branch synchronized with the main development line (often master or main) is crucial for avoiding complex merge conflicts and maintaining a clean project history. While git merge is an option, git rebase offers a powerful alternative that rewrites your branch's history, making it appear as if your changes were made directly on top of the latest master.

Understanding Git Rebase

Git rebase is a command that integrates changes from one branch into another. Unlike git merge, which creates a new merge commit, git rebase moves or reapplies a series of commits from your feature branch onto a new base commit. This results in a linear project history, which can be easier to read and understand, especially in projects with many contributors.

flowchart TD
    gitGraph
    commit id: "C1"
    commit id: "C2"
    branch feature
    checkout feature
    commit id: "F1"
    commit id: "F2"
    checkout master
    commit id: "C3"
    commit id: "C4"
    checkout feature
    cherry-pick id: "F1"
    cherry-pick id: "F2"
    checkout master
    merge feature
    commit id: "M"
    branch rebased_feature
    checkout rebased_feature
    cherry-pick id: "F1"
    cherry-pick id: "F2"
    checkout master
    merge rebased_feature
    commit id: "M_rebased"

    config {
        "mainBranchName": "master"
    }

    %% This is a simplified representation. The actual rebase operation rewrites F1 and F2.
    %% The 'cherry-pick' here is used to illustrate the conceptual reapplication of commits.
    %% A true rebase would show F1' and F2' on top of C4, then master fast-forwarding.
    %% Due to limitations in gitGraph for showing rebase directly, this illustrates the 'effect'.

    %% Correct conceptual flow for rebase:
    %% master: C1 -- C2 -- C3 -- C4
    %% feature: C1 -- C2 -- F1 -- F2
    %% After rebase feature onto master:
    %% master: C1 -- C2 -- C3 -- C4
    %% feature: C1 -- C2 -- C3 -- C4 -- F1' -- F2'
    %% Then master fast-forwards to feature.

    %% Let's try a more direct rebase visualization if possible with gitGraph
    %% This is a common challenge with gitGraph for rebase.
    %% The following is a better conceptual representation of the *result*:

    %% gitGraph
    %%    commit id: "C1"
    %%    commit id: "C2"
    %%    branch feature
    %%    checkout feature
    %%    commit id: "F1"
    %%    commit id: "F2"
    %%    checkout master
    %%    commit id: "C3"
    %%    commit id: "C4"
    %%    checkout feature
    %%    rebase master
    %%    checkout master
    %%    merge feature
    %%    commit id: "M_rebased"

    %% The above gitGraph syntax for rebase is not directly supported to show the commit ID change.
    %% The initial graph shows the conceptual difference between merge and rebase's outcome.
    %% For a true rebase visualization, a different diagram type might be better, or a more abstract gitGraph.

    %% Let's simplify to show the *before* and *after* of the feature branch relative to master.
    %% This is the most common way to explain rebase visually.

    commit id: "A"
    commit id: "B"
    branch feature_before_rebase
    checkout feature_before_rebase
    commit id: "X"
    commit id: "Y"
    checkout master
    commit id: "C"
    commit id: "D"

    %% After rebase, feature_before_rebase would conceptually look like:
    %% master: A -- B -- C -- D
    %% feature_after_rebase: A -- B -- C -- D -- X' -- Y'

    %% This is the best way to represent it with gitGraph's current capabilities for clarity.
    %% The 'rebase' command itself in gitGraph doesn't visually rewrite history in the way we need.
    %% So, we show the state before and imply the state after.

    %% Let's try a flowchart to show the *process* of rebasing.

    flowchart LR
        subgraph Before Rebase
            A["master: C1 -- C2"]
            B["feature: C1 -- C2 -- F1 -- F2"]
            C["Remote master: C1 -- C2 -- C3 -- C4"]
        end

        subgraph Rebase Process
            D[""git fetch origin""]
            E[""git checkout feature-branch""]
            F[""git rebase origin/master""]
            G{Conflicts?}
            G -- Yes  -->  H[""Resolve conflicts, git add, git rebase --continue""]
            G -- No  -->  I[""Rebase complete""]
        end

        subgraph After Rebase
            J["feature-branch: C1 -- C2 -- C3 -- C4 -- F1' -- F2'"]
            K["Remote master: C1 -- C2 -- C3 -- C4"]
        end

        A  -->  D
        B  -->  D
        C  -->  D
        D  -->  E
        E  -->  F
        F  -->  G
        H  -->  F
        I  -->  J
        J  -->  K

        style A fill:#f9f,stroke:#333,stroke-width:2px
        style B fill:#bbf,stroke:#333,stroke-width:2px
        style C fill:#f9f,stroke:#333,stroke-width:2px
        style J fill:#bbf,stroke:#333,stroke-width:2px
        style K fill:#f9f,stroke:#333,stroke-width:2px

Conceptual flow of rebasing a local feature branch onto a remote master.

Step-by-Step: Rebasing Your Local Branch

Follow these steps to safely rebase your local feature branch onto the latest remote master.

1. Step 1: Ensure a Clean Working Directory

Before starting any Git operation that modifies history, ensure your working directory is clean. Commit or stash any uncommitted changes.

2. Step 2: Fetch the Latest Changes from Remote

Update your local repository's knowledge of the remote branches without merging them. This ensures you have the most current origin/master.

3. Step 3: Switch to Your Feature Branch

Navigate to the local feature branch you intend to rebase.

4. Step 4: Rebase Your Feature Branch onto Remote Master

This is the core rebase command. It takes all the commits on your current branch that are not on origin/master and reapplies them one by one on top of origin/master.

5. Step 5: Resolve Conflicts (if any)

If conflicts occur during the rebase, Git will pause and prompt you to resolve them. After resolving, git add the conflicted files and continue the rebase. You can abort the rebase at any time with git rebase --abort.

6. Step 6: Push Your Rebased Branch (Force Push if necessary)

After a successful rebase, your local branch's history has changed. If you've previously pushed this branch, you'll need to force push to update the remote. Use git push --force-with-lease for a safer force push, which prevents overwriting others' work if they've pushed to the same branch.

# Step 1: Ensure a clean working directory
git status
# If you have uncommitted changes, either commit them or stash them:
# git commit -m "WIP: Before rebase"
# git stash

# Step 2: Fetch the latest changes from remote
git fetch origin

# Step 3: Switch to your feature branch
git checkout my-feature-branch

# Step 4: Rebase your feature branch onto remote master
git rebase origin/master

# Step 5: Resolve conflicts (if any)
# If conflicts occur, Git will tell you which files are conflicted.
# 1. Open the conflicted files and resolve the differences.
# 2. Mark them as resolved:
git add <conflicted-file-1> <conflicted-file-2>
# 3. Continue the rebase:
git rebase --continue
# Repeat until all conflicts are resolved and rebase completes.
# To abort the rebase at any point:
# git rebase --abort

# Step 6: Push your rebased branch
# If this is a new branch, a regular push is fine:
git push origin my-feature-branch

# If you have previously pushed this branch, its history has changed.
# You will need to force push. Use --force-with-lease for safety:
git push --force-with-lease origin my-feature-branch

Commands for rebasing a local branch onto remote master.