From 4598c7b548c142a5a80e3a3e442f0f679bbecca0 Mon Sep 17 00:00:00 2001 From: Stefan Haller Date: Sun, 26 Jul 2026 18:53:40 +0200 Subject: [PATCH] Adapt documentation --- README.md | 6 +- docs-master/Config.md | 2 +- docs-master/Custom_DiffRenderers.md | 84 ++++++++++++++++++++++ docs-master/Custom_Pagers.md | 108 ---------------------------- docs-master/README.md | 2 +- pkg/config/user_config.go | 2 +- schema-master/config.json | 2 +- 7 files changed, 91 insertions(+), 115 deletions(-) create mode 100644 docs-master/Custom_DiffRenderers.md delete mode 100644 docs-master/Custom_Pagers.md diff --git a/README.md b/README.md index 2fdf688fd..5d5e47e11 100644 --- a/README.md +++ b/README.md @@ -118,7 +118,7 @@ If you're a mere mortal like me and you're tired of hearing how powerful git is - [Changing Directory On Exit](#changing-directory-on-exit) - [Undo/Redo](#undoredo) - [Configuration](#configuration) - - [Custom Pagers](#custom-pagers) + - [Custom Diff Renderers](#custom-diff-renderers) - [Custom Commands](#custom-commands) - [Git flow support](#git-flow-support) - [Contributing](#contributing) @@ -590,9 +590,9 @@ See the [docs](/docs/Undoing.md) Check out the [configuration docs](docs/Config.md). -### Custom Pagers +### Custom Diff Renderers -See the [docs](docs/Custom_Pagers.md) +See the [docs](docs/Custom_DiffRenderers.md) ### Custom Commands diff --git a/docs-master/Config.md b/docs-master/Config.md index 3dede3bc9..857a4e359 100644 --- a/docs-master/Config.md +++ b/docs-master/Config.md @@ -390,7 +390,7 @@ git: # # applicable if the type is 'rawGit'. # args: [] # - # See https://github.com/jesseduffield/lazygit/blob/master/docs/Custom_Pagers.md + # See https://github.com/jesseduffield/lazygit/blob/master/docs/Custom_DiffRenderers.md # for more information. diffRenderers: [] diff --git a/docs-master/Custom_DiffRenderers.md b/docs-master/Custom_DiffRenderers.md new file mode 100644 index 000000000..1a6b1d5ce --- /dev/null +++ b/docs-master/Custom_DiffRenderers.md @@ -0,0 +1,84 @@ +# 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](#delta) and [diff-so-fancy](#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. + + You can include the `{{diffContext}}` template variable to pass lazygit's current diff context size (the value controlled by the `{`/`}` keybindings) to the diff tool. + +Fields only for `rawGit`: + +- **args** The additional arguments to use in the `git diff` or `git show` call (e.g. `--color-words`) + +Here's an example for a multi-renderer setup: + +```yaml +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: + +```yaml +git: + diffRenderers: + - command: delta --dark --paging=never +``` + +![](https://i.imgur.com/QJpQkF3.png) + +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 + +```yaml +git: + diffRenderers: + - command: diff-so-fancy +``` + +![](https://i.imgur.com/rjH1TpT.png) + +## ydiff + +```yaml +gui: + sidePanelWidth: 0.2 # gives you more space to show things side-by-side +git: + diffRenderers: + - colorArg: never + command: ydiff -p cat +``` + +![](https://i.imgur.com/vaa8z0H.png) diff --git a/docs-master/Custom_Pagers.md b/docs-master/Custom_Pagers.md deleted file mode 100644 index 8bdcf164d..000000000 --- a/docs-master/Custom_Pagers.md +++ /dev/null @@ -1,108 +0,0 @@ -# Custom Pagers - -Lazygit supports custom pagers, [configured](/docs/Config.md) in the config.yml file (which can be opened by pressing `e` in the Status panel). - -Multiple pagers are supported; you can cycle through them with the `|` key. This can be useful if you usually prefer a particular pager, but want to use a different one for certain kinds of diffs. - -Pagers are configured with the `pagers` array in the git section; here's an example for a multi-pager setup (use an empty object `{}` for the default builtin diff display that doesn't use a pager): - -```yaml -git: - pagers: - - pager: delta --dark --paging=never - - pager: ydiff -p cat -s --wrap --width={{columnWidth}} - colorArg: never - - externalDiffCommand: difft --color=always - - {} # default, no pager used -``` - -The `colorArg` key is for whether you want the `--color=always` arg in your `git diff` command. Some pagers want it set to `always`, others want it set to `never`. The default is `always`, since that's what most pagers need. - -## Delta: - -```yaml -git: - pagers: - - pager: delta --dark --paging=never -``` - -![](https://i.imgur.com/QJpQkF3.png) - -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 `pager:` config 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 - -```yaml -git: - pagers: - - pager: diff-so-fancy -``` - -![](https://i.imgur.com/rjH1TpT.png) - -## ydiff - -```yaml -gui: - sidePanelWidth: 0.2 # gives you more space to show things side-by-side -git: - pagers: - - colorArg: never - pager: ydiff -p cat -s --wrap --width={{columnWidth}} -``` - -![](https://i.imgur.com/vaa8z0H.png) - -Be careful with this one, I think the homebrew and pip versions are behind master. I needed to directly download the ydiff script to get the no-pager functionality working. - -## Using external diff commands - -Some diff tools can't work as a simple pager like the ones above do, because they need access to the entire diff, so just post-processing git's diff is not enough for them. The most notable example is probably [difftastic](https://difftastic.wilfred.me.uk). - -These can be used in lazygit by using the `externalDiffCommand` config; in the case of difftastic, that could be - -```yaml -git: - pagers: - - externalDiffCommand: difft --color=always --context={{diffContext}} -``` - -The `colorArg` option is not used in this case. You can include the `{{diffContext}}` template variable to pass lazygit's current diff context size (the value controlled by the `{`/`}` keybindings) to the diff tool. - -You can add whatever extra arguments you prefer for your difftool; for instance - -```yaml -git: - pagers: - - externalDiffCommand: difft --color=always --context={{diffContext}} --display=inline --syntax-highlight=off -``` - -This can also be used for normal git diffs with custom parameters, such as `--color-words` or `--word-diff` which some people find useful. To do that, save a script like this to, say, `~/bin/color-words.sh`: - -```sh -#!/bin/sh - -git diff --color-words --no-index --color=always --no-ext-diff --unified=$LAZYGIT_DIFF_CONTEXT "$2" "$5" -``` - -And then use it in your git config like so: - -```yaml -git: - pagers: - - externalDiffCommand: LAZYGIT_DIFF_CONTEXT={{diffContext}} ~/bin/color-words.sh -``` - -Instead of setting this command in lazygit's `externalDiffCommand` config, you can also tell lazygit to use the external diff command that is configured in git itself (`diff.external`), by using - -```yaml -git: - pagers: - - useExternalDiffGitConfig: true -``` - -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. - -`pager`, `externalDiffCommand`, and `useExternalDiffGitConfig` are alternative ways of producing the diff, so a pager entry may use at most one of them. diff --git a/docs-master/README.md b/docs-master/README.md index 1bc0bb6be..c586d9699 100644 --- a/docs-master/README.md +++ b/docs-master/README.md @@ -2,7 +2,7 @@ * [Configuration](./Config.md). * [Custom Commands](./Custom_Command_Keybindings.md) -* [Custom Pagers](./Custom_Pagers.md) +* [Custom Diff Renderers](./Custom_DiffRenderers.md) * [Dev docs](./dev) * [Keybindings](./keybindings) * [Undo/Redo](./Undoing.md) diff --git a/pkg/config/user_config.go b/pkg/config/user_config.go index a8148f022..9738186d9 100644 --- a/pkg/config/user_config.go +++ b/pkg/config/user_config.go @@ -300,7 +300,7 @@ type GitConfig struct { // # applicable if the type is 'rawGit'. // args: [] // - // See https://github.com/jesseduffield/lazygit/blob/master/docs/Custom_Pagers.md for more information. + // See https://github.com/jesseduffield/lazygit/blob/master/docs/Custom_DiffRenderers.md for more information. DiffRenderers []DiffRendererConfig `yaml:"diffRenderers"` // Config relating to committing Commit CommitConfig `yaml:"commit"` diff --git a/schema-master/config.json b/schema-master/config.json index bd4b3bc8e..45a2b9efe 100644 --- a/schema-master/config.json +++ b/schema-master/config.json @@ -365,7 +365,7 @@ "$ref": "#/$defs/DiffRendererConfig" }, "type": "array", - "description": "Array of diff renderers. Each entry has the following format:\n\n # The type of diff renderer. One of: 'stdinFilter' (default) | 'extDiff'\n # | 'rawGit'\n type: \"stdinFilter\"\n\n # A name for the diff renderer, shown in the notification when cycling\n # renderers. If not set, the name is derived from the first word of the\n # renderer command.\n name: \"\"\n\n # Value of the --color arg in the git diff command. Only used for type\n # 'stdinFilter'. Some renderers want this to be set to 'always' and some\n # want it set to 'never'.\n colorArg: \"always\"\n\n # The command to use for rendering diffs. This is either a stdinFilter or\n # an external diff command, depending on the type field; not applicable if\n # the type is 'rawGit'.\n # e.g.\n # diff-so-fancy\n # delta --dark --paging=never\n # ydiff -p cat\n # difft --color=always\n command: \"\"\n\n # Extra arguments (array of strings) passed to the git command. Only\n # applicable if the type is 'rawGit'.\n args: []\n\nSee https://github.com/jesseduffield/lazygit/blob/master/docs/Custom_Pagers.md for more information." + "description": "Array of diff renderers. Each entry has the following format:\n\n # The type of diff renderer. One of: 'stdinFilter' (default) | 'extDiff'\n # | 'rawGit'\n type: \"stdinFilter\"\n\n # A name for the diff renderer, shown in the notification when cycling\n # renderers. If not set, the name is derived from the first word of the\n # renderer command.\n name: \"\"\n\n # Value of the --color arg in the git diff command. Only used for type\n # 'stdinFilter'. Some renderers want this to be set to 'always' and some\n # want it set to 'never'.\n colorArg: \"always\"\n\n # The command to use for rendering diffs. This is either a stdinFilter or\n # an external diff command, depending on the type field; not applicable if\n # the type is 'rawGit'.\n # e.g.\n # diff-so-fancy\n # delta --dark --paging=never\n # ydiff -p cat\n # difft --color=always\n command: \"\"\n\n # Extra arguments (array of strings) passed to the git command. Only\n # applicable if the type is 'rawGit'.\n args: []\n\nSee https://github.com/jesseduffield/lazygit/blob/master/docs/Custom_DiffRenderers.md for more information." }, "commit": { "$ref": "#/$defs/CommitConfig",