Document new color-moved functionality

1 files changed, 33 insertions, 3 deletions

diff --git a/README.md b/README.md
index 9f77b0a..0876d71 100644
--- a/README.md
+++ b/README.md
@@ -492,13 +492,43 @@ To activate the Git feature, use
 
 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.
 
-In order to support this feature, Delta has to look at the raw colors it receives in a line from Git, and use them to judge whether it is a typical removed/added line, or a specially-colored moved line. This should just work. However, if it causes problems, the behavior can be disabled using
+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]
-    inspect-raw-lines = false
+    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>
+
 ### Navigation keybindings for large diffs
 
 Use the `navigate` feature to activate navigation keybindings. In this mode, pressing `n` will jump forward to the next file in the diff, and `N` will jump backwards. If you are viewing multiple commits (e.g. via `git log -p`) then navigation will also visit commit boundaries.