Divergent Git branches

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?

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.

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:

1. Pull remote changes:

   Terminal

   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:

   Terminal

   git add <conflicted-file>
   
   

3. Complete the merge: Once all conflicts are resolved, continue the merge:

   Terminal

   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:

   Terminal

   git 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:

1. Fetch remote changes:

   Terminal

   git fetch origin
   
   

2. Rebase local changes:

   Terminal

   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:

   Terminal

   git add <conflicted-file>
   
   

   Continue the rebase process:

   Terminal

   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:

   Terminal

   git push origin feature-branch --force
   
   

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