Split README.md into mdbook manual

github actions config copied from https://github.com/Wilfred/difftastic

35 files changed, 1272 insertions, 0 deletions

diff --git a/.github/workflows/manual.yml b/.github/workflows/manual.yml
new file mode 100644
index 00000000..c262effd
--- /dev/null
+++ b/.github/workflows/manual.yml
@@ -0,0 +1,38 @@
+name: Deploy Manual
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  deploy:
+    runs-on: ubuntu-20.04
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: 1.54.0
+          override: true
+      - uses: actions-rs/cargo@v1
+        with:
+          command: doc
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: '0.4.14'
+
+      - name: Build manual
+        run: mdbook build
+        working-directory: manual
+
+      - name: Deploy to GitHub pages
+        uses: JamesIves/github-pages-deploy-action@4.1.6
+        with:
+          branch: gh-pages
+          folder: manual/book
diff --git a/manual/.gitignore b/manual/.gitignore
new file mode 100644
index 00000000..7585238e
--- /dev/null
+++ b/manual/.gitignore
@@ -0,0 +1 @@
+book
diff --git a/manual/Makefile b/manual/Makefile
new file mode 100644
index 00000000..571a147c
--- /dev/null
+++ b/manual/Makefile
@@ -0,0 +1,8 @@
+build:
+	mdbook build
+
+init:
+	mdbook init --ignore none --title delta
+
+serve:
+	mdbook serve
diff --git a/manual/book.toml b/manual/book.toml
new file mode 100644
index 00000000..3fa05dc8
--- /dev/null
+++ b/manual/book.toml
@@ -0,0 +1,6 @@
+[book]
+authors = ["Dan Davison"]
+language = "en"
+multilingual = false
+src = "src"
+title = "delta"
diff --git a/manual/src/24-bit-color-truecolor.md b/manual/src/24-bit-color-truecolor.md
new file mode 100644
index 00000000..53d47dda
--- /dev/null
+++ b/manual/src/24-bit-color-truecolor.md
@@ -0,0 +1,15 @@
+# 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.
+
+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.
+
+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.
diff --git a/manual/src/SUMMARY.md b/manual/src/SUMMARY.md
new file mode 100644
index 00000000..210d4009
--- /dev/null
+++ b/manual/src/SUMMARY.md
@@ -0,0 +1,32 @@
+# Summary
+
+- [Introduction](./introduction.md)
+- [Get started](./get-started.md)
+- [Features](./features.md)
+- [Installation](./installation.md)
+- [Configuration](./configuration.md)
+- [How delta works](./how-delta-works.md)
+- [Usage](./usage.md)
+  - [Choosing colors (styles)](./choosing-colors-styles.md)
+  - [Line numbers](./line-numbers.md)
+  - [Side-by-side view](./side-by-side-view.md)
+  - [Grep](./grep.md)
+  - ["Features": named groups of settings](./features-named-groups-of-settings.md)
+  - [Custom themes](./custom-themes.md)
+  - [diff-highlight and diff-so-fancy emulation](./diff-highlight-and-diff-so-fancy-emulation.md)
+  - [--color-moved support](./color-moved-support.md)
+  - [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 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)
+- [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/build-delta-from-source.md b/manual/src/build-delta-from-source.md
new file mode 100644
index 00000000..ba00b5d1
--- /dev/null
+++ b/manual/src/build-delta-from-source.md
@@ -0,0 +1,9 @@
+# Build delta from source
+
+You'll need to [install the rust tools](https://www.rust-lang.org/learn/get-started). Then:
+
+```ShellSession
+$ cargo build --release
+```
+
+and use the executable found at `./target/release/delta`.
diff --git a/manual/src/choosing-colors-styles.md b/manual/src/choosing-colors-styles.md
new file mode 100644
index 00000000..e974ebe5
--- /dev/null
+++ b/manual/src/choosing-colors-styles.md
@@ -0,0 +1,16 @@
+# Choosing colors (styles)
+
+All options that have a name like `--*-style` work in the same way. It is very similar to how
+colors/styles are specified in a gitconfig file:
+https://git-scm.com/docs/git-config#Documentation/git-config.txt-color
+
+Here's an example:
+
+```gitconfig
+[delta]
+    minus-style = red bold ul "#ffeeee"
+```
+
+That means: For removed lines, set the foreground (text) color to 'red', make it bold and underlined, and set the background color to `#ffeeee`.
+
+For full details, see the `STYLES` section in [`delta --help`](#full---help-output).
diff --git a/manual/src/color-moved-support.md b/manual/src/color-moved-support.md
new file mode 100644
index 00000000..5f4c42fc
--- /dev/null
+++ b/manual/src/color-moved-support.md
@@ -0,0 +1,56 @@
+# `--color-moved` support
+
+Recent versions of Git (≥ v2.17, April 2018) are able to detect moved blocks of code and style them differently from the usual removed/added lines. If you have activated this feature in Git, then Delta will automatically detect such differently-styled lines, and display them unchanged, i.e. with the raw colors it receives from Git.
+
+To activate the Git feature, use
+
+```gitconfig
+[diff]
+    colorMoved = default
+```
+
+and see the [Git documentation](https://git-scm.com/docs/git-diff#Documentation/git-diff.txt---color-movedltmodegt) for the other possible values and associated color configuration.
+
+The `map-styles` option allows us to transform the styles that git emits for color-moved sections into delta styles.
+Here's an example of using `map-styles` to assign delta styles to the raw color-moved styles output by git.
+This feature allows all of git's color-moved options to be rendered using delta styles, including with syntax highlighting.
+
+```gitconfig
+[delta]
+    map-styles = bold purple => syntax magenta, bold cyan => syntax blue
+```
+
+It is also possible to reference other styles.
+
+```gitconfig
+[delta]
+    features = my-color-moved-theme
+
+[delta "my-color-moved-theme"]
+    git-moved-from-style = bold purple     # An ad-hoc named style (must end in "-style")
+
+    map-styles = "my-color-moved-theme.git-moved-from-style => red #cccccc, \
+                  bold cyan => syntax #cccccc"
+
+    # we could also have defined git-moved-to-style = bold cyan
+```
+
+To make use of that, you need to know that git is emitting "bold cyan" and "bold purple".
+But that's not always obvious.
+To help with that, delta now has a `--parse-ansi` mode. E.g. `git show --color=always | delta --parse-ansi` outputs something like this:
+
+<table><tr><td><img width=300px src="https://user-images.githubusercontent.com/52205/143238872-58a40754-ae50-4a9e-ba72-07e330e520e6.png" alt="image" /></td></tr></table>
+
+As you see above, we can now define named styles in gitconfig and refer to them in places where a style string is expected.
+We can also define custom named colors in git config, and styles can reference other styles; see the [hoopoe theme](https://github.com/dandavison/delta/blob/master/themes.gitconfig#L76-L91) for an example:
+
+```gitconfig
+[delta "hoopoe"]
+    green = "#d0ffd0"  # ad-hoc named color
+    plus-style = syntax hoopoe.green  # refer to named color
+    plus-non-emph-style = plus-style  # styles can reference other styles
+```
+
+Additionally, we can now use the 140 color names that are standard in CSS. Use `delta --show-colors` to get a demo of the available colors, as background colors to see how they look with syntax highlighting:
+
+<table><tr><td><img width=300px src="https://user-images.githubusercontent.com/52205/143237384-246db199-ef65-4ad2-ad4e-03d07d1ea41d.png" alt="image" /></td></tr></table>
diff --git a/manual/src/comparisons-with-other-tools.md b/manual/src/comparisons-with-other-tools.md
new file mode 100644
index 00000000..670820d7
--- /dev/null
+++ b/manual/src/comparisons-with-other-tools.md
@@ -0,0 +1,51 @@
+# Comparisons with other tools
+
+(`delta --light`)
+
+<table>
+  <tr>
+    <td>
+      delta vs. git
+    </td>
+    <td>
+      <img width=500px style="border: 1px solid black"
+           src="https://user-images.githubusercontent.com/52205/65248525-32250480-daea-11e9-9965-1a05c6a4bdf4.png"
+           alt="image" />
+    </td>
+    <td>
+      <img width=500px style="border: 1px solid black"
+           src="https://user-images.githubusercontent.com/52205/65248441-14f03600-daea-11e9-88a1-d96bbb6947f8.png"
+           alt="image" />
+    </td>
+  </tr>
+  <tr>
+    <td>
+      delta vs. diff-so-fancy /<br>diff-highlight
+    </td>
+    <td>
+      <img width=500px style="border: 1px solid black"
+           src="https://user-images.githubusercontent.com/52205/65248525-32250480-daea-11e9-9965-1a05c6a4bdf4.png"
+           alt="image" />
+    </td>
+    <td>
+      <img width=500px style="border: 1px solid black"
+           src="https://user-images.githubusercontent.com/52205/65248407-07d34700-daea-11e9-9a8f-6d81f4021abf.png"
+           alt="image" />
+    </td>
+  </tr>
+  <tr>
+    <td>
+      delta vs. github
+    </td>
+    <td>
+      <img width=500px style="border: 1px solid black"
+           src="https://user-images.githubusercontent.com/52205/65248525-32250480-daea-11e9-9965-1a05c6a4bdf4.png"
+           alt="image" />
+    </td>
+    <td>
+      <img width=500px style="border: 1px solid black"
+           src="https://user-images.githubusercontent.com/52205/65248749-9a73e600-daea-11e9-9c0d-29c8f1dea08e.png"
+           alt="image" />
+    </td>
+  </tr>
+</table>
diff --git a/manual/src/configuration.md b/manual/src/configuration.md
new file mode 100644
index 00000000..28281416
--- /dev/null
+++ b/manual/src/configuration.md
@@ -0,0 +1,63 @@
+# Configuration
+
+## Git config file
+
+The most convenient way to configure delta is with a `[delta]` section in `~/.gitconfig`. Here's an example:
+
+<sub>
+
+```gitconfig
+[core]
+    pager = delta
+
+[interactive]
+    diffFilter = delta --color-only --features=interactive
+
+[delta]
+    features = decorations
+
+[delta "interactive"]
+    keep-plus-minus-markers = false
+
+[delta "decorations"]
+    commit-decoration-style = blue ol
+    commit-style = raw
+    file-style = omit
+    hunk-header-decoration-style = blue box
+    hunk-header-file-style = red
+    hunk-header-line-number-style = "#067a00"
+    hunk-header-style = file line-number syntax
+```
+
+</sub>
+
+Use `delta --help` to see all the available options.
+
+Note that delta style argument values in ~/.gitconfig should be in double quotes, like `--minus-style="syntax #340001"`. For theme names and other values, do not use quotes as they will be passed on to delta, like `theme = Monokai Extended`.
+
+All git commands that display diff output should now display syntax-highlighted output. For example:
+
+- `git diff`
+- `git show`
+- `git log -p`
+- `git stash show -p`
+- `git reflog -p`
+- `git add -p`
+
+To change your delta options in a one-off git command, use `git -c`. For example
+
+```
+git -c delta.line-numbers=false show
+```
+
+Delta can also be used as a shorthand for diffing two files: the following two commands do the same thing:
+
+```
+delta a.txt b.txt
+
+git diff a.txt b.txt
+```
+
+Delta also handles unified diff format, e.g. `diff -u a.txt b.txt | delta`.
+
+For Mercurial, you can add delta, with its command line options, to the `[pager]` section of `.hgrc`.
diff --git a/manual/src/custom-themes.md b/manual/src/custom-themes.md
new file mode 100644
index 00000000..0d7e0f0d
--- /dev/null
+++ b/manual/src/custom-themes.md
@@ -0,0 +1,21 @@
+# Custom themes
+
+A "theme" in delta is just a collection of settings grouped together in a named [feature](#features-named-groups-of-settings). One of the available settings is `syntax-theme`: this dictates the colors and styles that are applied to foreground text by the syntax highlighter. Thus the concept of "theme" in delta encompasses not just the foreground syntax-highlighting color theme, but also background colors, decorations such as boxes and under/overlines, etc.
+
+The delta git repo contains a [collection of themes](./themes.gitconfig) created by users. These focus on the visual appearance: colors etc. If you want features like `side-by-side` or `navigate`, you would set that yourself, after selecting the color theme. To use the delta themes, clone the delta repo (or download the [themes.gitconfig](./themes.gitconfig) file) and add the following entry in your gitconfig:
+
+```gitconfig
+[include]
+    path = /PATH/TO/delta/themes.gitconfig
+```
+
+Then, add your chosen color theme to your features list, e.g.
+
+```gitconfig
+[delta]
+    features = collared-trogon
+    side-by-side = true
+    ...
+```
+
+Note that this terminology differs from [bat](https://github.com/sharkdp/bat): bat does not apply background colors, and uses the term "theme" to refer to what delta calls `syntax-theme`. Delta does not have a setting named "theme": a theme is a "feature", so one uses `features` to select a theme.
diff --git a/manual/src/delta-configs-used-in-screenshots.md b/manual/src/delta-configs-used-in-screenshots.md
new file mode 100644
index 00000000..faec6997
--- /dev/null
+++ b/manual/src/delta-configs-used-in-screenshots.md
@@ -0,0 +1,25 @@
+# Delta configs used in screenshots
+
+## Side-by-side view
+
+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/diff-highlight-and-diff-so-fancy-emulation.md b/manual/src/diff-highlight-and-diff-so-fancy-emulation.md
new file mode 100644
index 00000000..27056210
--- /dev/null
+++ b/manual/src/diff-highlight-and-diff-so-fancy-emulation.md
@@ -0,0 +1,11 @@
+# diff-highlight and diff-so-fancy emulation
+
+Use `--diff-highlight` or `--diff-so-fancy` to activate the respective emulation mode.
+
+You may want to know which delta configuration values the emulation mode has selected, so that you can adjust them. To do that, use e.g. `delta --diff-so-fancy --show-config`:
+
+<table><tr><td><img width=300px src="https://user-images.githubusercontent.com/52205/86271121-5abe4c80-bb9a-11ea-950a-7c79502267d5.png" alt="image" /></td></tr></table>
+
+[diff-highlight](https://github.com/git/git/tree/master/contrib/diff-highlight) is a perl script distributed with git that allows within-line edits to be identified and highlighted according to colors specified in git config. [diff-so-fancy](https://github.com/so-fancy/diff-so-fancy) builds on diff-highlight, making various additional improvements to the default git diff output. Both tools provide very helpful ways of viewing diffs, and so delta provides emulation modes for both of them.
+
+The within-line highlighting rules employed by diff-highlight (and therefore by diff-so-fancy) are deliberately simpler than Delta's Levenshtein-type edit inference algorithm (see discussion in the [diff-highlight README](https://github.com/git/git/tree/master/contrib/diff-highlight)). diff-highlight's rules could be added to delta as an alternative highlighting algorithm, but that hasn't been done yet.
diff --git a/manual/src/features-named-groups-of-settings.md b/manual/src/features-named-groups-of-settings.md
new file mode 100644
index 00000000..0dde9eb9
--- /dev/null
+++ b/manual/src/features-named-groups-of-settings.md
@@ -0,0 +1,27 @@
+# "Features": named groups of settings
+
+All delta options can go under the `[delta]` section in your git config file. However, you can also use named "features" to keep things organized: these are sections in git config like `[delta "my-feature"]`. Here's an example using two custom features:
+
+```gitconfig
+[delta]
+    features = unobtrusive-line-numbers decorations
+    whitespace-error-style = 22 reverse
+
+[delta "unobtrusive-line-numbers"]
+    line-numbers = true
+    line-numbers-minus-style = "#444444"
+    line-numbers-zero-style = "#444444"
+    line-numbers-plus-style = "#444444"
+    line-numbers-left-format = "{nm:>4}┊"
+    line-numbers-right-format = "{np:>4}│"
+    line-numbers-left-style = blue
+    line-numbers-right-style = blue
+
+[delta "decorations"]
+    commit-decoration-style = bold yellow box ul
+    file-style = bold yellow ul
+    file-decoration-style = none
+    hunk-header-decoration-style = yellow box
+```
+
+<table><tr><td><img width=400px src="https://user-images.githubusercontent.com/52205/86275048-a96ee500-bba0-11ea-8a19-584f69758aee.png" alt="image" /></td></tr></table>
diff --git a/manual/src/features.md b/manual/src/features.md
new file mode 100644
index 00000000..651b51f6
--- /dev/null
+++ b/manual/src/features.md
@@ -0,0 +1,32 @@
+# Features
+
+- Language syntax highlighting with color themes
+- Within-line highlights based on a Levenshtein edit inference algorithm
+- Side-by-side view with line-wrapping
+- Line numbering
+- `n` and `N` keybindings to move between files in large diffs, and between diffs in `log -p` views (`--navigate`)
+- Improved merge conflict display
+- Improved `git blame` display (syntax highlighting; `--hyperlinks` formats commits as links to GitHub/GitLab/Bitbucket etc)
+- Syntax-highlights grep output from `rg`, `git grep`, `grep`, etc
+- Support for Git's `--color-moved` feature.
+- Code can be copied directly from the diff (`-/+` markers are removed by default).
+- `diff-highlight` and `diff-so-fancy` emulation modes
+- Commit hashes can be formatted as terminal [hyperlinks](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda) to the GitHub/GitLab/Bitbucket page (`--hyperlinks`).
+  File paths can also be formatted as hyperlinks for opening in your OS.
+- Stylable box/line decorations to draw attention to commit, file and hunk header sections.
+- Git style strings (foreground color, background color, font attributes) are supported for >20 stylable elements
+
+|                                                | delta | git | [diff-so-fancy] /<br>[diff-highlight] | github/gitlab |
+| ---------------------------------------------- | ----- | --- | ------------------------------------- | ------------- |
+| language syntax highlighting                   | ✅    | ❌  | ❌                                    | ✅            |
+| within-line insertion/deletion detection       | ✅    | ❌  | ✅                                    | ✅            |
+| multiple insertion/deletions detected per line | ✅    | ❌  | ❌                                    | ✅            |
+| matching of unequal numbers of changed lines   | ✅    | ❌  | ❌                                    | ❌            |
+| independently stylable elements                | ✅    | ✅  | ✅                                    | ❌            |
+| line numbering                                 | ✅    | ❌  | ❌                                    | ✅            |
+| side-by-side view                              | ✅    | ❌  | ❌                                    | ✅            |
+
+In addition, delta handles traditional unified diff output.
+
+[diff-so-fancy]: https://github.com/so-fancy/diff-so-fancy
+[diff-highlight]: https://github.com/git/git/tree/master/contrib/diff-highlight
diff --git a/manual/src/full---help-output.md b/manual/src/full---help-output.md
new file mode 100644
index 00000000..9781145a
--- /dev/null
+++ b/manual/src/full---help-output.md
@@ -0,0 +1,536 @@
+# Full --help output
+
+```
+delta 0.11.3
+A viewer for git and diff output
+
+USAGE:
+    delta [FLAGS] [OPTIONS] [ARGS]
+
+FLAGS:
+        --light                      Use default colors appropriate for a light terminal background. For more control,
+                                     see the style options and --syntax-theme
+        --dark                       Use default colors appropriate for a dark terminal background. For more control,
+                                     see the style options and --syntax-theme
+    -n, --line-numbers               Display line numbers next to the diff. See LINE NUMBERS section
+    -s, --side-by-side               Display a side-by-side diff view instead of the traditional view
+        --diff-highlight             Emulate diff-highlight (https://github.com/git/git/tree/master/contrib/diff-highlight)
+        --diff-so-fancy              Emulate diff-so-fancy (https://github.com/so-fancy/diff-so-fancy)
+        --navigate                   Activate diff navigation: use n to jump forwards and N to jump backwards. To change
+                                     the file labels used see --file-modified-label, --file-removed-label, --file-added-
+                                     label, --file-renamed-label
+        --relative-paths             Output all file paths relative to the current directory so that they resolve
+                                     correctly when clicked on or used in shell commands
+        --hyperlinks                 Render commit hashes, file names, and line numbers as hyperlinks, according to the
+                                     hyperlink spec for terminal emulators:
+                                     https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda. By default,
+                                     file names and line numbers link to the local file using a file URL, whereas commit
+                                     hashes link to the commit in GitHub, if the remote repository is hosted by GitHub.
+                                     See --hyperlinks-file-link-format for full control over the file URLs emitted.
+                                     Hyperlinks are supported by several common terminal emulators. To make them work,
+                                     you must use less version >= 581 with the -R flag (or use -r with older less
+                                     versions, but this will break e.g. --navigate). If you use tmux, then y