Resolve Git Merge Conflicts

Learn how to resolve conflicts in your site code base.

Contributors: Alex Fornuto.

Discuss in our Forum Discuss in Slack

Git is the version control tool at the heart of the Pantheon workflow. If you're a developer who likes to use local development, it's a good way to work with the Pantheon platform: develop locally, commit, and push to master to deploy code into your Pantheon Development environment.

Conflicts can occur when modified file(s) within your site's codebase do not align with changes made to the same file(s) in the site's upstream.

When a merge isn’t resolved automatically, Git leaves the index and the working tree in a special state that gives you all the information you need to help resolve the merge.

- Git Manual

Resolve Conflicts When Updating Core

If you receive the error that you have conflicts while updating core, the fastest resolution is often the -Xtheirs flag. This will attempt to automatically resolve the conflicts with a preference for upstream changes.

This is safe to run if you don't have your own changes in any of the conflicting files (e.g. problems with .gitignore).

git pull -Xtheirs git:// default
# resolve conflicts
git push origin master
git pull -Xtheirs git:// default
# resolve conflicts
git push origin master
git pull -Xtheirs git:// default
# resolve conflicts
git push origin master
git pull -Xtheirs git:// master
# resolve conflicts
git push origin master

Double-check the files before going forward to make sure no bugs were introduced.

If you modify core CMS files, the -Xtheirs flag will drop your changes. In that case you should manually resolve conflicts. For more details on core updates, see WordPress and Drupal Core Updates.

Find a Site's Upstream URL

The upstream URL is provided within the Site Dashboard, under Settings > About site. Upstream URLs can also be identified via Terminus:

terminus site:info <site> --field=upstream

Manually Resolve Conflicts

How you resolve a merge conflict depends on what type of conflict you're faced with.

Resolve delete/modify Conflicts

A delete/modify conflict occurs when one commit deletes a file and another modifies it. To resolve such a conflict from the terminal, use the following commands in sequence. Start by identifying the file that is generating a delete error.

For example, the Git log may contain an entry similar to the following:

CONFLICT (delete/modify): scripts/ deleted in HEAD and modified in 72faeeff1c9356221694d1351cdb2000ab3c5d1c. Version 72faeeff1c9356221694d1351cdb2000ab3c5d1c of scripts/ left in tree.
  1. From your local repository, run this Git command to get a copy of the file in conflict:

    git checkout <commit ID> -- <file>


    When looking for a commit ID, you can find the last instance where the missing file was in the repository.

  2. Run git status and verify that there is a new file to add to the repository:

     git status
     On branch master
     Changes to be committed:
     (use "git reset HEAD ..." to unstage)
     new file: README.txt
  3. Stage and commit:

    git commit -am "verifying missing README.txt"

    You will receive confirmation from Git that the file has been committed.

  4. Run the Git push command:

    git push origin master

Resolve Content Conflicts

A content conflict occurs when two commits modify the same line(s) of a file non-sequentially (without one having the other in its history). For example:

CONFLICT (content): Merge conflict in wp-admin/about.php
Automatic merge failed; fix conflicts and then commit the result.

To resolve:

  1. Open the conflicting file in your text editor or IDE. Note that the conflicting lines are enclosed with <<<<<<< HEAD at the top, and >>>>>>> <commit-id> at the bottom, with ======= delineating the two versions. Some IDEs, like Visual Studio Code for example, will highlight the conflicting section:

    An example of Visual Studio Code highlighting a merge conflict

  2. Edit the conflict by either choose one of the two versions of the conflicting line(s), or editing a version containing both updates. Be sure to remove all the delineators notes above from the file.

  3. Once you've saved your changes, commit and push:

    git add wp-admin/about.php
    git commit -m "Merge conflict resolution"
    git push origin master

Resolve Conflicts from Multidevs

If a merge conflict is preventing you from merging a Multidev environment, follow these steps to resolve.

  1. Set the Dev environment to Git mode:

    Git Connection Mode

  2. Clone the repository to your local computer:

    Git Clone

  3. From the repository directory, pull the Multidev branch to master. In the example below, replace multidev with the Multidev environment name:

    git checkout master
    git pull origin multidev
  4. Git will tell you which files are in conflict. Resolve the conflicts using the steps above.