- Rust 87.1%
- Nix 12.9%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
All checks were successful
CI / Lint (pull_request) Successful in 29s
CI / Run tests (pull_request) Successful in 34s
CI / Nix checks and package build (pull_request) Successful in 1m6s
CI / Mutation testing (pull_request) Successful in 4m44s
CI / Nix checks and package build (push) Successful in 12s
CI / Lint (push) Successful in 26s
CI / Run tests (push) Successful in 33s
CI / Mutation testing (push) Successful in 12m52s
In kitty and Ghostty the side-by-side copies are now actual pixels through the graphics protocol - a quiet PNG transmit per image and a virtual placement letterboxed into its cell grid, drawn with unicode placeholders so the pictures scroll and reflow with the text. Every other terminal keeps the half-block characters. Neither way queries the terminal, so the keyboard-freeze of the earlier image attempt stays impossible. The terminal is identified by environment alone, and the cell size comes from the window-size ioctl; one that reports no pixel size falls back to half-block characters. Verified against Ghostty's own terminal core: tests/kitty_ghostty.rs runs the binary in a pseudo-terminal at kitty cell geometry, feeds every byte it writes into libghostty-vt, and checks what Ghostty would draw - both images stored with the exact grid and the exact pixels, the placeholders side by side, one transmit per image. The library is built from the commit its bindings were generated from, because the C ABI only froze later. Two bugs this surfaced: ratatui's frame diff takes a long cell symbol for a wide glyph and skips every cell after it, so the transmit-bearing cell must declare unit width; and image::resize silently ignores a wrong dimension because it fits within the box, so the downscale calls resize_exact. Co-Authored-By: GLM 5.3 <noreply@anthropic.com> |
||
| .cargo | ||
| .forgejo/workflows | ||
| examples | ||
| nix | ||
| src | ||
| tests | ||
| .envrc | ||
| .gitignore | ||
| build.rs | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CLAUDE.md | ||
| flake.lock | ||
| flake.nix | ||
| LICENSE | ||
| PLAN.md | ||
| README.md | ||
| spec.md | ||
deescalate
A TUI tool for resolving file sync conflicts, with a focus on Syncthing.
Note: This project is under active development. See
PLAN.mdfor current progress. The documentation below describes the planned feature set.
What It Does
When file synchronization tools like Syncthing detect that a file was modified on multiple devices simultaneously, they create conflict copies rather than silently overwriting changes. This leaves you with files like:
notes.md
notes.sync-conflict-20240115-143052-5CYLJKE.md
deescalate helps you resolve these conflicts by:
- Scanning directories recursively for conflict files
- Analyzing both versions using file-type-specific metadata
- Suggesting automatic resolution when one file is clearly newer or identical
- Showing diffs when manual decision is needed
- Confirming before making any disk changes
Installation
From crates.io
cargo install deescalate
With Nix
nix run github:cyplo/deescalate
Or add to your flake inputs:
{
inputs.deescalate.url = "github:cyplo/deescalate";
}
Usage
deescalate <DIRECTORY>
Scan a directory recursively for conflicts and open the TUI:
deescalate ~/Sync
TUI Controls
| Key | Action |
|---|---|
j/k or ↑/↓ |
Navigate list |
Enter |
Open conflict details |
Space |
Toggle selection |
a |
Auto-resolve selected |
d |
Show diff |
c |
Commit changes |
q |
Quit |
? |
Help |
Supported File Types
| Type | Extensions | Metadata Used | Diff Support |
|---|---|---|---|
| Text | .txt, .md, .json, .yaml, .xml, etc. | Line count, content hash | Full text diff |
| Images | .jpg, .jpeg, .png, .bmp | EXIF dates, dimensions | Side-by-side thumbnails |
| Word | .docx, .doc | Author, modified date, revision | diffoscope |
| Excel | .xlsx, .xls | Author, modified date | diffoscope |
| LibreOffice | .odt, .ods | Author, modified date, edit cycles | diffoscope |
| Author, creation/mod dates | diffoscope | ||
| Unknown | Any other extension | mtime, size, content hash | None (metadata only) |
Unknown file types are handled gracefully using filesystem metadata. You can still resolve conflicts based on modification times, file sizes, and whether the files are identical (via hash comparison).
How Resolution Works
Automatic Resolution
deescalate suggests automatic resolution when:
- One file is clearly newer (modification time differs by >1 hour)
- Files are identical (same content hash)
- One file is empty (keep the non-empty one)
You always confirm before any disk changes are made.
Manual Resolution
When automatic resolution isn't confident, you see:
- Side-by-side metadata comparison
- Full diff view (text files) or structural diff (binary files via diffoscope)
- Options: keep original, keep conflict, keep both, skip
Optional Dependencies
For enhanced diff support:
- difftastic - Syntax-aware diffs for source code
- diffoscope - Deep comparison of binary files (Office docs, PDFs, images)
Without these, deescalate falls back to basic metadata comparison.
Development
Prerequisites
- Rust 1.75+ (uses edition 2024)
- Nix (optional, for reproducible dev environment)
Setup
# With Nix
nix develop
# Or manually
cargo build
Running Tests
This project always uses cargo-nextest for testing. Do not use cargo test.
cargo nextest run
Test Architecture
Tests are data-driven and auto-generated from the tests/test_data/ directory structure:
tests/test_data/
├── text/ # Text file conflict scenarios
│ ├── simple/ # Basic conflict detection
│ ├── multiple/ # Multiple conflicts for same file
│ ├── newer_original/ # Auto-resolution by mtime
│ └── identical/ # Identical content detection
├── image/ # Image conflict scenarios
├── operations/ # Resolutions applied to disk
├── display/ # What the screen shows
└── nested/ # Nested directory handling
Each test case directory contains:
- Conflict files - The actual files to test (original + conflict versions)
expected.toml- The keys a user presses and what should followscreen.snap- The final screen, text and styles
Example expected.toml:
name = "Keep the second of three conflict copies"
description = "b picks the copy labelled [b]; confirming replaces the original with it"
[setup]
keys = ["b", "c", "y"] # pick [b], confirm, apply
[expect.ui]
conflict_count = 0
[expect.files]
content = { "shopping.md" = "oat milk" }
The keys go through the same event loop as the real terminal. See
tests/test_data/SCHEMA.md for every field.
To add a new test case: Create a directory under tests/test_data/ with test files and an expected.toml. The test is automatically discovered and run. Its first run writes screen.snap.new; read it, then accept it with cargo insta accept. When a change alters a screen on purpose, review the differences with cargo insta review.
Tests that need the compiled program in a real terminal, such as its first frame or restoring the terminal on exit, live in tests/ui/pty.rs.
Mutation Testing
cargo mutants # every mutant
jj diff --git --from main > change.diff && cargo mutants --in-diff change.diff
cargo-mutants changes the code one small step at a time and checks that a test notices. Settings are in .cargo/mutants.toml; CI runs it on the lines each pull request changes.
Seeing the Screen
cargo run --example screen -- ~/Sync --keys "j enter" # text
cargo run --example screen -- ~/Sync --svg > screen.svg && resvg screen.svg screen.png
This prints what deescalate would show after those keys, without a terminal. It works on a temporary copy of the directory, so keys that apply resolutions never touch your files.
Project Structure (Target Architecture)
src/
├── main.rs # Entry point, CLI
├── lib.rs # Library root
├── scanner.rs # Find conflicts by pattern
├── types.rs # Core types
├── filetypes/ # File-type handlers (colocated logic)
│ ├── mod.rs # FileType trait, registry
│ ├── text.rs # Text: metadata, diff, resolution
│ ├── image.rs # Images: EXIF, metadata display
│ ├── office.rs # Office docs: OOXML/ODF metadata
│ ├── pdf.rs # PDF metadata
│ └── unknown.rs # Fallback: mtime, size, hash only
├── resolver.rs # Resolution logic
├── tui/ # Terminal UI
│ ├── app.rs # App state
│ ├── scan_view.rs # Conflict list
│ ├── detail_view.rs # Diff/metadata view
│ └── confirm_view.rs # Confirmation
└── operations.rs # File operations
See PLAN.md for implementation progress.
Adding a New File Type
- Create
src/filetypes/yourtype.rs - Implement the
FileTypetrait:matches()- detect files by extensionextract_metadata()- get comparison datasuggest_resolution()- auto-resolve if confidentgenerate_diff()- produce diff outputrender_details()- TUI display
- Register in
src/filetypes/mod.rs
All file-type logic is colocated in one file for easy understanding and modification.
Syncthing Conflict Format
Syncthing creates conflict files with this naming pattern:
<filename>.sync-conflict-<YYYYMMDD>-<HHMMSS>-<DEVICEID>.<ext>
- Date and time indicate when the conflict was detected
- Device ID (7 chars) identifies which device created the conflicting version
License
AGPL-3.0
Contributing
Contributions welcome! Please read the spec.md for detailed requirements before implementing features.