lazygit/docs-master/Custom_DiffRenderers.md

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.
• {{colorScheme}}: dark or light, depending on whether the terminal has a dark or a light background. Lazygit asks the terminal about this; if yours doesn't tell, set gui.colorScheme.
• {{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, or delta --syntax-theme={{if eq .colorScheme "light"}}Github{{else}}Dracula{{end}} picks a different syntax theme based on the background.

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

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

Delta:

git:
  diffRenderers:
    - command: delta --{{colorScheme}} --paging=never

--{{colorScheme}} passes --dark or --light to delta, so that it matches the background of your terminal.

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 --{{colorScheme}} --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