mirror of https://github.com/jesseduffield/lazygit.git synced 2026-10-05 21:46:49 -04:00

Files

T

Stefan HallerandClaude Opus 5.5 c8a4c8d392 Let the command of a diff renderer be a template

The command of a diff renderer can refer to values like the width it
renders at, as {{width}}. They are filled in by plain replacement, so a
command can't choose between options depending on them. The next commit
adds a value that needs this: whether the terminal is dark or light.
delta takes --dark or --light, but for other renderers the choice has to
be spelled out differently, for example as the name of a syntax theme.

Resolve the command as a Go template instead. The values become its
variables, so that {{if gt .width 160}} --side-by-side{{end}} works too.
To keep the existing commands working, a variable can still be written
without the leading dot.

A mistake in a template, such as a misspelled variable, now makes
resolving the command fail, instead of leaving the placeholder in it.
Check the commands when the config is loaded, by resolving each of them
with made-up values, so that the mistake shows up as an invalid config.
This also rejects a variable that the kind of renderer doesn't have,
such as {{columnWidth}} in the command of an external diff; until now,
it reached the renderer as it was.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

2026-09-27 08:09:45 +02:00

4.6 KiB

Raw Blame History

Custom Diff Renderers

Custom diff renderers are useful for showing a better rendering of a diff than git's builtin raw diff, and using one is strongly recommended (I personally prefer delta myself, but that's a matter of personal preference). There are three types of diff renderers that lazygit supports:

stdin filters, e.g. delta and diff-so-fancy. They take git's raw output as stdin and produce something nicer on stdout, and they are hooked up using git's GIT_PAGER mechanism. (These used to be called "custom pagers" in earlier lazygit versions.)
external diff programs, e.g. difftastic; these are called using git's --ext-diff flag, and they take over diff generation from git completely rather than post-processing git's output.
git's raw output using custom arguments; mainly useful for --color-words (or --word-diff if you are color blind).

Diff renderers are configured with the diffRenderers array in the git section of lazygit's config file; it is an array because you can have multiple entries that you can cycle through with the | key. This can be useful if you usually prefer a particular diff renderer, but want to use a different one for certain kinds of diffs.

Fields that are shared by all renderer types:

type The type of diff renderer; choices are stdinFilter, extDiff, or rawGit. stdinFilter is the default, because it's the most common one; so you can omit this if you use delta.
name A name that is shown in the status bar toast when cycling renderers; defaults to the first word of the renderer command, but can be useful e.g. to distinguish "delta" from "delta side-by-side" if you have entries for both.

Fields only for stdinFilter:

command The command line to use for GIT_PAGER.
colorArg whether you want the --color=always arg in your git diff command. Some diff renderers want it set to always, others want it set to never. The default is always, since that's what most renderers need.

Fields only for extDiff:

command The command line to use for the diff.external git config. If left empty, it uses the global value of git's diff.external config; this can be useful if you also want to use it for diffs on the command line, and it also has the advantage that you can configure it per file type in .gitattributes; see https://git-scm.com/docs/gitattributes#_defining_an_external_diff_driver.

Fields only for rawGit:

args The additional arguments to use in the git diff or git show call (e.g. --color-words), as an array of strings.

The command of a stdinFilter or extDiff renderer is a Go template with these variables:

{{width}}: the width of the view that the diff is rendered into.
{{columnWidth}} (only for stdinFilter): the width of one side of a side-by-side rendering, e.g. for ydiff -p cat -s -w {{columnWidth}}.
{{diffContext}} (only for extDiff): lazygit's current diff context size, the value controlled by the {/} keybindings.

A variable can also be written with a leading dot, as in {{.width}}. The command can use template expressions too; for example, delta --paging=never {{if gt .width 160}}--side-by-side{{end}} shows the diff side by side only when there is room for it.

Here's an example for a multi-renderer setup:

git:
  diffRenderers:
    - command: delta --dark --paging=never
    - command: ydiff -p cat
      colorArg: never
    - type: extDiff
      command: difft --color=always --context={{diffContext}}
    - type: rawGit
      args: [--color-words]
      name: color-words
    - type: rawGit # git's default diff
      name: default

Delta:

git:
  diffRenderers:
    - command: delta --dark --paging=never

A cool feature of delta is --hyperlinks, which renders clickable links for the line numbers in the left margin, and lazygit supports these. To use them, set the command: field to delta --dark --paging=never --line-numbers --hyperlinks --hyperlinks-file-link-format="lazygit-edit://{path}:{line}"; this allows you to click on an underlined line number in the diff to jump right to that same line in your editor.

Note that delta's --navigate option doesn't work in lazygit, for technical reasons.

Diff-so-fancy

git:
  diffRenderers:
    - command: diff-so-fancy

ydiff

gui:
  sidePanelWidth: 0.2 # gives you more space to show things side-by-side
git:
  diffRenderers:
    - colorArg: never
      command: ydiff -p cat

4.6 KiB Raw Blame History

Custom Diff Renderers

Delta:

Diff-so-fancy

ydiff

4.6 KiB

Raw Blame History