Using xlCompare with GIT
How to integrate xlCompare into GIT or similar applications (SVN, SourceTree, Perforce) as external diff viewer and merge tool for XLSX and XML or Text files.
Integrate xlCompare into GIT step-by-step
Below is a simple procedure that connects your git repository with xlCompare application.
xlCompare has simple set of command line arguments (CLI) that are standard for diff viewer tools and merge tools.
So, you can integrate xlCompare into almost every version control application.
Step 1 - Install xlCompare on your computer
Visit the Download page or use this direct download link https://xlCompare.com/xlcompare.zip.
Save the setup file on your computer and run it to install the xlCompare.
Below we are using installation path to xlCompare application on your computer. By default xlCompare is installed into folder
C:/Users/{User Name}/AppData/Local/Spreadsheet Tools/xlCompare
But if you've installed it into other location, for example D:\xlCompare, you need to make appropriate changes.
Step 2 - Edit .git/config file
Add following lines to the .git/config file in your repository:
[diff "xlcompare"]
command = 'C:/Users/{User Name}/AppData/Local/Spreadsheet Tools/xlCompare/exceldiff.cmd'
[merge "xlcompare"]
name = xlCompare
driver = 'C:/Users/{User Name}/AppData/Local/Spreadsheet Tools/xlCompare/excelmerge.cmd' %A %O %B
[mergetool "xlcompare"]
cmd = 'C:/Users/{User Name}/AppData/Local/Spreadsheet Tools/xlCompare/excelmerge.cmd' \"$LOCAL\" \"$BASE\" \"$REMOTE\" \"$MERGED\"
trustExitCode = false
IMPORTANT:
Path to the xlCompare folder contains space characters, so we've wrapped it into single quote.
If you miss this quote chars - you will receive an error message in the Git console.
%A %O %B are command line arguments, used by GIT for the merge tools:
- %A - LOCAL version of Excel file
- %O - BASE (common) version of Excel file
- %B - REMOTE version of Excel file
Why there are two lines for merge?
First one (merge) sets xlCompare as a driver for automatic merge operations, when you are updating files in your local repository.
Second line (mergetool) allows to use xlCompare with a command git mergetool --tool=xlcompare -y --no-prompt {file path}
trustExitCode is set to true, so you will decide if merge operation was successful. However in the merge mode xlCompare returns number of conflicts as exit code. So, if needed, you can set this argument to true.
Step 3 - Connect Excel files in git with xlCompare
This is final step in our guide. Create .gitattributes file in the root of your repository. Possible this file already exists.
Add following lines to the end of the file:
*.xlsx diff=xlcompare
*.xlsx merge=xlcompare
*.xlsx merge=xlcompare
It points git to use xlCompare with Excel files, when diff viewer or merge tool is needed.
Start using xlCompare with git diff command!
That's all. You've connected your xlCompare with Excel files in the git repository.
Now git diff command shows difference for 2 XLSX files by opening xlCompare with difference report.
Integrate xlCompare into GUI tools like SourceTree, etc.?
Use these settings ff your version control application allows to set a GUI tool for diff and merge operations with Excel files.
Diff tool
Use path to your xlCompare as tool. By default it is:
'C:/Users/{User Name}/AppData/Local/Spreadsheet Tools/xlCompare/exceldiff-source-tree.cmd'
Command line arguments are following:
Merge tool
Use path to your xlCompare as tool. By default it is:
'C:/Users/{User Name}/AppData/Local/Spreadsheet Tools/xlCompare/excelmerge.cmd'
Command line switches are the following:
"$LOCAL" "$BASE" "$REMOTE" "$MERGED"
What about if version control app doesn't have $MERGED parameter?
Just remove it from command line and use the following syntax:
"$LOCAL" "$BASE" "$REMOTE"
IMPORTANT
We are using $LOCAL, $BASE and $REMOTE names in the command line switches above. Possible you need to replace them with appropriate names, used by your version control application.
NOTE
Command files exceldiff-source-tree.cmd and excelmerge.cmd are included into xlCompare installation package.
You have them on your computer in the xlCompare installation folder.
Questions and Answers
In this topic we've described some common questions about git integration.
If you need an assistance with using xlCompare as a difference viewer or merge tool for Excel files - contact us. We will be happy to help you.
Why do we use CMD files as a drivers for diff and merge tools?
You need to use this method, if you version control system requires console application as a diff or merge tool.
xlCompare itself is a GUI application, that is not always works when console tool is required.
In this case you can use our drivers or create a similar ones for your version control application.
What is inside CMD file
exceldiff.cmd
"%~dp0xlCompare.exe" %5 %2 -quit_on_close -titleMine:LOCAL -titleBase:REMOTE -rep:"%__CD__%"
- "%~dp0xlCompare.exe" - path to xlCompare application that is in the current directory
- %5 - LOCAL version of Excel file, git uses 7 arguments, 5-th one is a local file
- %2 - REMOTE version of Excel file
- quit_on_close - After you close the comparison xlCompare will exit. This will save you a second for clicking on the close button.
- titleMine:LOCAL - Git uses temporary file names, so LOCA and REMOTE will clearly identify the file.
- rep:"%__CD__%" - path to repository. This is highly important switch that should be used as last one. Without this parameter you will be unable to open files in subfolders.
excelmerge.cmd
"%~dp0xlCompare.exe" -merge -titleMine:LOCAL -titleBase:BASE -titleTheir:REMOTE "%1" "%2" "%3" -output:"%4" -rep:"%__CD__%"
- "%~dp0xlCompare.exe" - path to xlCompare application that is in the current directory
- git - says that it is used as external tool for GIT. It will exit after you close the comparison.
- merge - perform merge operation on the passed files and open GUI window is there are conflicts.
- titleMine:LOCAL - Git uses temporary file names, so LOCA and REMOTE will clearly identify the file.
- "%1" "%2" "%3" - paths to local, base and remote versions of Excel files.
- output:"%4" - if xlCompare is called with mergetool command, this switch tell xlCompare to save result file under $MERGED path. MERGED file is passed as 4-th argument in the mergetool syntax, described above.
- rep:"%__CD__%" - path to repository. This is highly important switch that should be used as last one. Without this parameter you will be unable to open files in subfolders.
As you see contents of the CMD files are simple, you can modify them by adding CONFIG switch or create your own CMD wrappers for GIT.
Do I need a license to use xlCompare with GIT and other tools?
XLSX and XML files
You need xlCompare Professional license to use xlCompare application as diff or merge tool for XLSX and XML files.
TEXT files
For the text files you don't need xlCompare license You can use xlCompare with text files for free.
