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

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

[Chris Frey]

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>
---

I recently upgraded to 1.6.0.2, and ran into the LESS problem again.
I usually just hacked the code, but figured this was sub-par, expecially
with the documentation recently upgraded to show me how to do it
with core.pager.

Unfortunately, it took me much longer than I would have expected.

I'm assuming others will have run into this as well, so here's
an update to the docs.

The most interesting feature I discovered while looking into this,
was that setting command line options in core.pager ends up using
the shell, which allows for additional trickery to make this
override truly git-specific.

Now I can have different less behaviour when using it myself vs.
using it through git.  In the same shell.  Regardless of how I
setup LESS.

- Chris


 Documentation/config.txt |   13 +++++++++++--
 1 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 922ac7b..9493621 100644
--- 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
-	`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
-- 
1.6.0.2

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

[Chris Frey]

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>
---

No comments on this patch last week, so sending again, to be
applied.

Thanks,
- Chris

 Documentation/config.txt |   13 +++++++++++--
 1 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 922ac7b..9493621 100644
--- 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
-	`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
-- 
1.6.0.2