No description
  • Rust 87.1%
  • Nix 12.9%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Cyryl Płotnicki 92e27a4e9d
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
Draw image comparisons as real pixels in kitty and Ghostty
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>
2026-11-09 17:16:05 +00:00
.cargo Preview BMP conflicts; page the selection with Page up/down 2026-11-09 14:49:31 +00:00
.forgejo/workflows Make the full mutation run on main gate 2026-11-09 10:03:35 +00:00
examples Draw image comparisons as real pixels in kitty and Ghostty 2026-11-09 17:16:05 +00:00
nix Draw image comparisons as real pixels in kitty and Ghostty 2026-11-09 17:16:05 +00:00
src Draw image comparisons as real pixels in kitty and Ghostty 2026-11-09 17:16:05 +00:00
tests Draw image comparisons as real pixels in kitty and Ghostty 2026-11-09 17:16:05 +00:00
.envrc project init 2025-12-28 19:32:13 +00:00
.gitignore Draw image comparisons as real pixels in kitty and Ghostty 2026-11-09 17:16:05 +00:00
build.rs sort tests 2025-12-29 22:39:13 +00:00
Cargo.lock Draw image comparisons as real pixels in kitty and Ghostty 2026-11-09 17:16:05 +00:00
Cargo.toml Draw image comparisons as real pixels in kitty and Ghostty 2026-11-09 17:16:05 +00:00
CLAUDE.md Set up mutation testing with cargo-mutants 2026-11-08 22:16:06 +00:00
flake.lock Update flake inputs 2026-11-08 22:10:45 +00:00
flake.nix Draw image comparisons as real pixels in kitty and Ghostty 2026-11-09 17:16:05 +00:00
LICENSE Initial commit 2025-12-28 19:09:46 +00:00
PLAN.md Draw image comparisons as real pixels in kitty and Ghostty 2026-11-09 17:16:05 +00:00
README.md Preview BMP conflicts; page the selection with Page up/down 2026-11-09 14:49:31 +00:00
spec.md Draw image comparisons as real pixels in kitty and Ghostty 2026-11-09 17:16:05 +00:00

deescalate

A TUI tool for resolving file sync conflicts, with a focus on Syncthing.

Note: This project is under active development. See PLAN.md for 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:

  1. Scanning directories recursively for conflict files
  2. Analyzing both versions using file-type-specific metadata
  3. Suggesting automatic resolution when one file is clearly newer or identical
  4. Showing diffs when manual decision is needed
  5. 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
PDF .pdf 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 follow
  • screen.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

  1. Create src/filetypes/yourtype.rs
  2. Implement the FileType trait:
    • matches() - detect files by extension
    • extract_metadata() - get comparison data
    • suggest_resolution() - auto-resolve if confident
    • generate_diff() - produce diff output
    • render_details() - TUI display
  3. 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.