From ecfdc69124381f6c7cd604e8f50b55e7d2bb9417 Mon Sep 17 00:00:00 2001 From: Kevin Ernst Date: Mon, 13 Jan 2025 21:42:44 -0500 Subject: [PATCH] Suggest minimum bat version in manual - make explicit mention of which bat version should be installed in the "Installation" and "Supported languages and themes" sections of the manual - add missing "Tips & tricks" page See https://github.com/dandavison/delta/issues/1712 for context. --- manual/src/installation.md | 2 ++ manual/src/supported-languages-and-themes.md | 3 ++- manual/src/tips-and-tricks.md | 5 +++++ 3 files changed, 9 insertions(+), 1 deletion(-) create mode 100644 manual/src/tips-and-tricks.md diff --git a/manual/src/installation.md b/manual/src/installation.md index 4ad5d3fc7..7cb509f9e 100644 --- a/manual/src/installation.md +++ b/manual/src/installation.md @@ -97,3 +97,5 @@ Users of older MacOS versions (e.g. 10.11 El Capitan) should install using Homeb Behind the scenes, delta uses [`less`](https://www.greenwoodsoftware.com/less/) for paging. It's important to have a reasonably recent version of less installed. On MacOS, install `less` from Homebrew. For Windows, see [Using Delta on Windows](./tips-and-tricks/using-delta-on-windows.md). + +If you use [`bat`](https://github.com/sharkdp/bat) and are running `bat cache --build` to install custom themes or language syntaxes then you should install the same version of bat as specified in the [`Cargo.toml`](https://github.com/dandavison/delta/blob/main/Cargo.toml) for the delta release you're using, otherwise delta will crash with a [memory error](https://github.com/dandavison/delta/issues/1712). The current version of delta does not work with bat v0.18.3 or prior versions. diff --git a/manual/src/supported-languages-and-themes.md b/manual/src/supported-languages-and-themes.md index 2e90d53c1..1dd3eff15 100644 --- a/manual/src/supported-languages-and-themes.md +++ b/manual/src/supported-languages-and-themes.md @@ -7,6 +7,7 @@ To add your own custom color theme, or language, please follow the instructions - [Adding a custom language](https://github.com/sharkdp/bat/#adding-new-syntaxes--language-definitions) - [Adding a custom theme](https://github.com/sharkdp/bat/#adding-new-themes) -Delta automatically recognizes custom themes and languages added to bat. You will need to install bat in order to run the `bat cache --build` command. +Delta automatically recognizes custom themes and languages added to bat. You will need to install bat in order to run the `bat cache --build` command. Ideally, the version of bat you install should match the version specified in delta's [`Cargo.toml`](https://github.com/dandavison/delta/blob/main/Cargo.toml) for the delta release you're using. There are [known problems](https://github.com/dandavison/delta/issues/1712) with bat v0.18.3 and below. The languages and color themes that ship with delta are those that ship with bat. So, to propose a new language or color theme for inclusion in delta, it would need to be a helpful addition to bat, in which case please open a PR against bat. + diff --git a/manual/src/tips-and-tricks.md b/manual/src/tips-and-tricks.md new file mode 100644 index 000000000..603823736 --- /dev/null +++ b/manual/src/tips-and-tricks.md @@ -0,0 +1,5 @@ +# Tips & tricks + +Delta has a number of options to configure the appearance and behavior of the user interface, and integrate with other programs, including the programmable completion features of various shells. + +The following sections discuss these features and integrations.