How to Create an XDelta Patch with Delta Patcher

What you need

• The original file: an unmodified copy, identical to the one your users will have. If people commonly have several versions (different regions, revisions or dumps), pick one and document it clearly.
• The modified file: the finished result you want people to end up with. Build it from that same original.
• Delta Patcher, installed from the download page.

Create the patch step by step

1. Switch to patch creation mode

   Delta Patcher starts in application mode. Click the switch-mode button at the bottom right of the window (its tooltip reads “Switches between patch creation and patch application modes”). The window now shows four fields.

2. Choose the original file

   Click the folder button next to Original file and select the untouched file, or drag it onto that field.

3. Choose the modified file

   Click the folder button next to Modified file and select your edited version, or drag it onto the field. Double-check you haven’t swapped the two files; a reversed patch turns the modified file back into the original.

4. Choose where to save the patch

   Click the save button next to XDelta patch, pick a folder and enter a file name ending in .xdelta. Delta Patcher asks before overwriting an existing file. A clear name helps users, for example Game (USA) - Translation v1.2.xdelta.

5. Write a description (optional but recommended)

   Anything you type in Description (optional) is saved inside the patch, and any language or symbol is supported. When someone loads the patch in Delta Patcher, it appears in a Patch info tooltip. See writing a useful description.

6. Check the options

   Click the gear button next to Create patch. The defaults suit most patches; the options table explains when to change them.

7. Click Create patch

   The window is disabled while xdelta3 compares the files. When it finishes you’ll see “Patch successfully created!” If an error appears instead, show the log (bottom-right button) to read the message; unreadable files and a destination folder you can’t write to are the usual causes.

Every field has to be filled in except the description. If one is empty, Delta Patcher shows “Fill all the textboxes first!”

Patch creation options

These settings are in the gear menu next to Create patch. They affect how the patch is encoded, not what it does: any setting produces a patch that rebuilds the same modified file.

Secondary compression and compatibility

Secondary compression is part of the xdelta3 format, but not every tool that applies XDelta patches supports every compressor. An xdelta3 build without LZMA support, for example, stops with unavailable secondary compressor: LZMA. Older Delta Patcher releases also had trouble opening patches that used secondary compression, which version 3.0.0 fixed. If your users might use other patchers or old versions, the default none is the safest choice. If everyone uses a current Delta Patcher, lzma is fine.

When to change the source window size

xdelta3 finds matches by searching a “window” of the original file. When data has shifted a long way (for example, a file inserted near the start of a large disc image pushes everything after it along), matches may fall outside a 64 MB window and get stored as new data. The patch still works, but it’s bigger than it needs to be. If a patch for a large file seems much bigger than your actual changes, try 256 MB or 512 MB. Larger windows use more memory while creating the patch.

Writing a useful description

The description is the first thing Delta Patcher users see after loading your patch. Use it to prevent the most common support question, “why doesn’t it work?”:

• What the patch is: project name and version.
• The exact source file: file name, version or revision, and size.
• A checksum of the source: CRC32, MD5, SHA-1 or SHA-256, so users can verify their file before patching.
• A checksum of the result, so users can confirm the output.
• Special instructions, such as the order to apply multiple patches in.

Example Translation v1.2
Apply to: Game (USA).iso, revision 1.0, <size in bytes>
Source SHA-1: <40-character SHA-1 of your original file>
Patched SHA-1: <40-character SHA-1 of your modified file>
Read the included README for credits and known issues.

Most other XDelta tools don’t display this description. Always include the same information in a README file distributed with the patch.

Test your patch before sharing it

A patch that works on your machine can still fail for users if the original you used differs from theirs. Test it the way they’ll use it:

1. Start from a fresh copy of the original

   Use a clean copy, not the working file you edited. Confirm its checksum matches the one in your description.

2. Apply the patch in application mode

   Switch back to application mode, select the copy and your new patch, tick Backup original file, and click Apply patch.

3. Compare the output with your modified file

   Calculate the checksum of the PATCHED file and of your modified file. They must be identical. If they are, the patch rebuilds your work exactly.

Sharing patch files

• Share the patch, not the original. Patches exist so you don’t need to redistribute files you don’t have the right to share. Never bundle the original or the patched file.
• Include a README with the same details as your description, plus credits and a changelog.
• Put the version in the file name, so users can tell updates apart.
• Mention the tool. Say the patch is an XDelta patch and link to the Delta Patcher usage guide or the xdelta3 documentation.
• Publish checksums for the source file, the patched result and the patch itself.

Patch compatibility

Patches created with Delta Patcher are standard xdelta3 (VCDIFF) patches. They can be applied with Delta Patcher on any platform, with the official xdelta3 command-line tool, and with other patchers that support XDelta. The description is stored in the patch’s application header, which other tools simply ignore.

Why is my patch so large?

An XDelta patch is roughly the size of the new data in your modified file. Patches get large when:

• The changed data is compressed or encrypted. A small edit to compressed or encrypted content can change every byte after it, so xdelta3 finds few matches. Editing the data before it’s compressed, where your project allows, gives much smaller patches.
• Data moved further than the source window. Increase Src Window Size.
• The files were swapped or unrelated. If the patch is about as large as the modified file, check that you selected the right original.

Command-line equivalent

To script patch creation, xdelta3 uses the same inputs. -e encodes, -9 sets the compression level, -S the secondary compressor, and -B the source window size in bytes:

xdelta3 -e -9 -S none -s "Game (USA).iso" "Game (USA) [translated].iso" "Translation v1.2.xdelta"

Delta Patcher also passes -A to store the description in the patch’s application header, written as ^* followed by the Base64-encoded text. Patches created without that prefix still work; they just don’t show a Patch info tooltip.