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.
What does "divergent branches" mean?
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.
How do you end up with divergent branches?
Local commits: You’ve made commits locally on a branch (say,
feature-branch
) that have not been pushed to the remote repository.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.
How to resolve divergent branches
The resolution process involves deciding how to integrate these changes. There are primarily two ways to handle divergence: merging or rebasing.
Option 1: merging
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:
Pull remote changes:
Terminalgit pull origin feature-branchThis command fetches the changes from the remote and tries to merge them into your local branch.
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:
Terminalgit add <conflicted-file>Complete the merge: Once all conflicts are resolved, continue the merge:
Terminalgit merge --continueIf no conflicts were found, Git auto-creates the merge commit.
Push the merge commit: Finally, push your changes to update the remote repository:
Terminalgit push origin feature-branch
Option 2: rebasing
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:
Fetch remote changes:
Terminalgit fetch originRebase local changes:
Terminalgit rebase origin/feature-branchThis command will start rebasing your changes on top of the latest commits from
origin/feature-branch
.Resolve any conflicts during rebase: If you encounter conflicts during the rebase, Git will stop and let you fix them. After resolving each conflict:
Terminalgit add <conflicted-file>Continue the rebase process:
Terminalgit rebase --continueForce 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:
Terminalgit push origin feature-branch --force
For further reading on dealing with divergent branches see the official Git documentation.