Documentation: clarify the details of overriding LESS via core.pager

The process of overriding the default LESS options using only
git-specific methods is rather obscure.  Show the end user how
to do it in a step-by-step manner.

Signed-off-by: Chris Frey <cdfrey@foursquare.net>
Signed-off-by: Shawn O. Pearce <spearce@spearce.org>

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 3727239891321a52d16fa7f9ed73bf172b758c48..87b028fbc1817c9c641e5fe03aab641e3bd5eb63 100644 (file)
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -363,8 +363,17 @@ core.pager::
        variable.  Note that git sets the `LESS` environment
        variable to `FRSX` if it is unset when it runs the
        pager.  One can change these settings by setting the
        variable.  Note that git sets the `LESS` environment
        variable to `FRSX` if it is unset when it runs the
        pager.  One can change these settings by setting the

-       `LESS` variable to some other value or by giving the
-       `core.pager` option a value such as "`less -+FRSX`".
+       `LESS` variable to some other value.  Alternately,
+       these settings can be overridden on a project or
+       global basis by setting the `core.pager` option.
+       Setting `core.pager` has no affect on the `LESS`
+       environment variable behaviour above, so if you want
+       to override git's default settings this way, you need
+       to be explicit.  For example, to disable the S option
+       in a backward compatible manner, set `core.pager`
+       to "`less -+$LESS -FRX`".  This will be passed to the
+       shell by git, which will translate the final command to
+       "`LESS=FRSX less -+FRSX -FRX`".

 
 core.whitespace::
        A comma separated list of common whitespace problems to
 
 core.whitespace::
        A comma separated list of common whitespace problems to