XML Diff and Patch

A VS Code extension that automatically generates and applies RFC 5261-compatible XML patch files using XPath selectors, watching modified XML files and producing diffs on save.

Originally developed for modding X4: Foundations (which uses RFC 5261 XML patches for game-data mods), the extension is fully generic and works with any XML workflow that follows the RFC 5261 patch format.

Features

• Auto-diff on save: Save a modified XML file and a diff is generated against the original (vanilla) version automatically.
• Auto-patch on save: Save a diff file and it is applied to the original to regenerate the modified file.
• Multiple folder pairs: Configure any number of modifiedFolder/diffFolder pairs under a single originalFolder, each with an optional pathPrefix.
• Glob pattern support: All folder paths accept *, ?, and ** glob wildcards so a single config entry can cover multiple mod directories.
• Explorer context menu: Right-click XML files or folders for Reset to Original, Reconstruct from Diff, and Regenerate Diff commands.
• Watch modes: onSave, onTheFly (debounced filesystem watcher), or contextMenuOnly.
• Settings sidebar: A dedicated explorer panel lets you add, edit, and remove folder pairs per scope (User / Workspace / Folder) without editing JSON directly.
• XSD validation: Optionally validate generated diff files against a schema, with configurable fail behavior.
• Empty diff handling: Choose to write, delete, warn, or warn-and-delete when a save produces no diff operations.
• Orphan cleanup: Regenerating a diff folder removes diff files that no longer have a corresponding modified file.

Requirements

Set xmlDiffAndPatch.originalFolder to the path containing the baseline XML files, then add at least one entry to xmlDiffAndPatch.folderPairs.

Minimal workspace settings example

{
  "xmlDiffAndPatch.originalFolder": "C:/Games/X4 Foundations/data",
  "xmlDiffAndPatch.folderPairs": [
    {
      "modifiedFolder": "${workspaceFolder}/src",
      "diffFolder": "${workspaceFolder}/diff",
      "pathPrefix": "libraries"
    }
  ]
}

• originalFolder: Path to the vanilla/baseline XML files. Always required.
• folderPairs: Array of pairs to process. Each pair needs modifiedFolder and diffFolder; pathPrefix is optional (see below).
• Use "." to refer to the workspace folder itself.
• modifiedFolder and diffFolder must not point to the same directory.
• originalFolder, modifiedFolder, and diffFolder support glob patterns (*, ?, **). pathPrefix does not support globs: it must be a plain file-system path segment.

How folder pairs work

Each pair in folderPairs defines one diff/patch cycle:

Path resolution

When a modified file is saved:

original  → originalFolder / [pathPrefix /] <relPath>
output    → diffFolder / <relPath>

When a diff file is saved (reflectDiffToModified = true):

original  → originalFolder / [pathPrefix /] <relPath>
output    → modifiedFolder / <relPath>

relPath is always the file's path relative to the source watch folder (modifiedFolder or diffFolder). pathPrefix only affects where the baseline file is looked up: it does not alter the output path.

For example, if originalFolder is C:\X4\data, pathPrefix is libraries, and you save {modifiedFolder}\ships\ship_xl.xml (relPath = ships\ship_xl.xml), the extension looks up C:\X4\data\libraries\ships\ship_xl.xml as the baseline and writes the diff to {diffFolder}\ships\ship_xl.xml.

Glob matching

A glob in modifiedFolder or diffFolder multiplies the pair: each expanded directory becomes a separate watcher instance. The two expansion lists are matched by a capture key — the path segment(s) covered by the wildcards, with the static prefix before the first wildcard and the literal suffix after the last wildcard both stripped before comparison. Only entries whose capture keys appear on both sides are activated; unmatched entries are each skipped with a per-entry warning.

Symmetric case — the most common pattern, where the same wildcard produces matching results on both sides:

{ "modifiedFolder": "mods/*/src", "diffFolder": "mods/*/diff" }

mods/*/src  →  [mods/modA/src,  mods/modB/src ]   capture keys: modA, modB
mods/*/diff →  [mods/modA/diff, mods/modB/diff]   capture keys: modA, modB

Activated: modA/src ↔ modA/diff,  modB/src ↔ modB/diff

Asymmetric case — the two sides expand to a different number of directories:

{ "modifiedFolder": "**/aiscripts.modified", "diffFolder": "**/aiscripts" }

The capture key for both patterns is the parent directory (the segment matched by **). If aiscripts.modified exists under 4 parent folders but aiscripts only under 2, only the 2 matching parents are activated; the other 2 aiscripts.modified folders are each skipped with a warning. Both sides do not need to expand to the same count.

originalFolder also accepts globs: when multiple directories match, the first alphabetical result is used and a warning is logged for the rest.

Multiple pairs share the same originalFolder (and all other scalar settings). This lets you handle several mod directories in one workspace configuration.

Context Menu Commands

Right-click any XML file or folder in the Explorer to access the XML Diff and Patch submenu. All three commands are also available from the Command Palette (uses the active editor's file when no selection is made). Selecting a folder processes all XML files within it recursively.

After each run a notification reports how many files were processed, how many were skipped (no matching original or wrong folder role), and how many orphan diffs were deleted.

Extension Settings

All settings are under the xmlDiffAndPatch namespace.

Editing Folder Pairs

folderPairs is an array of objects, which VS Code's built-in settings UI does not support editing directly. There are two ways to manage them:

Option 1: Settings Sidebar Panel (recommended)

Open the XML Diff and Patch panel in the Explorer sidebar. It shows your folder pairs grouped by scope (User or Workspace). Use the Add pair button to create a new entry, fill in the fields, and click Save. Existing pairs can be edited in-place or removed with the ✕ button.

Option 2: Edit settings.json directly

Open the relevant settings.json (e.g. Preferences: Open Workspace Settings (JSON)) and add or edit the xmlDiffAndPatch.folderPairs array manually:

"xmlDiffAndPatch.folderPairs": [
  {
    "modifiedFolder": "path/to/modified",
    "diffFolder": "path/to/diff",
    "pathPrefix": "optional/sub/path"
  }
]

Troubleshooting

Output channel

All extension activity is logged to the XML Diff and Patch output channel. Open it via View → Output and select XML Diff and Patch from the dropdown. The channel shows which folder pairs were resolved, which files were processed, and any warnings or errors.

Enable debug logging

Set xmlDiffAndPatch.debug to true in your settings to enable verbose logging. Debug output includes the resolved paths for every file event, XPath generation steps, and raw diff operations: useful for diagnosing unexpected diffs or missing output files.

"xmlDiffAndPatch.debug": true

Remember to set it back to false (or remove it) once you are done: debug mode is noisy.

Common issues

X4: Foundations Usage

X4: Foundations uses RFC 5261 XML patches to allow mods to modify game data without replacing entire files. This extension automates the diff/patch cycle:

1. Set originalFolder to the extracted X4 game-data folder.
2. Add a folder pair pointing at your mod's source XML and the diff output directory.
3. Edit and save your modified XML: the extension writes the RFC 5261 patch automatically.
4. Include the diff files in your mod package.

Demo

YouTube short demo video

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Credits

• Egosoft - for the game itself (In fact - for the series of games)!
• Members of the x4_modding discord channel - for their answers, support, ideas, and inspiration!

Changelog

[0.7.2] - 2026-05-27

• Fixed
  • ignoreDiffInAttribute can now be set via the VS Code settings UI. Previously, an incorrect type definition (["string", "null"]) prevented the settings editor from rendering a text input for it; it required manual settings.json editing. Now typed as string with an empty-string default (empty = disabled).
• Added
  • compactPath and qualifiedPath settings are now visible and editable in the VS Code settings UI. They already existed in the extension logic but were missing from the manifest, so the settings editor did not show them.
• Removed
  • showDiffEditorOnSave setting removed. It was never implemented and had no effect.

[0.7.1] - 2026-05-27

• Fixed
  • XML files with a UTF-8 BOM are now handled correctly. A BOM before the <?xml declaration no longer causes a parse failure or silently aborts the diff/patch operation.
  • Errors from the Reconstruct from Diff and Regenerate Diff context menu commands are now shown as a notification instead of being silently swallowed.
  • Settings sidebar no longer offers per-folder scope for folderPairs, which is not supported and previously caused a save error.

[0.7.0] - 2026-05-27

• Fixed
  • Unpaired deleted and inserted elements with different tag names now correctly produce a single replace operation instead of a separate remove + add pair.
  • Elements with two or more differing attributes were incorrectly considered close-enough matches during diff pairing; attribute difference counting is now accurate.
• Improved
  • Folder pairs with glob patterns no longer require both sides to expand to the same number of directories. The extension now matches directories by the path segment captured by the wildcards, so only folders that have a counterpart on both sides are activated. Unmatched folders are skipped individually with a warning instead of blocking the whole pair.
  • Generated sel XPath expressions use globally-unique // anchors where possible, producing shorter and more readable paths (unless onlyFullPath is enabled).
  • Elements without their own attributes are now qualified using a child-existence predicate (e.g. do_else[do_if[@value='...']]) to avoid brittle numeric position indices, preferring the child that lies on the path to the target.
  • When a single on-path child is enough to uniquely identify a parent element, the natural parent/child[@attr] form is used instead of the redundant parent[child[@attr]]/child[@attr] form.

[0.6.2] - 2026-05-27

• Fixed
  • A Changelog part in README.md

[0.6.1] - 2026-05-26

• Improved
  • XPath generation logic, including fallback to the full path.

[0.6.0] - 2026-05-17

• Added
  • Initial public version