gitlimes 0.1.0

Fast, low-memory git history CLI: colored log, branches, author stats and a unicode commit graph
Documentation
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
//! The only module that knows git is a subprocess.
//!
//! Commits are read one record at a time into a buffer that is reused for every
//! record, so peak memory is the size of the largest single commit record and
//! does not grow with history length.

use std::borrow::Cow;
use std::io::{self, BufRead, BufReader};
use std::process::{Child, ChildStdout, Command, Stdio};

/// Field separator.
///
/// NUL, because git refuses outright to store one anywhere in a commit
/// object - not just in the message. `git fast-import`, the most permissive,
/// purely byte-oriented way to construct a commit, rejects a NUL embedded in
/// an author line outright ("missing < in ident string"), because its ident
/// parser is itself NUL-terminated C-string based. The obvious-looking
/// alternatives are not safe: git happily stores 0x1f or 0x1e in a subject or
/// an author name if you commit one via `-F` or a raw ident line, and they
/// then split the record and silently truncate or drop it. See `WHO_FORMAT`
/// for the one place this project got that wrong before.
pub const FS: char = '\0';

/// Record separator for every format string in this crate: each one emits
/// exactly one physical line per record, and no field any of them use -
/// `%s`, `%an`, `%ae`, ref names - can contain an embedded newline, since git
/// collapses `%s` to one line and forbids newlines in author idents and ref
/// names outright.
pub const LINE: u8 = b'\n';

/// Field order must match `Commit::parse`. Framed by [`LINE`], separated by
/// [`FS`], so no byte a commit can carry will break it.
pub const LOG_FORMAT: &str = "--format=%H%x00%h%x00%P%x00%an%x00%at%x00%D%x00%s";

/// One line per commit: author name, email and timestamp, separated by
/// [`FS`]. With `--numstat`, git appends this commit's changed-file lines
/// after it - each `<added>\t<removed>\t<path>`, with **no** [`FS`] byte in
/// them, since a path cannot contain NUL either. That is what lets a reader
/// tell a commit's own line from a trailing stat line unambiguously: a
/// commit line has exactly two [`FS`] bytes, a stat line has none.
///
/// This used to lead with a reserved `%x1e` byte and frame records on that
/// byte directly, which broke silently: an author name or email containing a
/// literal `0x1e` - which git stores without complaint - split the record
/// early and dropped the commit. Unlike a NUL, nothing stops git from storing
/// that byte in an ident, so it was never a safe delimiter here.
pub const WHO_FORMAT: &str = "--format=%an%x00%ae%x00%at";

/// Number of fields in [`LOG_FORMAT`].
const LOG_FIELDS: usize = 7;

/// Borrows every field out of the reader's buffer; nothing here is owned.
pub struct Commit<'a> {
    pub hash: &'a str,
    pub short: &'a str,
    pub parents: &'a str,
    pub author: &'a str,
    pub timestamp: &'a str,
    pub refs: &'a str,
    pub subject: &'a str,
}

impl<'a> Commit<'a> {
    pub fn parse(rec: &'a str) -> Option<Commit<'a>> {
        // splitn, not split: the subject is last, so anything separator-shaped
        // inside it stays part of the subject instead of spilling into a field
        // that no longer exists.
        let mut f = rec.splitn(LOG_FIELDS, FS);
        Some(Commit {
            hash: f.next()?,
            short: f.next()?,
            parents: f.next()?,
            author: f.next()?,
            timestamp: f.next()?,
            refs: f.next()?,
            subject: f.next()?,
        })
    }

    pub fn parent_iter(&self) -> impl Iterator<Item = &'a str> {
        self.parents.split_whitespace()
    }
}

pub fn git(args: &[&str]) -> Command {
    let mut c = Command::new("git");
    c.args(args).stdout(Stdio::piped()).stderr(Stdio::inherit());
    c
}

/// Base argv for a `git log` call using one of this crate's format strings.
///
/// Always requests `--encoding=UTF-8`. A commit's message and subject are
/// stored in whatever charset `i18n.commitEncoding` names - git defaults to
/// UTF-8, but a repository is free to set something else - and without this
/// flag git emits the raw bytes verbatim. This project's whole pipeline is
/// `&str`, so those bytes then go through a lossy UTF-8 conversion and any
/// non-ASCII character is silently replaced with U+FFFD. `--encoding=UTF-8`
/// makes git do the transcoding correctly instead, and is a verified no-op
/// on an ordinary UTF-8 repository - passing it costs nothing there.
///
/// This does **not** cover the author or committer identity: verified against
/// a raw, hand-built commit object, `--encoding` only ever transcodes the
/// message body, never `%an`/`%ae`/`%cn`/`%ce`. A non-UTF-8 author name or
/// email can still come through as whatever bytes it was written in; this
/// is a documented limitation (see the README), not silently unhandled.
///
/// Centralised here, rather than repeated at each call site, so a future
/// caller cannot forget it the way `WHO_FORMAT` once forgot NUL-safe framing.
pub fn log_argv(format: &str) -> Vec<String> {
    vec![
        "log".to_string(),
        format.to_string(),
        "--encoding=UTF-8".to_string(),
    ]
}

/// Raised when git itself ran and exited non-zero.
///
/// git has already written its own diagnostic to stderr, so this carries only
/// the code, for a caller that wants to exit with it. It travels inside an
/// `io::Error` so every function here can keep returning `io::Result` - a
/// library must never call `process::exit` and kill its caller.
#[derive(Debug, Clone, Copy)]
pub struct GitExit(pub i32);

impl std::fmt::Display for GitExit {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "git exited with status {}", self.0)
    }
}

impl std::error::Error for GitExit {}

/// Recovers git's exit code from an error produced by this module, if that is
/// what the error is.
pub fn git_exit_code(e: &io::Error) -> Option<i32> {
    e.get_ref()
        .and_then(|inner| inner.downcast_ref::<GitExit>())
        .map(|g| g.0)
}

fn spawn_error(e: io::Error) -> io::Error {
    if e.kind() == io::ErrorKind::NotFound {
        // The likeliest first-run failure by a wide margin, and the bare
        // "program not found" says nothing about what to install.
        return io::Error::new(
            io::ErrorKind::NotFound,
            "git was not found on PATH; gitlimes runs git and needs it installed",
        );
    }
    e
}

/// Runs a git command and returns its whole stdout. Only for commands whose
/// output is bounded by ref count, never by history length.
pub fn capture(args: &[&str]) -> io::Result<String> {
    let out = git(args)
        .stderr(Stdio::inherit())
        .output()
        .map_err(spawn_error)?;
    if !out.status.success() {
        return Err(io::Error::other(GitExit(out.status.code().unwrap_or(1))));
    }
    Ok(String::from_utf8_lossy(&out.stdout).into_owned())
}

/// Like [`capture`], but a non-zero exit is `None` rather than an error, and
/// git's own message is swallowed.
///
/// This is for *feature detection*: asking the installed git whether it
/// supports something by trying it. That is more reliable than parsing
/// `git --version`, which says nothing about how a distribution built it.
pub fn probe(args: &[&str]) -> io::Result<Option<String>> {
    let out = git(args).stderr(Stdio::null()).output()?;
    if !out.status.success() {
        return Ok(None);
    }
    Ok(Some(String::from_utf8_lossy(&out.stdout).into_owned()))
}

/// Streams separator-delimited records from a child git process.
pub struct Records {
    child: Child,
    /// Taken before waiting, to close our end of the pipe. See `finish`.
    out: Option<BufReader<ChildStdout>>,
    buf: Vec<u8>,
    sep: u8,
    /// Set once the stream has been read to EOF. Until then git's exit status
    /// says nothing useful, because we are the ones who ended it.
    drained: bool,
}

impl Records {
    /// Reads any of this crate's format strings: one line per record, fields
    /// separated by [`FS`]. Every format string here - [`LOG_FORMAT`],
    /// [`WHO_FORMAT`] - is built to that same convention, so one framing byte
    /// serves all of them and a caller never has to line up a format with the
    /// framing it needs.
    pub fn spawn_lines(cmd: Command) -> io::Result<Records> {
        Records::spawn_framed(cmd, LINE)
    }

    /// Reads records framed by `sep`. Use [`LINE`] with [`LOG_FORMAT`].
    pub fn spawn_framed(mut cmd: Command, sep: u8) -> io::Result<Records> {
        let mut child = cmd.spawn().map_err(spawn_error)?;
        // Only `None` if the caller built a Command without a piped stdout.
        // A library returns an error for that; it does not panic on its caller.
        let stdout = child.stdout.take().ok_or_else(|| {
            io::Error::new(
                io::ErrorKind::InvalidInput,
                "the command must be configured with a piped stdout; use repo::git()",
            )
        })?;
        let out = BufReader::with_capacity(64 * 1024, stdout);
        Ok(Records {
            child,
            out: Some(out),
            buf: Vec::with_capacity(1024),
            sep,
            drained: false,
        })
    }

    /// Next record, or `None` at end of stream.
    ///
    /// Deliberately not `Iterator`: the returned string borrows the internal
    /// buffer and is invalidated by the following call, which no iterator
    /// signature can express.
    ///
    /// Blank records are skipped rather than reported as end-of-stream: a
    /// format that leads with the separator emits an empty first record, and
    /// git pads records with newlines.
    pub fn next_record(&mut self) -> io::Result<Option<Cow<'_, str>>> {
        let Some(out) = self.out.as_mut() else {
            return Ok(None);
        };
        let start;
        loop {
            self.buf.clear();
            if out.read_until(self.sep, &mut self.buf)? == 0 {
                self.drained = true;
                return Ok(None);
            }
            if self.buf.last() == Some(&self.sep) {
                self.buf.pop();
            }
            let s = self
                .buf
                .iter()
                .position(|b| !matches!(b, b'\n' | b'\r'))
                .unwrap_or(self.buf.len());
            if s < self.buf.len() {
                start = s;
                break;
            }
        }
        // Commit messages are not guaranteed UTF-8; lossy conversion borrows
        // when they are, which is the normal case.
        Ok(Some(String::from_utf8_lossy(&self.buf[start..])))
    }

    /// Waits for git and reports its exit code as a [`GitExit`] error, so
    /// `not a git repository` and friends surface correctly. git has already
    /// printed its own message to our stderr.
    pub fn finish(mut self) -> io::Result<()> {
        // Close our end of the pipe before waiting. A caller that stopped
        // reading early leaves git blocked writing into a full pipe, and
        // waiting on it in that state deadlocks; dropping the reader gives git
        // EPIPE so it can exit.
        drop(self.out.take());
        let status = self.child.wait()?;
        // Only report git's status if we actually read to the end. A caller
        // that stopped early killed git with EPIPE by closing the pipe, and
        // reporting that back as a failure would blame git for our choice.
        if self.drained && !status.success() {
            return Err(io::Error::other(GitExit(status.code().unwrap_or(1))));
        }
        Ok(())
    }
}

impl Drop for Records {
    /// A `Records` dropped without `finish` still has a child to reap; without
    /// this it would be left behind as a zombie.
    fn drop(&mut self) {
        drop(self.out.take());
        let _ = self.child.wait();
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_command_without_piped_stdout_errors_rather_than_panicking() {
        // A library consumer can build its own Command. Getting that wrong must
        // produce an error, not abort the caller's process.
        let mut cmd = Command::new("git");
        cmd.arg("--version");
        let err = match Records::spawn_lines(cmd) {
            Ok(_) => panic!("spawn should reject a command without piped stdout"),
            Err(e) => e,
        };
        assert_eq!(err.kind(), io::ErrorKind::InvalidInput);
        assert!(err.to_string().contains("piped stdout"));
    }

    #[test]
    fn a_missing_git_says_so_by_name() {
        let mut cmd = Command::new("definitely-not-a-real-program-xyz");
        cmd.stdout(Stdio::piped());
        let err = match Records::spawn_lines(cmd) {
            Ok(_) => panic!("that program should not exist"),
            Err(e) => e,
        };
        assert_eq!(err.kind(), io::ErrorKind::NotFound);
        assert!(
            err.to_string().contains("git was not found on PATH"),
            "unhelpful message: {}",
            err
        );
    }

    #[test]
    fn git_exit_code_round_trips_through_io_error() {
        let e = io::Error::other(GitExit(128));
        assert_eq!(git_exit_code(&e), Some(128));
        // An unrelated error must not be mistaken for a git exit.
        assert_eq!(git_exit_code(&io::Error::other("something else")), None);
    }

    #[test]
    fn the_field_separator_is_one_git_cannot_store() {
        // git rejects a NUL in a commit message outright, which is what makes
        // it safe. 0x1f and 0x1e are not safe: git stores them happily, and
        // they used to split the record and silently truncate the subject.
        assert_eq!(FS, '\0');
        assert!(LOG_FORMAT.contains("%x00"));
        assert!(
            !LOG_FORMAT.contains("%x1f") && !LOG_FORMAT.contains("%x1e"),
            "the log format must not rely on a byte a commit can carry"
        );
    }

    #[test]
    fn a_subject_containing_a_separator_stays_whole() {
        // splitn, not split: everything after the last field boundary belongs
        // to the subject, whatever bytes it happens to contain.
        let rec = "HASH\u{0}SHORT\u{0}P1 P2\u{0}Alice\u{0}123\u{0}refs\u{0}subject with \u{1f} and \u{1e}";
        let c = Commit::parse(rec).expect("parses");
        assert_eq!(c.hash, "HASH");
        assert_eq!(c.author, "Alice");
        assert_eq!(c.subject, "subject with \u{1f} and \u{1e}");
    }

    #[test]
    fn a_truncated_record_is_rejected_rather_than_half_parsed() {
        assert!(Commit::parse("HASH\u{0}SHORT\u{0}P1").is_none());
        assert!(Commit::parse("").is_none());
    }

    #[test]
    fn abandoning_a_reader_partway_neither_hangs_nor_leaks() {
        // A library caller may stop reading early. finish() must close the pipe
        // before waiting, or git stays blocked writing into a full one and the
        // wait never returns.
        let mut rec =
            Records::spawn_framed(git(&["log", LOG_FORMAT, "--"]), LINE).expect("spawn git log");
        assert!(
            rec.next_record().expect("read").is_some(),
            "this repository has commits"
        );
        // Deliberately stop here, with git still producing output.
        rec.finish().expect("finish must not hang or error");
    }

    #[test]
    fn dropping_a_reader_without_finishing_still_reaps_git() {
        let rec =
            Records::spawn_framed(git(&["log", LOG_FORMAT, "--"]), LINE).expect("spawn git log");
        drop(rec);
    }

    #[test]
    fn nothing_in_this_module_exits_the_process() {
        // Guards the rule, not just today's code: a library that terminates the
        // process kills any TUI or GUI that embeds it. Assembled at runtime so
        // this test's own source cannot match itself.
        let needle = format!("process{}exit", "::");
        let src = include_str!("repo.rs");
        // Only the real code; the test module below is allowed to mention it.
        let code = src.split("#[cfg(test)]").next().unwrap_or(src);
        let offenders: Vec<&str> = code
            .lines()
            .filter(|l| l.contains(&needle) && !l.trim_start().starts_with("//"))
            .collect();
        assert!(
            offenders.is_empty(),
            "the library must not exit the process: {:?}",
            offenders
        );
    }
}