tdm - 3DM XML Tree Differencing and Merging Tool
A command-line tool for structure-aware XML differencing and 3-way merging.
Overview
tdm (Tree Diff/Merge) is a CLI tool that performs operations on XML documents:
- 3-way merge: Merge two modified versions relative to a common ancestor
- Diff generation: Create a compact diff representation showing changes
- Patch application: Apply a diff to reconstruct the modified version
The tool operates on XML tree structure and handles scenarios like moving and editing the same content.
Installation
From Source
From Crates.io
Usage
3-Way Merge
Merge two branches that diverged from a common base:
# Example
# Short form
Options:
-c, --copy-threshold <BYTES>: Minimum size for copy detection (default: 128)- Set to 0 to disable copy detection
- Increase for larger documents to reduce false positives
Diff Generation
Generate a diff showing changes from base to branch:
# Example
# Short form
The diff format uses XML with special copy and insert operations:
New content
Patch Application
Apply a diff to reconstruct the modified version:
# Example
# Short form
Examples
Example 1: Simple Merge
Two reviewers edit a document independently:
# Alice moves a paragraph
# Bob fixes a typo in that paragraph
# Result: Paragraph is moved with the typo fixed
Example 2: Conflict Detection
When changes cannot be automatically merged:
# Output shows conflicts in stderr:
# CONFLICT: Conflicting updates at /document/section[2]/@title
# WARNING: Node deleted in one branch, modified in other
Example 3: Disable Copy Detection
For faster merging on large documents:
Example 4: Diff and Patch Round-Trip
# Generate diff
# Apply diff to reconstruct
# Verify
# (should be identical)
How It Works
Matching Phase
- Parse XML into tree structures
- Match nodes across trees using:
- Content hash equality (exact matches)
- Q-gram distance for fuzzy matching
- Tree structure similarity
Merge Phase
- Detect operations: Insert, delete, move, update, copy
- Resolve conflicts using operation priority table
- Merge content: Combine attribute and text changes
- Output the merged tree
Features
- Structure-aware: Understands XML elements, not just text lines
- Move detection: Tracks content moved between locations
- Copy detection: Identifies duplicated subtrees
- Conflict reporting: Clear error messages with document paths
- Attribute merging: Intelligent attribute-level conflict resolution
Exit Codes
0: Success (merge completed, possibly with warnings)1: Error (parse failure, I/O error, or unresolvable conflicts)
Limitations
- Requires well-formed XML input
- No namespace awareness
- Processing instructions are not preserved (comments ARE preserved)
- Whitespace is normalized (consecutive spaces collapsed)
Use Cases
- Version control: Use as a Git merge driver for XML files
- Document collaboration: Merge changes from multiple reviewers
- Configuration management: Merge XML configuration files
- Data synchronization: Sync XML data across systems
Git Integration
Configure tdm as a Git merge driver:
# In .git/config or ~/.gitconfig
# In .gitattributes
License
Licensed under the GNU Lesser General Public License v2.1 or later (LGPL-2.1-or-later).
Credits
Based on the original 3DM tool by Tancred Lindholm (Helsinki University of Technology, 2001).
Getting Help