The Sitecore Item Merge tool is a stand alone tool used to resolve merge conflicts in .item files during a source control merge/check-in. During installation, TDS automatically configures the Item Merge Tool for TFS. Configuring the Sitecore Item Merge tool for other Source Control providers will be covered below.

When your source control detects a conflict, it will require user intervention to merge the files. Although, Sitecore item files are plain text files, they are not as simple as text files. Care needs to be taken to properly manage field ID’s, versions and languages during the merge. This requires a specialized tool to do the process quickly and efficiently.

The screen shot shows a number of possible merge scenarios that may occur:

  • The __Lock field is the same in the Source, Target and Result, and therefore has no special highlighting in any of the windows.
  • The __Long description field was added in the source branch. Since this change is not a conflict between the two branches, it is highlighted in green. It is present on the left indicated by a solid highlight. It is not present on the right indicated by hashes. The grey hashes on the bottom indicate that there is a difference between the original and a branch. The item was not present in the original file.
  • The __Revision field was changed in both branches, and is different in both branches. This is indicated by a red box around each item in the branches. This indicates a conflict between the two branches, and extra care should be taken when deciding how to proceed with the merge.
  • The __Short description field has a green highlight, indicating the field values are not in conflict. The same value was added in both branches.

When resolving a merge, the user can choose to accept a change, reject a change or choose the value from one side or the other by checking the checkboxes and/or radio buttons in the top portion of the merge tool. You can see the result of your choices in the lower portion.

The merge tool offers a few shortcut functions from a toolbar. The tool bar buttons perform the following tasks:

  • Previous Arrow - Move to the previous difference.
  • Next Difference - Move to the next difference.
  • Previous Conflict - Move to the previous conflict.
  • Next Conflict - Move to the next conflict.
  • Select all non-conflict changes - Select all non-conflict changes.
  • Accept Chages - Accept all changes.

Setup Sitecore Item Merge for Source Control Providers

TDS automatically configures the Sitecore Item Merge to run for .item files inside of TFS. It needs to be configured for other source control providers.

The Sitecore Item Merge tool can be run from the command prompt. It accepts seven parameters from source control, which represent the four files that are part of the three-way merge and the labels for each of the three sections of the screen. The arguments for the Sitecore Item Merge are shown below in the order they are expected.

  1. [baseFilePath] - The file the merged files both started from.
  2. [branch1FilePath] - The file from the first branch.
  3. [branch2FilePath] - The file from the second branch.
  4. [finalFilePath] - The path to the file that holds the result of the merge.
  5. [branch1FileLabel] - Label for the branch1 file. This can be defined by source control or hard coded.
  6. [branch2FileLabel] - Label for the Branch2 file. This can be defined by source control or hard coded.
  7. [finalFileLabel] - Label for the Final file. This can be defined by source control or hard coded.

Configuring Sitecore Item Merge for Git using Script

By default, Git only allows a single file merge tool. Fortunately, Git allows the developer to easily extend the merge functionality. Please see the article: merge-wrapper (https://gist.github.com/elsevers/11349227) for more information on extending Git to use multiple merge tools.

The following code block is sample code modified from the above to provide Sitecore item merge capabilities in Git:

#!/bin/bash
# Wrapper script for git mergetool
# This requires the .gitconfig file to have:
#  - mergetool entry for "TDSMerge";
#  - mergetool entry for "kdiff3";
# These merge tool entries must both specify the
# cmd field. The command to call this script:
# [mergetool "merge_wrapper"]
# cmd = $HOME/merge-wrapper \"$BASE\" \"$LOCAL\" \"$REMOTE\" \"$MERGED\"
# Locate this script in your $HOME
 
BASE=$1
LOCAL=$2
REMOTE=$3
MERGED=$4
 
SCITEM="\.item"
 
if echo "$BASE" | grep -q "$SCITEM"; then
 echo "Using merge tool for sitecore item file";
 CMD=$(git config mergetool.TDSMerge.cmd) 
 eval $CMD
else
#checking for additional special merge tool cases
#Finally, the default case:
 echo "Using default merge tool";
 CMD=$(git config mergetool.kdiff3.cmd) 
 eval $CMD
fi

This solution needs some changes in the .gitconfig file. The changes needed are highlighted below:

[merge]
# tool = kdiff3
     tool = merge_wrapper
[diff]
     tool = kdiff3
     guitool = kdiff3
[core]
     editor = \"C:/Program Files (x86)/GitExtensions/GitExtensions.exe\" fileeditor
     autocrlf = false
[credential]
     helper = !'C:\\Users\\cturano\\AppData\\Roaming\\GitCredStore\\git-credential-winstore.exe'
[mergetool "kdiff3"]
     path = C:/Program Files (x86)/KDiff3/kdiff3.exe
[difftool "kdiff3"]
     path = C:/Program Files (x86)/KDiff3/kdiff3.exe
     cmd = \"C:/Program Files (x86)/KDiff3/kdiff3.exe\" \"$LOCAL\" \"$REMOTE\"
[i18n]
     filesEncoding = utf-8

[mergetool "merge_wrapper"]
     cmd = $HOME/merge-wrapper \"$BASE\" \"$LOCAL\" \"$REMOTE\" \"$MERGED\"

[mergetool "TDSMerge"]
     cmd = \"C:/Program Files (x86)/Hedgehog Development/Team Development for Sitecore (VS2013)/SitecoreItemMerge\" \"$BASE\" \"$LOCAL\" \"$REMOTE\" \"$MERGED\"

Configure Sitecore Item Merge for Git without using script

Some Git tools don’t allow you to configure multiple merge tools based on the file extension. If you are using a tool like this, we have provided a simple merge tool wrapper that can be configured to allow you to use multiple merge tools.

To setup the merge tool chooser, make the highlited changes to your .gitconfig:

[merge]
# tool = kdiff3
     tool = merge_chooser

[diff]
     tool = kdiff3
     guitool = kdiff3
[core]
     editor = \"C:/Program Files (x86)/GitExtensions/GitExtensions.exe\" fileeditor
     autocrlf = false
[credential]
     helper = !'C:\\Users\\cturano\\AppData\\Roaming\\GitCredStore\\git-credential-winstore.exe'
[mergetool "kdiff3"]
     path = C:/Program Files (x86)/KDiff3/kdiff3.exe
[difftool "kdiff3"]
     path = C:/Program Files (x86)/KDiff3/kdiff3.exe
     cmd = \"C:/Program Files (x86)/KDiff3/kdiff3.exe\" \"$LOCAL\" \"$REMOTE\"
[i18n]
     filesEncoding = utf-8

[mergetool "merge_chooser"]
     cmd = \"C:/Program Files (x86)/Hedgehog Development/Team Development for Sitecore (VS2013)/MergeToolChooser\" \"$BASE\" \"$LOCAL\" \"$REMOTE\" \"$MERGED\"

The MergeToolChooser passes the parameters to the specified merge tool based on the configuration specified in the MergeToolChooserConfig.xml file. This file need to be located in the same folder as the MergeToolChooser.

The default MergeToolChooserConfig.xml file specifies that SitecoreItemMerge.exe is the merge file for .item files and KDiff3 is the default merge tool for everything else.

<?xml version="1.0" encoding="utf-8" ?>
<MergeToolChooserConfig>
    <!-- TDS Item Merge Tool -->
    <MergeTool Extension=".item" Cmd=".\SitecoreItemMerge.exe" Parameters="&quot;$1&quot; &quot;$2&quot; &quot;$3&quot; &quot;$4&quot;"/>
    <!-- Default entry -->
    <MergeTool Cmd="C:\Program Files (x86)\KDiff3" Parameters="&quot;$1&quot; &quot;$2&quot; &quot;$3&quot; -o &quot;$4&quot;"/>
</MergeToolChooserConfig>

This file can be altered to allow any merge tool(s) the developer wants to use. The parameters are specified in the Parameter attribute by using $1, $2, $3, etc. Where $1 represents the first parameter passed to the merge tool, $2 represents the second, and so on. The Extension attribute specifies the file extension to use for the specified merge tool. The Cmd  attribute specifies the full path to the merge tool.

The merge tool is matched the order <MergeTool> elements are specified in the file. The match is based on one of the first 4 parameters ending with the string specified in the Extension attribute. If no Extension attribute is specified, the merge tool is considered the default merge tool.