color: document that "git -c color.*=always" is a bit specialjk/ui-color-always-to-auto-maint

When used from the command line as an option to "git" potty,
'always' does not get demoted to 'auto', to help third-party scripts
that (ab)used it to override the settings the end-user has.
Document it.

While at it, clarify description for per-command configuration
variables (color.branch, color.grep, color.interactive,
color.showBranch and color.status) so that they can more easily
share the new text to talk about this special-casing.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

1 files changed, 45 insertions, 23 deletions

diff --git a/Documentation/config.txt b/Documentation/config.txt
index cb0f951ddc..f79e82b79a 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -1051,11 +1051,15 @@ clean.requireForce::
 	-i or -n.   Defaults to true.
 
 color.branch::
-	A boolean to enable/disable color in the output of
-	linkgit:git-branch[1]. May be set to `false` (or `never`) to
-	disable color entirely, `auto` (or `true` or `always`) in which
-	case colors are used only when the output is to a terminal.  If
-	unset, then the value of `color.ui` is used (`auto` by default).
+	When to use color in the output of linkgit:git-branch[1].
+	May be set to `never` (or `false`) to disable color entirely,
+	or `auto` (or `true`) in which case colors are used only when
+	the output is to a terminal.  If unset, then the value of
+	`color.ui` is used (`auto` by default).
++
+The value `always` is a historical synonym for `auto`, except when
+passed on the command line using `-c`, where it is a historical synonym
+for `--color=always`.
 
 color.branch.<slot>::
 	Use customized color for branch coloration. `<slot>` is one of
@@ -1068,10 +1072,13 @@ color.diff::
 	Whether to use ANSI escape sequences to add color to patches.
 	If this is set to `true` or `auto`, linkgit:git-diff[1],
 	linkgit:git-log[1], and linkgit:git-show[1] will use color
-	when output is to the terminal. The value `always` is a
-	historical synonym for `auto`.  If unset, then the value of
+	when output is to the terminal. If unset, then the value of
 	`color.ui` is used (`auto` by default).
 +
+The value `always` is a historical synonym for `auto`, except when
+passed on the command line using `-c`, where it is a historical
+synonym for `--color=always`.
++
 This does not affect linkgit:git-format-patch[1] or the
 'git-diff-{asterisk}' plumbing commands.  Can be overridden on the
 command line with the `--color[=<when>]` option.
@@ -1091,10 +1098,14 @@ color.decorate.<slot>::
 	branches, remote-tracking branches, tags, stash and HEAD, respectively.
 
 color.grep::
-	When set to `always`, always highlight matches.  When `false` (or
+	When to highlight matches using color. When `false` (or
 	`never`), never.  When set to `true` or `auto`, use color only
 	when the output is written to the terminal.  If unset, then the
 	value of `color.ui` is used (`auto` by default).
++
+The value `always` is a historical synonym for `auto`, except when
+passed on the command line using `-c`, where it is a historical synonym
+for `--color=always`.
 
 color.grep.<slot>::
 	Use customized color for grep colorization.  `<slot>` specifies which
@@ -1126,9 +1137,11 @@ color.interactive::
 	When set to `true` or `auto`, use colors for interactive prompts
 	and displays (such as those used by "git-add --interactive" and
 	"git-clean --interactive") when the output is to the terminal.
-	When false (or `never`), never show colors. The value `always`
-	is a historical synonym for `auto`.  If unset, then the value of
-	`color.ui` is used (`auto` by default).
+	When false (or `never`), never show colors.
++
+The value `always` is a historical synonym for `auto`, except when
+passed on the command line using `-c`, where it means to use color
+regardless of whether output is to the terminal.
 
 color.interactive.<slot>::
 	Use customized color for 'git add --interactive' and 'git clean
@@ -1141,18 +1154,24 @@ color.pager::
 	use (default is true).
 
 color.showBranch::
-	A boolean to enable/disable color in the output of
-	linkgit:git-show-branch[1]. May be set to `always`,
-	`false` (or `never`) or `auto` (or `true`), in which case colors are used
-	only when the output is to a terminal. If unset, then the
-	value of `color.ui` is used (`auto` by default).
+	When to use color in the output of linkgit:git-show-branch[1].
+	May be set to `never` (or `false`) to disable color or `auto`
+	(or `true`) to use colors only when the output is to a terminal.
+	If unset, the value of `color.ui` is used (`auto` by default).
++
+The value `always` is a historical synonym for `auto`, except when
+passed on the command line using `-c`, where it is a historical synonym
+for `--color=always`.
 
 color.status::
-	A boolean to enable/disable color in the output of
-	linkgit:git-status[1]. May be set to `always`,
-	`false` (or `never`) or `auto` (or `true`), in which case colors are used
-	only when the output is to a terminal. If unset, then the
-	value of `color.ui` is used (`auto` by default).
+	When to use color in the output of linkgit:git-status[1].
+	May be set to `never` (or `false`) to disable color or `auto`
+	(or `true`) to use colors only when the output is to the terminal.
+	If unset, then the value of `color.ui` is used (`auto` by default).
++
+The value `always` is a historical synonym for `auto`, except when
+passed on the command line using `-c`, where it means to use color
+regardless of whether output is to the terminal.
 
 color.status.<slot>::
 	Use customized color for status colorization. `<slot>` is
@@ -1177,8 +1196,11 @@ color.ui::
 	color unless enabled explicitly with some other configuration
 	or the `--color` option. Set it to `true` or `auto` to enable
 	color when output is written to the terminal (this is also the
-	default since Git 1.8.4). The value `always` is a historical
-	synonym for `auto`.
+	default since Git 1.8.4).
++
+The value `always` is a historical synonym for `auto` (and its use is
+discouraged), except when passed on the command line using `-c`, where
+it means to use color regardless of whether output is to the terminal.
 
 column.ui::
 	Specify whether supported commands should output in columns.