261115.3 · Add a TUI based on a fork of gitu (#2323)
The purpose of delta is to transform input received from git, diff, git blame, grep, etc to produce visually appealing output, including by syntax highlighting code.
Initialization
Delta readsgithub user options from [delta] sections in .gitconfig, and from the command line.
Input
Delta reads from stdingithub, hence one can do e.g. git diff | delta.
Note that when git’s stdout is sent to a pipe, (a) git does not emit ANSI color escape sequences unless --color=always, and (b) git does not start its own pager process.
Users typically configure git to use delta as its pager. In that case, git sends its stdout to delta behind the scenes (with ANSI color escape sequences), without the user needing to pipe it explicitly.
Parsing the input
Delta parses inputgithub using a state machine in which
the states correspond to semantically distinct sections of the input (e.g. HunkMinus means that we are in a removed line in a diff hunk).
The core dispatching loop is heregithub.
pub fn delta<I>(lines: ByteLines<I>, writer: &mut dyn Write, config: &Config) -> std::io::Result<()>
where
I: BufRead,
{
StateMachine::new(writer, config).consume(lines)
}
pub enum State {
DiffHeader(DiffType),
HunkHeader(DiffType, ParsedHunkHeader, String, String),
HunkZero(DiffType, Option<String>),
HunkMinus(DiffType, Option<String>),
HunkPlus(DiffType, Option<String>),
Unknown,
}
impl<'a> StateMachine<'a> {
fn consume<I>(&mut self, mut lines: ByteLines<I>) -> std::io::Result<()>
where
I: BufRead,
{
while let Some(Ok(raw_line_bytes)) = lines.next() {
self.ingest_line(raw_line_bytes);
// Every method named handle_* must return std::io::Result<bool>.
// The bool indicates whether the line has been handled by that
// method (in which case no subsequent handlers are permitted to
// handle it).
let _ = self.handle_commit_meta_header_line()?
|| self.handle_diff_stat_line()?
|| self.handle_hunk_header_line()?
|| self.handle_hunk_line()?
|| self.emit_line_unchanged()?;
}
self.painter.paint_buffered_minus_and_plus_lines();
Ok(())
}
}Output
Delta createsgithub a child pager process (less) and writes its output to the stdin of the pager process.
Delta’s navigate feature is implemented by constructing an appropriate regex and passing it as an argument to less.
Core utility data structures
-
config::Configgithub This is a struct with many fields corresponding to all user options and miscellaneous other useful things. It might be possible to store it globally, but currently the code passes references to it around the call stack. -
paint::Paintergithub This struct holds the syntax highlighter, and a writable output stream (connected to the stdin of the childlessprocess). It also holds two line buffers: one to store all the removed (“minus”) lines encountered in a single diff hunk, and one to hold the added (“plus”) lines.
Handling diff hunk lines
Here we will follow one code path in detail: handling diff hunk linesgithub (removed/unchanged/added). This is the most important, and most complex, code path.
Recall that git diff output contains multiple diff “hunks”. A hunk is a sequence of diff lines describing the changes among some lines of code that are close together in the same file. A git diff may have many hunks, from multiple files (and therefore multiple languages). Within a hunk, there are sequences of consecutive removed and/or added lines (“subhunks”), separated by unchanged lines. (The term “hunk” is standard; the term “subhunk” is specific to delta.)
The handler function that is called when delta process a hunk line is handle_hunk_linegithub.
This function stores the line in a buffergithub (one buffer for minus lines and one for plus lines): the processing work is not done until we get to the end of the subhunk.
Now, we are at the end of a subhunk, and we have a sequence of minus lines, and a sequence of plus lines.
![]() |
Delta processes a subhunkgithub (paint_minus_and_plus_lines) as follows:
|
|
-
Compute syntax (foreground) styles for the subhunk
We callgithub the syntectgithub library to compute syntax highlighting styles for each of the minus lines, and each of the plus lines, if the minus/plus styles specify syntax highlighting. The language used for syntax-highlighting is determined by the filename in the diff. For a single line, the result is an array of
(style, substring)pairs. Each pair specifies the foreground (text) color to be applied to a substring of the line (for example, a language keyword, or a string literal). -
Compute diff (background) styles for the subhunk
Again, the callgithub yields, for each line, an array of
(style, substring)pairs. Each pair represents foreground and background colors to be applied to a substring of the line, as specified by delta’s*-styleoptions.In order to compute the array of style sections, the call has to (1) infer the correct alignment of minus and plus lines, and (2) for each such “homologous pair”, infer the edit operations that transformed the minus line into the plus line (see within-line-diff-algorithm).
For example, for a minus line, we may have inferred that the line has a homologous plus line, and that a word has been deleted. By default, delta applies a bright red background color to such a word and lets the foreground color be determined by the terminal emulator default foreground color (
minus-emph-style = normal "#901011"). On the other hand, for an added word, delta by default applies a bright green background color, and specifies that the foreground color should come from the syntax highlighting styles (plus-emph-style = syntax "#006000"). -
Process subhunk lines for side-by-side or unified output
At this point we have a collection of lines corresponding to a subhunk and, for each line, a specification of how syntax styles and diff styles are applied to substrings of the line. These data structures are processed differentlygithub according to whether unified or side-by-side diff display has been requested.
-
Superimpose syntax and diff styles for a line
Before we can output a line of code we need to take the two arrays of
(style, substring)pairs and compute a single output array of(style, substring)pairs, such that the output array represents the diff styles, but with foreground colors taken from the syntax highlighting, where appropriate. The call is heregithub (superimpose_style_sections). -
Output a line with styles converted to ANSI color escape sequences
The
stylestructs that delta uses are implemented by theansi_termgithub library. Individual substrings are paintedgithub with their assigned style, and concatenatedgithub to form a utf-8 string containing ANSI color escape sequences.
Within-line diff algorithm
There is currently only one within-line diff algorithm implemented. This considersgithub all possible pairings for a given line and for each one, computesgithub the minimum number of edit operations between the candidate pair. The inferred pairing is the one with the smallest edit distance. (The number of comparisons is constrained by the possible interleavings, and furthermore a greedy heuristic is used, so that the number of comparisons is not quadratic).
Features
Delta features such as line-numbers, side-by-side, diff-so-fancy, etc can be considered to consist of (a) some feature-specific implementation code, and (b) a collection of key-value pairs specifying the values that certain delta options should take if that feature is enabled.
Accordingly, each such “feature” is implemented by a separate module under src/features/github.
Each of these modules must export a function named make_feature whose job is to return key-value pairs for updating the user options.
Common terms used in the code
minus |
a removed line in a diff hunk (i.e. the lines starting with -) |
zero |
an unchanged line in a diff hunk |
plus |
an added line in a diff hunk (i.e. the lines starting with +) |
style |
a struct specifying foreground colors, background colors, and other attributes such as boldness, derived from ANSI sequences |
style_sections |
an array of (style, section) tuples |
paint |
to take a string without ANSI color sequences and return a new one with ANSI color sequences |
hunk |
a diff hunk |
subhunk |
a consecutive sequence of minus and/or plus lines, without any zero line |
TUI mode (delta --tui)
delta --tui runs gitu, from the delta-gitu crate (a forkgithub of gitugithub), inside the delta process (src/subcommands/gitu.rs). It sets the running delta binary as gitu’s diff renderer. delta is still a one-pass filter: gitu runs it as a child process for each diff it draws.
- Rows carry patch identity. gitu starts delta with
OSC1717=V1. delta then writes an OSC 1717 record on each row it draws: file header, hunk header, diff line (with its type and old and new line numbers) and commit (src/features/diff_line_metadata.rs). The records are invisible in a terminal. gitu parses the patch itself and uses the records to map each rendered row to a line of the patch, so it can navigate, fold and stage whatever delta’s layout (side-by-side, line numbers, no+/-markers). Staging builds a patch from the selected lines and passes it togit apply. - gitu runs git’s command again. git does not tell its pager what command it ran. gitu finds the git process in the process tree, as delta does to find the calling process, and runs that command itself, in the directory git ran it, without reading what git piped. It runs it again after each change, so
:accepts only read-only git commands. The command decides which operations are offered:git diffcan stage,git diff --cachedcan unstage, and a diff involving a commit can be applied and reversed. - Streaming. gitu passes git’s output to delta as a shell pipeline would. It draws the first screen from what delta has drawn so far, cut back to whole hunks, and rebuilds the view when delta finishes.
- Features. gitu passes the features turned on in the session as
DELTA_FEATURES=+name ..., which delta adds to the user’s config. - Stat rows. delta draws a file’s header before it reads the file’s hunks, so it cannot draw a
--statrow in place of the header. gitu counts stat rows from the patch and lays them out as git does.
