Integrating with Git

• Git for Windows (msysGit)
• Git WSL (Windows Subsystem for Linux)
• Git (Cygwin)

Integration with Git requires the Professional Edition of Merge to enable the comparison of two modified versions of a file with their common ancestor.

Git for Windows (msysGit)

Merge integrates tightly with Git for Windows. Araxis provides a Git File-System Plugin to enable Merge to access files in Git repositories directly. For file comparisons (but not folder comparisons), Merge is also able to populate the Versions button drop-down versions menu with other revisions of each file being compared. For more information, see Comparing Text Files (or Typed/Pasted Text).

Git for Windows can also be configured to use Merge for file comparison and merge operations.

The following configuration instructions have been tested using Git for Windows v2.24.0.

To use Araxis Merge for file comparison and file merging:

• Update the appropriate Git configuration file by adding the following diff and merge tool configurations:

  [diff]
  tool = araxis
  [difftool "araxis"]
  path = C:\\Program Files\\Araxis\\Araxis Merge\\compare.exe
  
  [merge]
  tool = araxis
  [mergetool "araxis"]
  path = C:\\Program Files\\Araxis\\Araxis Merge\\compare.exe
  
  [alias]
  ad = difftool --tool=araxis --dir-diff
  ads = difftool --tool=araxis --dir-diff --staged
  

  In the above paths, replace C:\\Program Files\\Araxis\\Araxis Merge\\compare.exe with the full path to the Merge compare.exe command-line utility that you have installed on your machine. Note the use of double-backslashes to separate path elements.

• To compare files, use the git difftool command. The --dir-diff option can be provided, in which case a folder comparison will be opened showing all the changed files.

  The git ad (short for Araxis diff) and ads (Araxis diff stage) aliases defined above provide convenient shortcuts to invoke Merge via the git difftool command. See Examples of using the git ad and ads aliases for usage.

• To resolve conflicting changes after merging files from a branch or remote repository, use the git mergetool command.

  When Merge is opened via git mergetool, the files being compared are automatically merged as described in the Automatic File Merging topic. Changes that overlap or touch at their start or end are marked as conflicts. A red conflict icon is shown at the beginning of each line within a change that could not be automatically merged.

  If you wish to see the files as they were prior to the automatic merge, simply click Undo or press Ctrl+Z.

Examples of using the git ad and ads aliases:

The git difftool command is a frontend to git diff and thus accepts git diff options and arguments. As the Git ad and ads aliases defined in the above configuration are simply shortcuts for invoking git difftool, this means that you can in general pass git diff arguments to git ad and git ads. The examples below show some possibilities, but are by no means exhaustive.

The documentation on specifying Git revisions and ranges may also be helpful when considering how best to invoke git ad.

The split-view folder-comparison-with-file-comparison (Two-way with file comparison ) can be especially useful when viewing folder comparisons launched by Git.

• Launch a two-way folder comparison to show all the unstaged changes within the current working tree:

  git ad
  

• Launch a two-way folder comparison to show all the staged changes within the current index (staging area):

  git ads
  

• Launch a two-way folder comparison showing the changes to a modified file myfile.c:

  git ad myfile.c
  

• Launch a two-way folder comparison of commits 11a783 and c2061b of myfile.c:

  git ad 11a783..c2061b myfile.c
  

• Launch a two-way folder comparison to show all the changes applied by the commit with hash c2061b:

  git ad c2061b^!
  

  If you are using zsh as your shell (e.g. under WSL) and have the EXTENDEDGLOB option set, you will need to escape the ^:

  git ad c2061b\^!
  

• Launch a two-way folder comparison to show all the changes between the master and bugfix branches:

  git ad master..bugfix
  

Git WSL (Windows Subsystem for Linux)

As of version 2017.4929, Merge can be integrated with Git running under the Windows Subsystem for Linux (WSL).

The use of Merge 2020 or later is strongly recommended as its WSL integration is considerably enhanced and uses \\wsl$-style paths with Windows 10 May 2019 Update (1903) onwards. Merge 2020 supports both WSL 1 and WSL 2.

Merge 2020 or later with Windows 10 May 2019 Update (1903) onwards

When using both Merge 2020 or later and Windows 10 1903 onwards, the Merge-WSL integration uses \\wsl$-style paths. This enables Merge to access WSL files, facilitating a much more straightforward integration than is possible with earlier versions of Merge or Windows.

To use Araxis Merge for file comparison and file merging:

• Update the appropriate Git configuration file by adding the following diff and merge tool configurations:

  [diff]
  tool = araxis
  [difftool "araxis"]
  cmd = '/mnt/c/Program Files/Araxis/Araxis Merge/arx_wsl_git_compare' $BASE $LOCAL $REMOTE
  
  [merge]
  tool = araxis
  [mergetool "araxis"]
  cmd = '/mnt/c/Program Files/Araxis/Araxis Merge/arx_wsl_git_merge' $BASE $LOCAL $REMOTE $MERGED
  
  [alias]
  ad = difftool --tool=araxis --dir-diff --no-symlinks
  ads = difftool --tool=araxis --dir-diff --no-symlinks --staged
  

  In the above paths, replace /mnt/c/Program Files/Araxis/Araxis Merge with the full path to the Merge installation folder on your machine.

• To compare files, use the git difftool command. The --dir-diff option can be provided, in which case a folder comparison will be opened showing all the changed files.

  The git ad (short for Araxis diff) and ads (Araxis diff stage) aliases defined above provide convenient shortcuts to invoke Merge via the git difftool command. See Examples of using the git ad and ads aliases for usage.

• To resolve conflicting changes after merging files from a branch or remote repository, use the git mergetool command.

  When Merge is opened via git mergetool, the files being compared are automatically merged as described in the Automatic File Merging topic. Changes that overlap or touch at their start or end are marked as conflicts. A red conflict icon is shown at the beginning of each line within a change that could not be automatically merged.

  If you wish to see the files as they were prior to the automatic merge, simply click Undo or press Ctrl+Z.

Merge 2017–2019 or Windows 10 October 2018 (1809) and earlier

When using these older versions of Merge or Windows, Merge-WSL integration requires the repositories and files being accessed by Merge to be stored on the Windows file system (e.g. under /mnt/c, from the perspective of WSL). Please read the following warning carefully to understand the reason for this limitation.

CRITICALLY IMPORTANT: Under no circumstance should you directly create and/or modify Linux files using Windows applications such as Araxis Merge. Due to the design of WSL, breaking this rule will likely result in loss of data and/or damage to your Linux environment. With older versions of Merge (pre-2020) or Windows (pre-Windows 10 1903), the integration of Merge with Git and Mercurial running under WSL therefore requires that you store repositories and files to be used from both Windows and WSL on the Windows file system (e.g. under /mnt/c, from the perspective of WSL). For more information, please see Do not change Linux files using Windows apps and tools.

The integration instructions in this section endeavour to adhere to the above restriction, but there may nevertheless be certain cases not taken into account. When saving or copying any file or folder using Merge, you are therefore advised to verify that the file or folder is not being written to the WSL file area under %localappdata%\lxss\.

To use Araxis Merge for file comparison and file merging:

• Since Git creates temporary files for comparison when git difftool is invoked, it is necessary to ensure that the TMPDIR environment variable is set to a temporary directory located on the Windows file system (e.g. under /mnt/c, from the perspective of WSL). One way of doing this is to create an alias for the git command that will set TMPDIR appropriately when running Git. To do this, add the following to your .bashrc:

  . "/mnt/c/Program Files/Araxis/Araxis Merge/arx_wsl_utilities"
  alias git="env TMPDIR='$(windows_tmp_dir_as_unix_path)' git"
  

  Note: replace /mnt/c/Program Files/Araxis/Araxis Merge in the above with the full path to the Merge installation folder on your machine.

  If you chose to set TMPDIR using this alias, you should only ever invoke Merge from Git using that alias. If you invoke Merge from Git under WSL via other means (e.g. from other applications or scripts), you should be sure to set TMPDIR appropriately before so doing.

• Update the appropriate Git configuration file by adding the following diff and merge tool configurations:

  [diff]
  tool = araxis
  [difftool "araxis"]
  cmd = '/mnt/c/Program Files/Araxis/Araxis Merge/arx_wsl_git_compare' $BASE $LOCAL $REMOTE
  
  [merge]
  tool = araxis
  [mergetool "araxis"]
  cmd = '/mnt/c/Program Files/Araxis/Araxis Merge/arx_wsl_git_merge' $BASE $LOCAL $REMOTE $MERGED
  
  [alias]
  ad = difftool --tool=araxis --dir-diff --no-symlinks
  ads = difftool --tool=araxis --dir-diff --no-symlinks --staged
  

  In the above paths, replace /mnt/c/Program Files/Araxis/Araxis Merge with the full path to the Merge installation folder on your machine.

• To compare files, use the git difftool command. The --dir-diff option can be provided, in which case a folder comparison will be opened showing all the changed files.

  The git ad (short for Araxis diff) and ads (Araxis diff stage) aliases defined above provide convenient shortcuts to invoke Merge via the git difftool command. See Examples of using the git ad and ads aliases for usage.

• To resolve conflicting changes after merging files from a branch or remote repository, use the git mergetool command.

  When Merge is opened via git mergetool, the files being compared are automatically merged as described in the Automatic File Merging topic. Changes that overlap or touch at their start or end are marked as conflicts. A red conflict icon is shown at the beginning of each line within a change that could not be automatically merged.

  If you wish to see the files as they were prior to the automatic merge, simply click Undo or press Ctrl+Z.

Git (Cygwin)

Git on Cygwin can be configured to use Merge for file comparison and merge operations.

The following configuration step has been tested using the Cygwin distribution of Git v2.21.0.

To use Araxis Merge for file comparison and file merging:

• Update the appropriate Git configuration file by adding the following diff and merge tool configurations:

  [diff]
  tool = araxis
  [difftool "araxis"]
  cmd = '/cygdrive/c/Program Files/Araxis/Araxis Merge/ConsoleCompare.exe' /2 `cygpath -w $LOCAL` `cygpath -w $REMOTE`
  
  [merge]
  tool = araxis
  [mergetool "araxis"]
  cmd = '/cygdrive/c/Program Files/Araxis/Araxis Merge/ConsoleCompare.exe' /3 /a2 `cygpath -w $REMOTE` `cygpath -w $BASE` `cygpath -w $LOCAL` `cygpath -w $MERGED`
  
  [alias]
  ad = difftool --tool=araxis --dir-diff --no-symlinks
  ads = difftool --tool=araxis --dir-diff --no-symlinks --staged
  

  In the above paths, replace /cygdrive/c/Program Files/Araxis/Araxis Merge/Compare.exe with the full path to the Merge compare.exe command-line utility that you have installed on your machine.

• To compare files, use the git difftool command. The --dir-diff option can be provided, in which case a folder comparison will be opened showing all the changed files.

  The git ad (short for Araxis diff) and ads (Araxis diff stage) aliases defined above provide convenient shortcuts to invoke Merge via the git difftool command. See Examples of using the git ad and ads aliases for usage.

• To resolve conflicting changes after merging files from a branch or remote repository, use the git mergetool command.

  When Merge is opened via git mergetool, the files being compared are automatically merged as described in the Automatic File Merging topic. Changes that overlap or touch at their start or end are marked as conflicts. A red conflict icon is shown at the beginning of each line within a change that could not be automatically merged.

  If you wish to see the files as they were prior to the automatic merge, simply click Undo or press Ctrl+Z.