dead-ringer 1.2.1

A terminal-based binary diff viewer with hex and ASCII representations
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84

[![Build](https://github.com/ztroop/dead-ringer/actions/workflows/build.yml/badge.svg)](https://github.com/ztroop/dead-ringer/actions/workflows/build.yml)

# dead-ringer

A Rust-based command-line utility designed to compare two binary files, displaying differences by showcasing both hexadecimal and ASCII representations of the differing bytes.

![demo](./assets/demo.png)

## Features

- CLI Diff Viewer for Hex and ASCII.
- Color highlighting for different data types to enhance readability.
- Keyboard navigation enables interactive exploration of differences.
- Search for hex byte sequences (`/`) or ASCII strings (`?`), with `n`/`N` to cycle through matches.
- Displays byte offset for focused data, aiding in precise location identification.

## Installation

```sh
cargo install dead-ringer
```

## Usage

```
Usage: dring <file1> <file2>

Arguments:
  <file1>  Path to the first binary file
  <file2>  Path to the second binary file
```

## Keybindings

| Key | Action |
|-----|--------|
| `h/j/k/l` or arrow keys | Navigate |
| `/` | Search by hex bytes |
| `?` | Search by ASCII string |
| `Enter` | Submit search |
| `Tab` | Toggle between hex/ASCII search |
| `n` | Next match |
| `N` | Previous match |
| `v` | Enter visual selection mode |
| `y` | Copy selection as hex (OSC 52) |
| `Y` | Copy selection as ASCII (OSC 52) |
| `Esc` | Cancel search / selection |
| `q` | Quit |

### Clipboard (tmux)

Copy to clipboard uses the [OSC 52](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h3-Operating-System-Commands) escape sequence, which works natively in most modern terminals (iTerm2, kitty, foot, WezTerm, etc.). If you run inside **tmux 3.3+**, add the following to `~/.tmux.conf` so the sequence is forwarded to the outer terminal:

```
set -g allow-passthrough on
```

Then reload with `tmux source-file ~/.tmux.conf`.

## Examples

The [`examples/`](./examples) directory contains pre-built binary file pairs for testing:

```sh
cargo run -- examples/simple_v1.bin examples/simple_v2.bin
cargo run -- examples/firmware_v1.bin examples/firmware_v2.bin
```

See [`examples/README.md`](./examples/README.md) for the full list of test pairs.

## Color Reference

|Type of Byte|Color|
|---|---|
|NULL|![#555753](https://placehold.co/10x10/555753/555753.png) Gray|
|OFFSET|![#555753](https://placehold.co/10x10/555753/555753.png) Gray|
|ASCII Printable|![#06989a](https://placehold.co/10x10/06989a/06989a.png) Cyan|
|ASCII Whitespace|![#4e9a06](https://placehold.co/10x10/4e9a06/4e9a06.png) Green|
|ASCII Other|![#4e9a06](https://placehold.co/10x10/4e9a06/4e9a06.png) Green|
|Non-ASCII|![#c4a000](https://placehold.co/10x10/c4a000/c4a000.png) Yellow|

## Alternatives

If you're looking for a full-featured Hex/ASCII viewer, check out [Hexyl](https://github.com/sharkdp/hexyl)!