From ffec84e3405dae86d3d0ab0f432388233240988e Mon Sep 17 00:00:00 2001 From: Dan Davison Date: Thu, 9 Mar 2023 14:08:34 +0000 Subject: Tips and tricks manual section (#1339) * Add Tips & tricks section to manual * Clean up manual * Reorganize Tips & tricks --- manual/src/24-bit-color-truecolor.md | 5 ----- manual/src/SUMMARY.md | 15 +++++++------- manual/src/delta-configs-used-in-screenshots.md | 2 +- manual/src/mouse-scrolling.md | 8 -------- manual/src/side-by-side-view-1.md | 23 ---------------------- .../src/tips-and-tricks/24-bit-color-truecolor.md | 5 +++++ manual/src/tips-and-tricks/export-to-html.md | 14 +++++++++++++ manual/src/tips-and-tricks/mouse-scrolling.md | 8 ++++++++ manual/src/tips-and-tricks/tips-and-tricks.md | 1 + .../src/tips-and-tricks/using-delta-on-windows.md | 3 +++ .../tips-and-tricks/using-delta-with-gnu-screen.md | 19 ++++++++++++++++++ .../src/tips-and-tricks/using-delta-with-magit.md | 5 +++++ .../src/tips-and-tricks/using-delta-with-tmux.md | 9 +++++++++ manual/src/using-delta-on-windows.md | 3 --- manual/src/using-delta-with-gnu-screen.md | 19 ------------------ manual/src/using-delta-with-magit.md | 5 ----- manual/src/using-delta-with-tmux.md | 7 ------- 17 files changed, 73 insertions(+), 78 deletions(-) delete mode 100644 manual/src/24-bit-color-truecolor.md delete mode 100644 manual/src/mouse-scrolling.md delete mode 100644 manual/src/side-by-side-view-1.md create mode 100644 manual/src/tips-and-tricks/24-bit-color-truecolor.md create mode 100644 manual/src/tips-and-tricks/export-to-html.md create mode 100644 manual/src/tips-and-tricks/mouse-scrolling.md create mode 100644 manual/src/tips-and-tricks/tips-and-tricks.md create mode 100644 manual/src/tips-and-tricks/using-delta-on-windows.md create mode 100644 manual/src/tips-and-tricks/using-delta-with-gnu-screen.md create mode 100644 manual/src/tips-and-tricks/using-delta-with-magit.md create mode 100644 manual/src/tips-and-tricks/using-delta-with-tmux.md delete mode 100644 manual/src/using-delta-on-windows.md delete mode 100644 manual/src/using-delta-with-gnu-screen.md delete mode 100644 manual/src/using-delta-with-magit.md delete mode 100644 manual/src/using-delta-with-tmux.md diff --git a/manual/src/24-bit-color-truecolor.md b/manual/src/24-bit-color-truecolor.md deleted file mode 100644 index 8b82d47d..00000000 --- a/manual/src/24-bit-color-truecolor.md +++ /dev/null @@ -1,5 +0,0 @@ -# 24 bit color (truecolor) - -Delta looks best if your terminal application supports 24 bit colors. See https://github.com/termstandard/colors#readme. For example, on MacOS, iTerm2 supports 24-bit colors but Terminal.app does not. - -If your terminal application does not support 24-bit color, delta will still work, by automatically choosing the closest color from those available. See the `Colors` section of the help output below. diff --git a/manual/src/SUMMARY.md b/manual/src/SUMMARY.md index c997740e..232a19f3 100644 --- a/manual/src/SUMMARY.md +++ b/manual/src/SUMMARY.md @@ -19,16 +19,17 @@ - [Navigation keybindings for large diffs](./navigation-keybindings-for-large-diffs.md) - [Merge conflicts](./merge-conflicts.md) - [Git blame](./git-blame.md) - - [24 bit color (truecolor)](./24-bit-color-truecolor.md) - - [Using Delta with tmux](./using-delta-with-tmux.md) - - [Using Delta with GNU Screen](./using-delta-with-gnu-screen.md) - - [Using Delta on Windows](./using-delta-on-windows.md) - - [Mouse scrolling](./mouse-scrolling.md) - - [Using Delta with Magit](./using-delta-with-magit.md) - [Supported languages and themes](./supported-languages-and-themes.md) +- [Tips & tricks](./tips-and-tricks.md) + - [24 bit color (truecolor)](./tips-and-tricks/24-bit-color-truecolor.md) + - [Using Delta with tmux](./tips-and-tricks/using-delta-with-tmux.md) + - [Using Delta with GNU Screen](./tips-and-tricks/using-delta-with-gnu-screen.md) + - [Using Delta on Windows](./tips-and-tricks/using-delta-on-windows.md) + - [Mouse scrolling](./tips-and-tricks/mouse-scrolling.md) + - [Using Delta with Magit](./tips-and-tricks/using-delta-with-magit.md) + - [Save output with colors to HTML/PDF etc](./tips-and-tricks/export-to-html.md) - [Comparisons with other tools](./comparisons-with-other-tools.md) - [Build delta from source](./build-delta-from-source.md) - [Related projects](./related-projects.md) - [Full --help output](./full---help-output.md) - [Delta configs used in screenshots](./delta-configs-used-in-screenshots.md) - - [Side-by-side view](./side-by-side-view-1.md) diff --git a/manual/src/delta-configs-used-in-screenshots.md b/manual/src/delta-configs-used-in-screenshots.md index faec6997..3c3dc127 100644 --- a/manual/src/delta-configs-used-in-screenshots.md +++ b/manual/src/delta-configs-used-in-screenshots.md @@ -2,7 +2,7 @@ ## Side-by-side view -https://github.com/vuejs/vue/commit/7ec4627902020cccd7b3f4fbc63e1b0d6b9798cd +[https://github.com/vuejs/vue/commit/7ec4627902020cccd7b3f4fbc63e1b0d6b9798cd](https://github.com/vuejs/vue/commit/7ec4627902020cccd7b3f4fbc63e1b0d6b9798cd) ```gitconfig [delta] diff --git a/manual/src/mouse-scrolling.md b/manual/src/mouse-scrolling.md deleted file mode 100644 index 26e5510a..00000000 --- a/manual/src/mouse-scrolling.md +++ /dev/null @@ -1,8 +0,0 @@ -# Mouse scrolling - -If mouse scrolling isn't working correctly, ensure that you have the most recent version of `less`. - -- For Windows you can download from https://github.com/jftuga/less-Windows/releases/latest -- For Mac you can install `brew install less; brew link less` - -Alternatively try setting your `DELTA_PAGER` environment variable to (at least) `less -R`. See [issue #58](https://github.com/dandavison/delta/issues/58). See also [bat README / "Using a different pager"](https://github.com/sharkdp/bat#using-a-different-pager), since the `DELTA_PAGER` environment variable functions very similarly for delta. diff --git a/manual/src/side-by-side-view-1.md b/manual/src/side-by-side-view-1.md deleted file mode 100644 index e456a707..00000000 --- a/manual/src/side-by-side-view-1.md +++ /dev/null @@ -1,23 +0,0 @@ -# Side-by-side view - -[https://github.com/vuejs/vue/commit/7ec4627902020cccd7b3f4fbc63e1b0d6b9798cd](https://github.com/vuejs/vue/commit/7ec4627902020cccd7b3f4fbc63e1b0d6b9798cd) - -```gitconfig -[delta] - features = side-by-side line-numbers decorations - syntax-theme = Dracula - plus-style = syntax "#003800" - minus-style = syntax "#3f0001" - -[delta "decorations"] - commit-decoration-style = bold yellow box ul - file-style = bold yellow ul - file-decoration-style = none - hunk-header-decoration-style = cyan box ul - -[delta "line-numbers"] - line-numbers-left-style = cyan - line-numbers-right-style = cyan - line-numbers-minus-style = 124 - line-numbers-plus-style = 28 -``` diff --git a/manual/src/tips-and-tricks/24-bit-color-truecolor.md b/manual/src/tips-and-tricks/24-bit-color-truecolor.md new file mode 100644 index 00000000..8b82d47d --- /dev/null +++ b/manual/src/tips-and-tricks/24-bit-color-truecolor.md @@ -0,0 +1,5 @@ +# 24 bit color (truecolor) + +Delta looks best if your terminal application supports 24 bit colors. See https://github.com/termstandard/colors#readme. For example, on MacOS, iTerm2 supports 24-bit colors but Terminal.app does not. + +If your terminal application does not support 24-bit color, delta will still work, by automatically choosing the closest color from those available. See the `Colors` section of the help output below. diff --git a/manual/src/tips-and-tricks/export-to-html.md b/manual/src/tips-and-tricks/export-to-html.md new file mode 100644 index 00000000..26ae9798 --- /dev/null +++ b/manual/src/tips-and-tricks/export-to-html.md @@ -0,0 +1,14 @@ +# Save output with colors to HTML/PDF etc + +Install [ansifilter](https://formulae.brew.sh/formula/ansifilter). + +```sh +git show \ + | delta --no-gitconfig --file-decoration-style blue --hunk-header-decoration-style blue \ + | ansifilter --html \ + > /tmp/diff.html +``` + +Now open `/tmp/diff.html` in a web browser, print to PDF, etc. + +Remove the `--no-gitconfig` above to use your own delta style, but not that `ansifilter` does not handle hyperlinks or decoration boxes etc. diff --git a/manual/src/tips-and-tricks/mouse-scrolling.md b/manual/src/tips-and-tricks/mouse-scrolling.md new file mode 100644 index 00000000..26e5510a --- /dev/null +++ b/manual/src/tips-and-tricks/mouse-scrolling.md @@ -0,0 +1,8 @@ +# Mouse scrolling + +If mouse scrolling isn't working correctly, ensure that you have the most recent version of `less`. + +- For Windows you can download from https://github.com/jftuga/less-Windows/releases/latest +- For Mac you can install `brew install less; brew link less` + +Alternatively try setting your `DELTA_PAGER` environment variable to (at least) `less -R`. See [issue #58](https://github.com/dandavison/delta/issues/58). See also [bat README / "Using a different pager"](https://github.com/sharkdp/bat#using-a-different-pager), since the `DELTA_PAGER` environment variable functions very similarly for delta. diff --git a/manual/src/tips-and-tricks/tips-and-tricks.md b/manual/src/tips-and-tricks/tips-and-tricks.md new file mode 100644 index 00000000..2c8c73f1 --- /dev/null +++ b/manual/src/tips-and-tricks/tips-and-tricks.md @@ -0,0 +1 @@ +# Tips & tricks diff --git a/manual/src/tips-and-tricks/using-delta-on-windows.md b/manual/src/tips-and-tricks/using-delta-on-windows.md new file mode 100644 index 00000000..a0d67a04 --- /dev/null +++ b/manual/src/tips-and-tricks/using-delta-on-windows.md @@ -0,0 +1,3 @@ +# Using Delta on Windows + +Delta works on Windows. However, it is essential to use a recent version of `less.exe`: you can download one from https://github.com/jftuga/less-Windows/releases/latest. If you see incorrect colors and/or strange characters in Delta output, then it is probably because Delta is picking up an old version of `less.exe` on your system. diff --git a/manual/src/tips-and-tricks/using-delta-with-gnu-screen.md b/manual/src/tips-and-tricks/using-delta-with-gnu-screen.md new file mode 100644 index 00000000..918e8733 --- /dev/null +++ b/manual/src/tips-and-tricks/using-delta-with-gnu-screen.md @@ -0,0 +1,19 @@ +# Using Delta with GNU Screen + +True color output in GNU Screen is currently only possible when using a development build, as support for it is not yet implemented in the (v4) release versions. A snapshot of the latest Git trunk can be obtained via https://git.savannah.gnu.org/cgit/screen.git/snapshot/screen-master.tar.gz - the required build steps are described in the `src/INSTALL` file. After installing the program, 24-bit color support can be activated by including `truecolor on` in either the system's or the user's `screenrc` file. + +When working in Screen without true color output, it might be that colors supposed to be different look the same in XTerm compatible terminals. If that is the case, make sure the following settings are included in your `screenrc` file: + +```Shell +term screen-256color +termcapinfo xterm 'Co#256:AB=\E[48;5;%dm:AF=\E[38;5;%dm' # ANSI (256-color) patterns - AB: background, AF: foreground +attrcolor b ".I" # use bright colors for bold text +``` + +If despite having those settings you still only get a limited set of colors, your build of Screen might have been configured without the `--enable-colors256` flag. If this is the case, you have two options : + +- If available for your OS, get a different package of Screen. Otherwise +- Build your own binary : + - Download and extract a release tarball from https://ftp.gnu.org/gnu/screen/ + - `cd` into the newly extracted folder + - Follow the instructions in the `INSTALL` file, and when running the `./configure` command apply the `--enable-colors256` flag. diff --git a/manual/src/tips-and-tricks/using-delta-with-magit.md b/manual/src/tips-and-tricks/using-delta-with-magit.md new file mode 100644 index 00000000..5ad2d03c --- /dev/null +++ b/manual/src/tips-and-tricks/using-delta-with-magit.md @@ -0,0 +1,5 @@ +# Using Delta with Magit + +Delta can be used when displaying diffs in the Magit git client: see [magit-delta](https://github.com/dandavison/magit-delta). Here's a screenshot: + +
image
diff --git a/manual/src/tips-and-tricks/using-delta-with-tmux.md b/manual/src/tips-and-tricks/using-delta-with-tmux.md new file mode 100644 index 00000000..5df79ab4 --- /dev/null +++ b/manual/src/tips-and-tricks/using-delta-with-tmux.md @@ -0,0 +1,9 @@ +# Using Delta with tmux + +If you're using tmux, it's worth checking that 24 bit color is working correctly. For example, run a color test script like [this one](https://gist.githubusercontent.com/lifepillar/09a44b8cf0f9397465614e622979107f/raw/24-bit-color.sh), or one of the others listed [here](https://gist.github.com/XVilka/8346728). If you do not see smooth color gradients, see the discussion at [tmux#696](https://github.com/tmux/tmux/issues/696). The short version is you need something like this in your `~/.tmux.conf`: + +```Shell +set -ga terminal-overrides ",xterm-256color:Tc" +``` + +and you may then need to quit tmux completely for it to take effect. diff --git a/manual/src/using-delta-on-windows.md b/manual/src/using-delta-on-windows.md deleted file mode 100644 index a0d67a04..00000000 --- a/manual/src/using-delta-on-windows.md +++ /dev/null @@ -1,3 +0,0 @@ -# Using Delta on Windows - -Delta works on Windows. However, it is essential to use a recent version of `less.exe`: you can download one from https://github.com/jftuga/less-Windows/releases/latest. If you see incorrect colors and/or strange characters in Delta output, then it is probably because Delta is picking up an old version of `less.exe` on your system. diff --git a/manual/src/using-delta-with-gnu-screen.md b/manual/src/using-delta-with-gnu-screen.md deleted file mode 100644 index 918e8733..00000000 --- a/manual/src/using-delta-with-gnu-screen.md +++ /dev/null @@ -1,19 +0,0 @@ -# Using Delta with GNU Screen - -True color output in GNU Screen is currently only possible when using a development build, as support for it is not yet implemented in the (v4) release versions. A snapshot of the latest Git trunk can be obtained via https://git.savannah.gnu.org/cgit/screen.git/snapshot/screen-master.tar.gz - the required build steps are described in the `src/INSTALL` file. After installing the program, 24-bit color support can be activated by including `truecolor on` in either the system's or the user's `screenrc` file. - -When working in Screen without true color output, it might be that colors supposed to be different look the same in XTerm compatible terminals. If that is the case, make sure the following settings are included in your `screenrc` file: - -```Shell -term screen-256color -termcapinfo xterm 'Co#256:AB=\E[48;5;%dm:AF=\E[38;5;%dm' # ANSI (256-color) patterns - AB: background, AF: foreground -attrcolor b ".I" # use bright colors for bold text -``` - -If despite having those settings you still only get a limited set of colors, your build of Screen might have been configured without the `--enable-colors256` flag. If this is the case, you have two options : - -- If available for your OS, get a different package of Screen. Otherwise -- Build your own binary : - - Download and extract a release tarball from https://ftp.gnu.org/gnu/screen/ - - `cd` into the newly extracted folder - - Follow the instructions in the `INSTALL` file, and when running the `./configure` command apply the `--enable-colors256` flag. diff --git a/manual/src/using-delta-with-magit.md b/manual/src/using-delta-with-magit.md deleted file mode 100644 index 5ad2d03c..00000000 --- a/manual/src/using-delta-with-magit.md +++ /dev/null @@ -1,5 +0,0 @@ -# Using Delta with Magit - -Delta can be used when displaying diffs in the Magit git client: see [magit-delta](https://github.com/dandavison/magit-delta). Here's a screenshot: - -
image
diff --git a/manual/src/using-delta-with-tmux.md b/manual/src/using-delta-with-tmux.md deleted file mode 100644 index 5367395c..00000000 --- a/manual/src/using-delta-with-tmux.md +++ /dev/null @@ -1,7 +0,0 @@ -If you're using tmux, it's worth checking that 24 bit color is working correctly. For example, run a color test script like [this one](https://gist.githubusercontent.com/lifepillar/09a44b8cf0f9397465614e622979107f/raw/24-bit-color.sh), or one of the others listed [here](https://gist.github.com/XVilka/8346728). If you do not see smooth color gradients, see the discussion at [tmux#696](https://github.com/tmux/tmux/issues/696). The short version is you need something like this in your `~/.tmux.conf`: - -```Shell -set -ga terminal-overrides ",xterm-256color:Tc" -``` - -and you may then need to quit tmux completely for it to take effect. -- cgit v1.2.3