Github Desktop Comparison Script

So, we have this program where our 'version control' has, for at least the last three-four years, been simply date-stamping a Save-As version of the project every time we make a change. Obviously, this is not sustainable. Recently, we've been able to start making the move to Github for all of our projects, and I wanted to do the same with this.

Unfortunately, the saved version of the code/project ends up a compressed version of an xml file with no line breaks. Not exactly easy for comparison. I found a way to do compares based on the command line, with gitconfig and gitattribute updates and a little external script, and it works tolerably well in that environment.

But we're primarily using the (enterprise) website and Github Desktop for our needs. And this process doesn't seem to apply to those environments.

So the question is -- is there any way to set up a script for comparisons in the GitHub webpage or GitHub Desktop environments?

For reference, the page I found the command-line / git for windows format was https://www.theorycrafter.org/quipu/order-to-chaos-version-control-and-transformations/, and the program is Kofax Transformation Modules.

Solution

Modifying Binary Diffs with Github Desktop

It does not appear that Github Desktop has the ability to do this directly from the interface. What you would do is additionally install git, follow the instructions in the article, then from Github Desktop, you can click Repository > Show in Explorer, then right click on the folder and choose Git GUI Here, which you can use to see the diffs.

External Files for Granular Changes in a KTM Project

When you look at the xml contents of the KTM project file (.fpr), you see the script in the project, but also all of the internals of the definition of the project. Some might be understandable like fields, but many others may not. Either way, you won't be able to selectively merge changes (as the article mentions). So at its core, you will still have a check-in of the whole project for each change. If you want to be able to be more granular, you might consider a different approach in place of, or even in addition to what the article suggests.

Script: You could could copy your script out to separate text files that get checked in and then be able to do normal diffs and merges on them, knowing that you can copy a merged script back into the project. Update: KTM 6.1 Service Pack 1 (6.1.1) introduces a menu option to the code window to do this easily (Tools > Save All Scripts).

Locators: Project Builder allows you to export/import the configuration of a specific locator to a file. You won't be able do diffs or merges on these, however, if you determined that a locator was producing worse results after a certain change, you could import the specific locator from a previous check-in rather than reverting the entire project.

Programmatic Approach: The script function below can be called to export a file for each class containing the class's script, as well as an export of each locator Script locators cannot be exported, but they also don't have much configuration: The script behind them is included in their class script. You could run the function as needed, but to make it simple my recommendation is to have it run each time you test a document in Project Builder. Thus any time you test extracting a document, these external files are up to date and any changes can be committed.

Public Sub Design_ExportScriptAndLocators()
   Dim ClassIndex As Long
   Dim Path As String
   ' You could hard code a path if you did not want to use script variables
   Path=Project.ScriptVariables("Dev_ExportPath")

   ' Make sure you've added the Microsoft Scripting Runtime reference
   Dim fso As New Scripting.FileSystemObject
   If Not fso.FolderExists(Path) Then Exit Sub

   ' Here we use class index -1 to represent the special case of the project class
   For ClassIndex=-1 To Project.ClassCount-1
      Dim KTMClass As CscClass, ClassName As String, ScriptCode As String

      ' Get the script of this class
      If ClassIndex=-1 Then
         Set KTMClass=Project.RootClass
         ScriptCodPe=Project.ScriptCode
      Else
         Set KTMClass=Project.ClassByIndex(ClassIndex)
         ScriptCode=KTMClass.ScriptCode
      End If

      ' Get the name of the class
      ClassName=IIf(ClassIndex=-1,"Project",KTMClass.Name)

      ' Export script to file
      Dim ScriptFile As TextStream
      Set ScriptFile=fso.CreateTextFile(Path & "\Script-" & ClassName & ".txt",True,False)
      ScriptFile.Write(ScriptCode)
      ScriptFile.Close()

      ' Export locators (same as from Project Builder menus)
      Dim FileName As String
      Dim LocatorIndex As Integer
      For LocatorIndex=0 To KTMClass.Locators.Count-1
         If Not KTMClass.Locators.ItemByIndex(LocatorIndex).LocatorMethod Is Nothing Then
            FileName="\" & ClassName & "-" & KTMClass.Locators.ItemByIndex(LocatorIndex).Name & ".loc"
            KTMClass.Locators.ItemByIndex(LocatorIndex).ExportLocatorMethod(Path & FileName,Path)
         End If
      Next
   Next
End Sub

Example call when a document extraction is tested in Project Builder:

Private Sub Document_AfterExtract(ByVal pXDoc As CASCADELib.CscXDocument)
   ' Only when run in Project Builder...
   If Project.ScriptExecutionMode=CscScriptExecutionMode.CscScriptModeServerDesign Then
      ' Update external script and locator files added to source control
      Design_ExportScriptAndLocators()
   End If
End Sub

There is no perfect solution to store KTM projects or KC batch classes in source control as nicely as simple code, but this at least gives you a little more granularity to see what changes are checked in and be able to revert changes with more granularity.