Skip to content

XMLDIffWithVSCode.md

Latest commit

 

History

History
137 lines (100 loc) · 6.63 KB

XMLDIffWithVSCode.md

File metadata and controls

137 lines (100 loc) · 6.63 KB

Using XMLDIff with Visual Studio Code

Introduction

This document describes how to use XMLDiff with Visual Studio Code.

Prerequisites

Steps

  1. Prepare a folders structure like the following:

    RootExtensionFolder
│   XMLDiffAndPatch
│   │   XMLDiff.exe
│   RunXMLDiff.bat
│   aiscripts
│   aiscripts.modified
│   aiscripts.original
│   md
│   md.modified
│   md.original
│   subdir1
│   │   subdir2
│   │   │   aiscripts
│   │   │   aiscripts.modified
│   │   │   aiscripts.original

    The structure now supports any depth of subdirectories between the workspace root and the type folders.

  2. You can skip creation *.original folders, if you will use the extracted files folder.

  3. Copy the RunXMLDiff.bat file to the root of your project.

  4. Copy the XMLDiff.exe file to the XMLDiffAndPatch folder in the root of your project.

  5. Install the VSCode extension Run on Save by emeraldwalk

  6. Open the settings of the extension by pressing Ctrl + , and search for runOnSave.commands

  7. Add the following configuration to the settings: 7.1 In case of not to use the "Extracted" files folder, i.e. with *.original folders:

    "commands": [
    {
        "match": "\\.modified\\\\.+?\\.xml$",
        "cmd": "${workspaceFolder}\\RunXMLDiff.bat ${file} ${workspaceFolder}\\XMLDiffAndPatch\\XMLDiff.exe ${workspaceFolder}"
    }
]

    7.2. With the extracted folder, which is outside the project folder:

    "commands": [
    {
        "match": "\\.modified\\\\.+?\\.xml$",
        "cmd": "${workspaceFolder}\\RunXMLDiff.bat ${file} ${workspaceFolder}\\XMLDiffAndPatch\\XMLDiff.exe ${workspaceFolder} ${workspaceFolder}\\..\\extracted"
    }
]

    Take in account that with the extracted folder you still can use the *.original folders for original files. It will be used first, if they exist, otherwise the script will use the extracted folder.

  8. Save the settings and close the settings tab.

Now you can modify the *.modified files and the RunXMLDiff.bat will be executed automatically on save.

You can check an output in the OUTPUT tab in the VSCode, selecting the Run on Save item in the dropdown list.

Description of the RunXMLDiff.bat

RunXMLDiff.bat is a batch script that compares a modified XML file with its original version using the XMLDiff.exe utility. The script takes the paths to the modified file, the XMLDiff utility, and optionally the path to the original files as input. It then constructs the appropriate paths, checks for the existence of necessary files and directories, and runs the XMLDiff utility to generate a diff file.

Usage

RunXMLDiff.bat <ModifiedFilePath> <XMLDiffPath> <WorkspacePath> [OriginalFilesPath]

Parameters

  • <ModifiedFilePath>: The full path to the modified XML file. This parameter is mandatory.
  • <XMLDiffPath>: The full path to the XMLDiff.exe utility. This parameter is mandatory.
  • <WorkspacePath>: The full path to the workspace root directory. The modified file must be located inside this workspace. This parameter is mandatory.
  • [OriginalFilesPath]: The full path to the directory containing the original XML files. This parameter is optional.

Example

RunXMLDiff.bat "C:\path\to\workspace\subdir\md.modified\file.xml" "C:\path\to\XMLDiff.exe" "C:\path\to\workspace" "C:\path\to\original\files"

How It Works

  1. Validate Workspace: The script validates that the modified file path is inside the workspace path. If not, it exits with an error.
  2. Calculate Relative Path: The script calculates the relative path from the workspace to the modified file, preserving the full directory structure.
  3. Extract Type and Filename: The script extracts the type (e.g., aiscript or md) and filename from the relative path. The type is determined from the parent folder of the .modified folder.
  4. Determine Target File Path: The script constructs the target file path by replacing .modified with .diff in the relative path structure, maintaining any subdirectories.
  5. Determine Original File Path:
    • First, it looks for a local .original folder following the same relative path structure.
    • If the OriginalFilesPath is provided and local original file doesn't exist, the original file path is constructed using the same relative directory structure under OriginalFilesPath.
    • If the OriginalFilesPath is not provided, it uses the local .original folder path.
  6. Check Existence:
    • The script checks for the existence of XMLDiff.exe, the modified file, the original file, and the target file directory.
  7. Run XMLDiff: If all checks pass, the script runs XMLDiff.exe with the appropriate parameters to generate the diff file.

Error Handling

The script will output error messages and exit with a non-zero status code if any of the following conditions are met:

  • The modified file path is not inside the workspace path.
  • XMLDiff.exe is not found at the specified path.
  • The modified file is not found at the specified path.
  • The original file is not found at the constructed path.
  • The target file directory does not exist.

Output

If the script runs successfully, it will output a message indicating that the XMLDiff operation completed successfully and provide the path to the generated diff file.

Notes

  • Ensure that the XMLDiff.exe utility is accessible and has the necessary permissions to execute.
  • The script assumes that the modified file path follows the convention where one of the folders in the relative path is of the form type.modified.
  • The script now supports any depth of subdirectories between the workspace root and the type folders, preserving the full directory structure in the output.
  • If you have some beautification plugins for XML use the alternative save (Ctrl + K S, i.e. "Save without Formatting), which will not involve them, to get the diff as small as possible.

Demo

Small demo video

License

This script is provided "as-is" without any warranty. Use it at your own risk.