Integrating a git Workflow with the Compare Workspaces Tool

You can configure a git tool, such as Git on the command line, TortoiseGit, and Sourcetree, to interface directly with the Compare Workspaces tool in the following ways:

• Viewing differences (git diff).
• Resolving conflicts following a merge attempt (git merge).

Viewing Differences With Git Integration

A git diff command (or its equivalent) can launch the Compare Workspaces tool, open to both repository versions. You can work in the tool as described in Compare Workspaces.

Resolving Merge Conflicts With Git Integration

A git merge command (or its equivalent) between two conflicted workspace files can launch the Compare Workspaces tool. You can compare workspaces in three ways:

• Your workspace ("ours") and the version with which you are in conflict ("theirs"). This view allows you to see differences and perform Copy to Left actions to resolve conflicts between your version and "theirs." Copy to Left effectively performs a merge that is directly reflected in your git tool.
• The "base" workspace version and your workspace version ("ours"). "Base" is the version of the workspace from which yours and "theirs" both originated prior to the latest revisions. This view is for your information only; neither workspace is editable.
• The "base" workspace and "their" workspace. This view is for your information only; neither workspace is editable.

Each view is selectable as a tab at the top left of the Compare Workspaces tool: (According to the configurations in Setting up the Integration (below), the tabs appear like this, but you can adjust the labels according to your own settings.)

This workflow also provides the option of explicitly flagging a merge as resolved. To flag a merge as resolved, once your version of the workspace is free of conflicts with "theirs," click Resolve in the middle toolbar. The resolved flag reflects accordingly in your git tool.

Setting up the Integration

The following instructions are a guide for setting up the Compare Workspaces tool to interface with the following git tools:

• Git on the command line
• TortoiseGit
• Sourcetree

These instructions focus on a Windows environment; however, similar configurations can be made on Linux and MacOS to achieve the same result.

Prerequisites

Git for Windows should be installed, along with a recent version of FME Form. Ensure that the FME installation directory is set on the PATH variable so that FME Workbench can be launched directly from the command line.

To properly test, there should also be a repository that contains, or will contain, workspaces that are modifiable over time.

Git on the Command Line

1. Add a line to your .gitattributes file to launch custom drivers fmeworkbench on git diff and fmeworkbench on git merge. (The .gitattributes file can reside in any directory in the repository that contains your workspaces. The root directory of the repository is the simplest place.) Add the line as follows:
Copy

*.fmw diff=fmeworkbench merge=fmeworkbench

This line can be extended with other values, such as -text, which tells git to skip line ending conversions. For more options, see the gitattributes guide in the git documentation.

2. Define the custom diff driver fmeworkbench that launches FME Workbench.

Create a shell script called workspace_diff.sh in a directory that is accessible to your PATH environment. Put the following contents in the shell script:

Copy

#!/bin/bash
# Arguments are: path old-file old-hex old-mode new-file new-hex new-mode
 
echo "Comparing changes on '" $1 "' using FME Workspace Compare"
 
fmeworkbench -TITLE-OVERRIDE "[$1] Compare Changes" -COMPARE-TITLE1 "Left" -COMPARE-TITLE2 "Right" -COMPARE $5 $2
 
exit 0

Note  The suggested TITLE-OVERRIDE settings can be configured to your choice.
3. Add the following to your git configuration file to register the shell script as the custom diff driver:
Copy

[diff "fmeworkbench"]
command = workspace_diff.sh
binary = true

Now, when using any git diff command on a .fmw file, FME Workbench will launch the Compare Workspaces tool, comparing the two files.

4. Define the custom merge driver fmeworkbench that launches FME Workbench.

Create a shell script called workspace_merge.sh in a directory that is accessible to your PATH environment. Put the following contents in the shell script:

Copy

#!/bin/bash
# Arguments are: ancestor-file current-file other-file path
echo "Launching FMEWorkbench to merge " $4
 
fmeworkbench -TITLE-OVERRIDE "[$4] Merge" -COMPARE-BASE $1 -COMPARE-BASE-TITLE "Base" -COMPARE-TITLE1 "Ours" -COMPARE-TITLE2 "Theirs" -COMPARE $2 $3

5. Add the following to your git configuration file to register the shell script as the custom merge driver:
Copy

[merge "fmeworkbench"]
name = FME Workbench Merge Driver
driver = workspace_merge.sh %O %A %B %P

Now, when using any git merge command on a .fmw file, FME Workbench will launch the Compare Workspaces tool.

TortoiseGit

1. Configure Diff Integration
1. Go to TortoiseGit Settings
2. In the left panel, select DiffViewer.
3. In the Diff Viewer pane, click Advanced.

   

4. In the Advanced diff settings dialog, click Add.
5. In the Edit extension specific diff program dialog, specify the following:
• Extension: .fmw
• External Program: <fme install dir>/fmeworkbench.exe -COMPARE %base %mine



6. Click OK to close out of each dialog.

Now, when using TortoiseGit to compare revisions of workspace files, FME Workbench will launch the Compare Workspaces tool, comparing the two files.

2. Configure Merge Integration
1. Go to TortoiseGit Settings
2. In the left pane, select Merge Tool.
3. In the Merge Tool pane, click Advanced.

   

4. In the Advanced merge settings dialog, click Add.
5. In the Add extension specific merge program dialog, specify the following:
• Extension: .fmw
• External Program: <fme install dir>/fmeworkbench.exe -MERGE-TARGET %merged -COMPARE-BASE %base -COMPARE %mine %theirs



6. Click OK to close out of each dialog.

Now, when using TortoiseGit to merge a revisions of a workspace file, FME Workbench will launch the Compare Workspaces tool.

Sourcetree

1. Configure Diff Integration
1. Go to Tools > Options.
2. Click the Diff tab
3. Under External Diff / Merge, set:
• External Diff Tool: Custom
• Diff Command: Navigate to fmeworkench.exe
• Arguments (corresponding to Diff Command): -COMPARE \"$LOCAL\" \"$REMOTE\"
4. Click OK.
5. Select a commit that has a change to a .fmw file, and click on the .fmw file.
6. Click the diff settings icon, and select External Diff to launch the Compare Workspaces tool in FME Workbench.



2. Configure Merge Integration
1. Go to Tools > Options.
2. Click the Diff tab
3. Under External Diff / Merge, set:
• External Merge Tool: Custom
• Diff Command: Navigate to fmeworkench.exe
• Arguments (corresponding to Merge Command): -MERGE-TARGET \"$MERGED\" -COMPARE-BASE \"$BASE\" -COMPARE \"$LOCAL\" \"$REMOTE\"
4. Click OK.



5. Select a branch to merge that has a conflicting change in a .fmw file, and merge it.
6. From the context menu on the conflicting file, select Resolve Conflicts > Launch External Merge Tool to launch the Compare Workspaces tool in FME Workbench.