andras/reconcile
1
0
Fork 0
Code Issues Pull requests 6 Projects Releases Packages Wiki Activity Actions

Generate docs

Browse source
This commit is contained in:
Andras Schmelczer 2025-07-05 10:13:51 +01:00
parent 7d242e1999
commit 24e027517f
6 changed files with 325 additions and 116 deletions
Download patch file Download diff file Expand all files Collapse all files

87
examples/website/README.md
View file

@ -1,59 +1,54 @@
# Reconcile: conflict-free 3-way text merging
# Reconcile: Interactive Demo
[![Check](https://github.com/schmelczer/reconcile/actions/workflows/check.yml/badge.svg)](https://github.com/schmelczer/reconcile/actions/workflows/check.yml)
[![Publish to GitHub Pages](https://github.com/schmelczer/reconcile/actions/workflows/gh-pages.yml/badge.svg)](https://github.com/schmelczer/reconcile/actions/workflows/gh-pages.yml)
This is the interactive demo website for the Reconcile library. Visit [schmelczer.dev/reconcile](https://schmelczer.dev/reconcile) to try it out.
> `diff3` but with automatic conflict resolution.
## About the Demo
Reconcile is a Rust and JavaScript (through WebAssembly) library for merging text without user intervention.
The demo allows you to:
```rust
use reconcile::{reconcile, BuiltinTokenizer};
- Enter three text versions (parent, left, right)
- See the reconciled result in real-time
- Experiment with different tokenization strategies
- Observe how cursor positions are updated during merging
- View the history of operations that led to the result
let parent = "Merging text is hard!";
let left = "Merging text is easy!";
let right = "With reconcile, merging documents is hard!";
## Features Demonstrated
let deconflicted = reconcile(parent, &left.into(), &right.into(), &*BuiltinTokenizer::Word);
assert_eq!(deconflicted.apply().text(), "With reconcile, merging documents is easy!");
- **Conflict-free merging**: No conflict markers in the output
- **Cursor tracking**: See how cursor positions are automatically updated
- **Different tokenizers**: Compare word-level vs. character-level tokenization
- **Operation history**: Understand the merge process step-by-step
## Running Locally
```bash
# Build the WASM module first
cd ../..
wasm-pack build --target web
# Install dependencies and run the demo
cd examples/website
npm install
npm run dev
```
## Features
## Usage Examples
- Conflict-free output (no more git conflict markers)
- Support for updating cursor/selection positions
- Pluggable tokenizer
- Full UTF-8 support
- WASM
Try these examples in the demo:
## Motivation
### Basic merge
- **Parent**: "Hello world"
- **Left**: "Hello beautiful world"
- **Right**: "Hi world"
- **Result**: "Hi beautiful world"
Sometimes documents get edited concurrently by multiple users (or the same user from multiple devices) resulting in divergent changes.
### Cursor tracking
- **Parent**: "The quick brown fox"
- **Left**: "The very quick brown fox" (cursor at position 4)
- **Right**: "The quick red fox" (cursor at position 10)
- **Result**: Cursors automatically repositioned
To allow for offline editing, we could use CRDTs or Operational Transformation (OT) to come to a consistent resolution of the competing version. However, this requires capturing all user actions: insertions, deletes, move, copies, and pastes. In some application, this is trivial if the document can only be edited through an editor that's in our control. But this isn't always the case. Users enjoy composable systems that don't lock them in. For example, one of the unique selling points of Obsidian is to provide an editor experience over a folder Markdown files leaving the user free to change their technology of choice on a whim.
### Character-level merging
Switch to character tokenizer for fine-grained merging of individual characters rather than whole words.
This means that files can be edited out-of-channel and the only information a text synchronisation system can know is the current content of each tracked file. This is the same problem as what Git and similar version control systems solve. Although the problem is similar, there's a relevant difference between syncing source code and personal notes: in the case of the former, a semantically incorrect conflict resolution can wreak havoc in a code base, or worse, introduce a correctness bug unnoticed. Text notes are different though, humans are well-equipped to finding the signal in a noisy environment and "bad merges" might result in a clumsy sentence but the reader will likely still understand the gist and can fix it if necessary.
> There are domains of human text which are less tolerant of mis-merges: for instance, a two conflicting changes to a contract could result in a term getting negated in different ways from both sides, resulting in a double-negation, thus, unknowingly changing the meaning.
## Architecture
## Development
### Install [nvm](https://github.com/nvm-sh/nvm)
- `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash`
- `nvm install 22`
- `nvm use 22`
- Optionally set the system-wide default: `nvm alias default 22`
### Set up Rust
- Install [`rustup`](https://rustup.rs): `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
- `cargo install wasm-pack cargo-insta cargo-edit`
#### Publish new version
```sh
scripts/bump-version.sh patch
```
For more examples and detailed documentation, see the [main README](../../README.md).