git-delta 0.20.0

A syntax-highlighting pager for git
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
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
// Emit per-line diff metadata as an OSC sequence, so that a host application
// (e.g. lazygit) can map a rendered diff row back to its patch-space identity
// (file, type, new-file line, old-file line) without re-parsing the rendered
// output. delta restructures the diff (drops the +/- markers, conveys the side
// by color, adds gutters), so that identity cannot be recovered from the
// painted text alone -- the pager, which still has it at render time, states it.
//
// This is gated on the OSC1717 environment variable: the host advertises the
// protocol versions it understands and delta emits the highest mutually-
// understood one. When the variable is unset (i.e. delta is not running under
// such a host) nothing is emitted, so a raw terminal / less / tmux see a normal
// diff.
//
// The OSC number 1717 was chosen after auditing the OSC allocations of the major
// terminal emulators (xterm, VTE, kitty, foot, WezTerm, iTerm2, Windows Terminal,
// Ghostty, VS Code, ConEmu, urxvt); none of them interpret it, so a terminal that
// is not a participating host skips it harmlessly.

use std::io::{self, Write};
use std::sync::OnceLock;

use crate::delta::{DiffType, State};

/// Highest protocol version this build of delta knows how to emit.
const SUPPORTED_VERSION: u32 = 1;

const OSC: &str = "\x1b]1717";
const ST: &str = "\x1b\\";

/// The highest version in the host's advertised list (e.g. "V1" or "V1,V2")
/// that this build also understands, or `None` if the lists are disjoint.
fn pick_version(advertised: &str) -> Option<u32> {
    advertised
        .split(',')
        .filter_map(|v| v.trim().strip_prefix('V')?.parse::<u32>().ok())
        .filter(|v| *v <= SUPPORTED_VERSION)
        .max()
}

/// The protocol version to emit, negotiated against the host's advertised list
/// in `OSC1717` (e.g. "V1" or "V1,V2"), or `None` when no host is asking (the
/// variable is unset) so delta stays silent.
pub fn negotiated_version() -> Option<u32> {
    static VERSION: OnceLock<Option<u32>> = OnceLock::new();
    *VERSION.get_or_init(|| pick_version(&std::env::var("OSC1717").ok()?))
}

/// The handshake record: a version-only OSC 1717 (no further fields) that a
/// conforming pager emits once, as its first output, to announce it speaks the
/// protocol (see the spec, ยง4.4). It lets a host probe delta on an empty diff --
/// which emits no per-line records -- and tell "speaks the protocol" apart from
/// "unsupported pager". Empty when no host negotiated a version.
pub fn handshake() -> String {
    negotiated_version().map_or(String::new(), handshake_for_version)
}

fn handshake_for_version(version: u32) -> String {
    format!("{OSC};{version}{ST}")
}

/// Tracks the current old-/new-file line numbers within a hunk and formats the
/// per-line OSC sequence. One instance is held by the `Painter` (when emission
/// is negotiated) and re-seeded at every hunk header.
pub struct DiffLineMetadata {
    version: u32,
    old_line: usize,
    new_line: usize,
    file: String,
    /// The record (`type_char`, `new_line`, `old_line`) most recently emitted
    /// for a primary content line, so a wrapped continuation row can re-emit it
    /// without advancing the counters. Set by every primary line; read by the
    /// wrapped row(s) that immediately follow it.
    last_record: Option<(char, usize, Option<usize>)>,
}

impl DiffLineMetadata {
    /// Returns an emitter iff the host negotiated a protocol version.
    pub fn from_env() -> Option<Self> {
        negotiated_version().map(|version| Self {
            version,
            old_line: 0,
            new_line: 0,
            file: String::new(),
            last_record: None,
        })
    }

    /// A version-1 emitter regardless of environment. Tests cannot go through
    /// `from_env`: the negotiated version is cached in a process-wide OnceLock,
    /// so an env var set by one test would leak into all others.
    #[cfg(test)]
    pub fn v1_for_tests() -> Self {
        Self {
            version: 1,
            old_line: 0,
            new_line: 0,
            file: String::new(),
            last_record: None,
        }
    }

    /// Seed the line-number counters and file path at a hunk header. Mirrors
    /// `LineNumbersData::initialize_hunk`: the first entry is the old-file start,
    /// the last is the new-file start.
    pub fn initialize_hunk(&mut self, line_numbers: &[(usize, usize)], file: String) {
        self.old_line = line_numbers[0].0;
        self.new_line = line_numbers[line_numbers.len() - 1].0;
        self.file = file;
    }

    /// Advance the counters for `state` and return the OSC sequence to prepend
    /// to that content line, or an empty string for states that carry no
    /// metadata (headers and -- in this prototype -- combined/merge diffs). The
    /// counter arithmetic mirrors `line_numbers::linenumbers_and_styles`.
    ///
    /// A wrapped continuation row (`Hunk*Wrapped`, produced when side-by-side
    /// wraps a long line into several output rows) re-emits the record of the
    /// primary line it continues, *without* advancing the counters. delta emits
    /// each wrapped row as a distinct output line, so a host sees them as
    /// distinct lines and needs the identity on each -- otherwise acting on a
    /// continuation row, or treating the wrapped line as one block when
    /// navigating, breaks.
    pub fn osc_for_line(&mut self, state: &State) -> String {
        use State::*;
        let record = match state {
            HunkZero(DiffType::Unified, _) => {
                let record = ('c', self.new_line, None);
                self.old_line += 1;
                self.new_line += 1;
                record
            }
            HunkPlus(DiffType::Unified, _) => {
                let record = ('a', self.new_line, None);
                self.new_line += 1;
                record
            }
            HunkMinus(DiffType::Unified, _) => {
                // A deletion sits at the new-file position the new-file counter
                // currently holds (it has not advanced past the preceding
                // context/added lines); it carries both numbers.
                let record = ('d', self.new_line, Some(self.old_line));
                self.old_line += 1;
                record
            }
            HunkZeroWrapped | HunkMinusWrapped | HunkPlusWrapped => match self.last_record {
                Some(record) => record,
                None => return String::new(),
            },
            _ => return String::new(),
        };
        self.last_record = Some(record);
        let (type_char, new_line, old_line) = record;
        let old_field = old_line.map_or(String::new(), |n| n.to_string());
        format!(
            "{OSC};{version};{type_char};{new_line};{old_field};{file}{ST}",
            version = self.version,
            file = self.file,
        )
    }

    /// The `h` (hunk-header) record for the current hunk. `initialize_hunk` has
    /// just seeded `new_line` with the hunk's new-file start -- which is the
    /// hunk's first line (spec ยง5.2) -- so it is in hand exactly when the hunk
    /// header is rendered. `old-line` is empty on a header.
    pub fn osc_for_hunk_header(&self) -> String {
        self.header_osc('h', Some(self.new_line), &self.file)
    }

    /// The `f` (file-header) record. It carries no line numbers (spec ยง5.5):
    /// delta renders the file header (the boxed file name) as soon as it parses
    /// the `+++` line, *before* it has seen the first `@@`, so the file's first
    /// hunk line is not known here. The path is supplied by the caller because
    /// the emitter only learns it at the first hunk header.
    pub fn osc_for_file_header(&self, file: &str) -> String {
        self.header_osc('f', None, file)
    }

    fn header_osc(&self, type_char: char, new_line: Option<usize>, file: &str) -> String {
        let new_field = new_line.map_or(String::new(), |n| n.to_string());
        format!(
            "{OSC};{version};{type_char};{new_field};;{file}{ST}",
            version = self.version,
        )
    }

    /// The `C` (commit) record marking the first row of a commit in `git log`
    /// output. A commit is no line of any file, so it carries no line numbers
    /// and states its id where a diff row states its file.
    pub fn osc_for_commit(&self, commit: &str) -> String {
        format!("{OSC};{version};C;;;{commit}{ST}", version = self.version)
    }
}

/// The commit a commit-header line names: the first token after whatever
/// `--commit-regex` matched, which is where git prints it. `None` when there is
/// no such token or it is no hash, so a custom regex matching something else
/// yields no record rather than a wrong one.
pub fn commit_id(line: &str, marker_end: usize) -> Option<&str> {
    let commit = line.get(marker_end..)?.split_whitespace().next()?;
    let is_hash = commit.len() >= 4 && commit.chars().all(|c| c.is_ascii_hexdigit());
    is_hash.then_some(commit)
}

/// A `Write` adapter that injects `prefix` at the start of the stream and after
/// every newline. delta draws a file/hunk header as a *multi-row* decoration --
/// an underline under the file name, a box around the hunk header -- written
/// straight to the output by the `draw` functions. To tag the whole block we
/// wrap that writer so every row the decoration emits is preceded by the
/// header's record, the same "every output row carries the record" rule that
/// wrapped content rows follow (spec ยง6.3/ยง6.4).
struct OscLinePrefixer<'a> {
    inner: &'a mut dyn Write,
    prefix: &'a str,
    at_line_start: bool,
}

impl Write for OscLinePrefixer<'_> {
    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
        for chunk in buf.split_inclusive(|&b| b == b'\n') {
            if self.at_line_start {
                self.inner.write_all(self.prefix.as_bytes())?;
            }
            self.inner.write_all(chunk)?;
            self.at_line_start = chunk.ends_with(b"\n");
        }
        Ok(buf.len())
    }

    fn flush(&mut self) -> io::Result<()> {
        self.inner.flush()
    }
}

/// Run `draw`, prefixing every output row it writes with `osc` (a header
/// record). With `osc` empty the closure writes to `writer` untouched, so the
/// output stays byte-for-byte identical to stock delta.
pub fn write_with_header_osc(
    writer: &mut dyn Write,
    osc: &str,
    draw: impl FnOnce(&mut dyn Write) -> io::Result<()>,
) -> io::Result<()> {
    if osc.is_empty() {
        draw(writer)
    } else {
        let mut prefixer = OscLinePrefixer {
            inner: writer,
            prefix: osc,
            at_line_start: true,
        };
        draw(&mut prefixer)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::delta::{DiffType, State};

    fn emitter() -> DiffLineMetadata {
        let mut md = DiffLineMetadata::v1_for_tests();
        // @@ -1,3 +1,4 @@ : old start 1, new start 1.
        md.initialize_hunk(&[(1, 3), (1, 4)], "f.txt".to_owned());
        md
    }

    #[test]
    fn test_handshake_is_version_only() {
        // The handshake carries only the version (no further fields), so a host tells
        // it apart from a per-line record by field count.
        assert_eq!(handshake_for_version(1), "\x1b]1717;1\x1b\\");
    }

    #[test]
    fn test_hunk_header_record_carries_the_hunks_first_line() {
        // `h` carries the hunk's first new-file line (just seeded by
        // initialize_hunk) and no old-line. Emitting it does not advance the
        // counters: the hunk's first content line reports the same line.
        let mut md = emitter();
        assert_eq!(md.osc_for_hunk_header(), "\x1b]1717;1;h;1;;f.txt\x1b\\");
        assert_eq!(
            md.osc_for_line(&State::HunkZero(DiffType::Unified, None)),
            "\x1b]1717;1;c;1;;f.txt\x1b\\"
        );
    }

    #[test]
    fn test_file_header_record_has_no_line_numbers() {
        // `f` never carries line numbers (spec ยง5.5): delta draws the file
        // header before it has seen the first `@@`. The path comes from the
        // caller, because the emitter's own state is only seeded at the first
        // hunk header.
        let md = emitter();
        assert_eq!(
            md.osc_for_file_header("src/foo.rs"),
            "\x1b]1717;1;f;;;src/foo.rs\x1b\\"
        );
    }

    #[test]
    fn test_header_record_prefixes_every_row_of_a_multi_row_block() {
        // A file/hunk header is a multi-row decoration (an underlined name, a
        // box); every row of the block carries the record (spec ยง6.4). With no
        // record the drawn bytes pass through untouched.
        let draw = |w: &mut dyn io::Write| -> io::Result<()> {
            write!(w, "โ”€โ”€โ”\n1:โ”‚\nโ”€โ”€โ”˜\n")
        };

        let mut tagged = Vec::new();
        write_with_header_osc(&mut tagged, "[osc]", draw).unwrap();
        assert_eq!(
            String::from_utf8(tagged).unwrap(),
            "[osc]โ”€โ”€โ”\n[osc]1:โ”‚\n[osc]โ”€โ”€โ”˜\n"
        );

        let mut untouched = Vec::new();
        write_with_header_osc(&mut untouched, "", draw).unwrap();
        assert_eq!(String::from_utf8(untouched).unwrap(), "โ”€โ”€โ”\n1:โ”‚\nโ”€โ”€โ”˜\n");
    }

    #[test]
    fn test_commit_record_carries_the_commit_id() {
        // `C` marks the first row of a commit in `git log` output. It is no line
        // of any file, so it carries no line numbers; the commit id goes where a
        // diff row carries its file.
        let md = emitter();
        assert_eq!(
            md.osc_for_commit("dbb7c03c3f306c0b12ce003358e1fd17c3fd2701"),
            "\x1b]1717;1;C;;;dbb7c03c3f306c0b12ce003358e1fd17c3fd2701\x1b\\"
        );
    }

    #[test]
    fn test_commit_id_is_the_token_after_what_marks_the_line() {
        // Whatever `--commit-regex` matched identifies the line; the commit is
        // the first token after it, so decorations stay out of it.
        assert_eq!(
            commit_id("commit dbb7c03 (HEAD -> main, origin/main)", 7),
            Some("dbb7c03")
        );
        assert_eq!(commit_id("commit ", 7), None);
        assert_eq!(commit_id("commit not-a-hash", 7), None);
    }

    #[test]
    fn test_wrapped_rows_reemit_the_primary_record_without_advancing() {
        let mut md = emitter();
        let zero = md.osc_for_line(&State::HunkZero(DiffType::Unified, None));
        let plus = md.osc_for_line(&State::HunkPlus(DiffType::Unified, None));
        let plus_w1 = md.osc_for_line(&State::HunkPlusWrapped);
        let plus_w2 = md.osc_for_line(&State::HunkPlusWrapped);
        let zero_after = md.osc_for_line(&State::HunkZero(DiffType::Unified, None));

        assert_eq!(zero, "\x1b]1717;1;c;1;;f.txt\x1b\\");
        assert_eq!(plus, "\x1b]1717;1;a;2;;f.txt\x1b\\");
        // Continuation rows re-emit the addition's record verbatim.
        assert_eq!(plus_w1, plus);
        assert_eq!(plus_w2, plus);
        // The wrapped rows must not advance the counters: the next content line
        // is new-line 3, not 5.
        assert_eq!(zero_after, "\x1b]1717;1;c;3;;f.txt\x1b\\");
    }

    #[test]
    fn test_wrapped_deletion_reemits_both_line_numbers() {
        let mut md = emitter();
        let minus = md.osc_for_line(&State::HunkMinus(DiffType::Unified, None));
        let minus_w = md.osc_for_line(&State::HunkMinusWrapped);
        assert_eq!(minus, "\x1b]1717;1;d;1;1;f.txt\x1b\\");
        assert_eq!(minus_w, minus);
    }

    #[test]
    fn test_wrapped_row_with_no_preceding_primary_emits_nothing() {
        let mut md = emitter();
        assert_eq!(md.osc_for_line(&State::HunkZeroWrapped), "");
    }

    #[test]
    fn test_pick_version() {
        assert_eq!(pick_version("V1"), Some(1));
        assert_eq!(pick_version("V1,V2"), Some(1)); // we cap at SUPPORTED_VERSION
        assert_eq!(pick_version("V2,V3"), None); // disjoint with what we emit
        assert_eq!(pick_version(""), None);
        assert_eq!(pick_version("garbage"), None);
    }

    #[test]
    fn test_unified_context_addition_deletion_sequence() {
        // A modification hunk in normal (unified) mode: one context line, two
        // deletions, two additions, then a trailing context line. Two consecutive
        // deletions share a new-line and are told apart only by old-line; a
        // deletion sits at the new-file position the counter currently holds,
        // while context and additions advance it.
        let mut md = emitter();
        assert_eq!(
            md.osc_for_line(&State::HunkZero(DiffType::Unified, None)),
            "\x1b]1717;1;c;1;;f.txt\x1b\\"
        );
        assert_eq!(
            md.osc_for_line(&State::HunkMinus(DiffType::Unified, None)),
            "\x1b]1717;1;d;2;2;f.txt\x1b\\"
        );
        assert_eq!(
            md.osc_for_line(&State::HunkMinus(DiffType::Unified, None)),
            "\x1b]1717;1;d;2;3;f.txt\x1b\\"
        );
        assert_eq!(
            md.osc_for_line(&State::HunkPlus(DiffType::Unified, None)),
            "\x1b]1717;1;a;2;;f.txt\x1b\\"
        );
        assert_eq!(
            md.osc_for_line(&State::HunkPlus(DiffType::Unified, None)),
            "\x1b]1717;1;a;3;;f.txt\x1b\\"
        );
        assert_eq!(
            md.osc_for_line(&State::HunkZero(DiffType::Unified, None)),
            "\x1b]1717;1;c;4;;f.txt\x1b\\"
        );
    }

    #[test]
    fn test_initialize_hunk_reseeds_the_counters() {
        // A second hunk re-seeds the old/new starts, so the counters jump to the
        // new hunk rather than continuing from the previous one.
        let mut md = emitter();
        md.initialize_hunk(&[(20, 3), (25, 4)], "f.txt".to_owned());
        assert_eq!(
            md.osc_for_line(&State::HunkZero(DiffType::Unified, None)),
            "\x1b]1717;1;c;25;;f.txt\x1b\\"
        );
        assert_eq!(
            md.osc_for_line(&State::HunkMinus(DiffType::Unified, None)),
            "\x1b]1717;1;d;26;21;f.txt\x1b\\"
        );
    }

    #[test]
    fn test_whole_file_deletion_sits_at_new_line_zero() {
        // A deleted file's hunk header is `@@ -1,N +0,0 @@`, so the new-file
        // start is 0 and every deletion reports new-line 0.
        let mut md = emitter();
        md.initialize_hunk(&[(1, 3), (0, 0)], "gone.txt".to_owned());
        assert_eq!(
            md.osc_for_line(&State::HunkMinus(DiffType::Unified, None)),
            "\x1b]1717;1;d;0;1;gone.txt\x1b\\"
        );
        assert_eq!(
            md.osc_for_line(&State::HunkMinus(DiffType::Unified, None)),
            "\x1b]1717;1;d;0;2;gone.txt\x1b\\"
        );
    }

    #[test]
    fn test_path_may_contain_semicolons() {
        // The path is the last field, so it may itself contain ';': a host splits
        // into at most five fields and takes the remainder as the path.
        let mut md = emitter();
        md.initialize_hunk(&[(1, 1), (1, 1)], "weird;name.txt".to_owned());
        assert_eq!(
            md.osc_for_line(&State::HunkPlus(DiffType::Unified, None)),
            "\x1b]1717;1;a;1;;weird;name.txt\x1b\\"
        );
    }
}