# Advanced Usage (Python)
## Edit Provenance
Track which changes came from where using `reconcile_with_history`:
```python
from reconcile_text import reconcile_with_history
result = reconcile_with_history(
"Hello world",
"Hello beautiful world",
"Hi world",
)
print(result["text"]) # "Hi beautiful world"
print(result["history"]) #
# [
# {"text": "Hello", "history": "RemovedFromRight"},
# {"text": "Hi", "history": "AddedFromRight"},
# {"text": " beautiful", "history": "AddedFromLeft"},
# {"text": " ", "history": "Unchanged"},
# {"text": "world", "history": "Unchanged"},
# ]
```
## Tokenization Strategies
`reconcile-text` offers different approaches to split text for merging:
- **Word tokenizer** (`"Word"`) - Splits on word boundaries (recommended for prose)
- **Character tokenizer** (`"Character"`) - Individual characters (fine-grained control)
- **Line tokenizer** (`"Line"`) - Line-by-line (similar to `git merge` or more precisely [`git merge-file`](https://git-scm.com/docs/git-merge-file))
- **Markdown tokenizer** (`"Markdown"`) - Splits on Markdown structural boundaries (headings, list items, paragraphs)
```python
from reconcile_text import reconcile
result = reconcile("abc", "axc", "abyc", "Character")
print(result["text"]) # "axyc"
```
## Cursor Tracking
`reconcile-text` automatically tracks cursor positions through merges, which is useful for collaborative editors. Selections can be tracked by providing them as a pair of cursors.
```python
from reconcile_text import reconcile
result = reconcile(
"Hello world",
{
"text": "Hello beautiful world",
"cursors": [{"id": 1, "position": 6}], # After "Hello "
},
{
"text": "Hi world",
"cursors": [{"id": 2, "position": 0}], # At the beginning
},
)
# Result: "Hi beautiful world" with repositioned cursors
print(result["text"]) # "Hi beautiful world"
print(result["cursors"]) # [{"id": 2, "position": 0}, {"id": 1, "position": 3}]
```
> The `cursors` list is sorted by character position (not IDs).
## Compact Diffs
Generate and apply compact diff representations:
```python
from reconcile_text import diff, undiff
original = "Hello world"
changed = "Hello beautiful world"
# Generate a compact diff
d = diff(original, changed)
print(d) # [5, ' beautiful world']
# Reconstruct the changed text from the diff
reconstructed = undiff(original, d)
assert reconstructed == changed
```
Diff entries are positive integers (retain N characters), negative integers (delete N characters), and strings (insert text).
## File Merging Example
For a complete file-merging CLI (a trivial `git merge-file`), see [`examples/merge_file.py`](../examples/merge_file.py).