Divergent Git branches

Greg Foster
Greg Foster
Graphite software engineer

When working with Git, encountering the message "you have divergent branches" indicates a scenario where your local branch and its corresponding remote branch have both been updated in ways that Git cannot reconcile automatically. This guide will explain what this message means, how you might end up in this state, and how to resolve it effectively.

The message "you have divergent branches" typically appears when you try to sync your local branch with the remote branch (e.g., during a pull or push operation) and there are commits on both branches that are not in common. This means that your local branch and the remote branch have both advanced in different directions—like two paths branching off from a common starting point.

  1. Local commits: You’ve made commits locally on a branch (say, feature-branch) that have not been pushed to the remote repository.

  2. Remote commits: Simultaneously, other collaborators have made and pushed commits to the same branch in the remote repository.

When these two scenarios occur, and you try to push your changes or pull the remote changes, Git will alert you that the branches have diverged.

The resolution process involves deciding how to integrate these changes. There are primarily two ways to handle divergence: merging or rebasing.

Merging is the most straightforward method to resolve divergences. It involves pulling the remote changes and merging them into your local branch. This action creates a new "merge commit" that combines the histories of both branches.

Steps to resolve using merge:

  1. Pull remote changes:

    git pull origin feature-branch

    This command fetches the changes from the remote and tries to merge them into your local branch.

  2. Resolve any merge conflicts: If there are conflicts, Git will pause the merge and ask you to resolve them. After editing the files with conflicts, mark them as resolved:

    git add <conflicted-file>
  3. Complete the merge: Once all conflicts are resolved, continue the merge:

    git merge --continue

    If no conflicts were found, Git auto-creates the merge commit.

  4. Push the merge commit: Finally, push your changes to update the remote repository:

    git push origin feature-branch

Rebasing is a cleaner way to resolve divergences by placing all your local changes on top of the latest remote branch's changes. This method avoids creating an additional merge commit and keeps the project history linear.

Steps to resolve using rebase:

  1. Fetch remote changes:

    git fetch origin
  2. Rebase local changes:

    git rebase origin/feature-branch

    This command will start rebasing your changes on top of the latest commits from origin/feature-branch.

  3. Resolve any conflicts during rebase: If you encounter conflicts during the rebase, Git will stop and let you fix them. After resolving each conflict:

    git add <conflicted-file>

    Continue the rebase process:

    git rebase --continue
  4. Force push to remote: After a successful rebase, your local branch history will have diverged from the remote branch history (because the commit hashes have changed). You'll need to force push:

    git push origin feature-branch --force

For further reading on dealing with divergent branches see the official Git documentation.

Stay unblocked. Ship faster.
Experience the new developer workflow - create, review, and merge code continuously. Get started with one command.
Get started

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2