Divergent Git branches

Greg Foster
Greg Foster
Graphite software engineer


Note

This guide explains this concept in vanilla Git. For Graphite documentation, see our CLI docs.


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.

Join 20,000+ developers at top companies
Stop wrestling with Git commands
The Graphite CLI takes all the pain out of Git, allowing you to ship faster and stop googling Git commands.
main
diff1
diff2
  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:

    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
Join 20,000+ developers at top companies
The best engineers use Graphite to simplify Git
Engineers at Vercel, Snowflake & The Browser Company are shipping faster and staying unblocked with Graphite.
main
diff1
diff2

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.

Git inspired
Graphite's CLI and VS Code extension make working with Git effortless.
Learn more

Graphite
Git stacked on GitHub

Stacked pull requests are easier to read, easier to write, and easier to manage.
Teams that stack ship better software, faster.

Or install our CLI.
Product Screenshot 1
Product Screenshot 2