Junio C Hamano <gits...@pobox.com> writes:
> We need to be able to answer "why does '-c color.ui=always' work
> only from the command line?", but I doubt we want to actively
> encourage the use of it, though, so I dunno.
For today's pushout, I've queued this as [PATCH 3/2]
Thanks..
-- >8 --
From: Jonathan Nieder <jrnie...@gmail.com>
Subject: color: document that "git -c color.*=always" is a bit special
Date: Wed, 11 Oct 2017 21:47:24 -0700
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 <jrnie...@gmail.com>
Signed-off-by: Junio C Hamano <gits...@pobox.com>
---
Documentation/config.txt | 68 ++++++++++++++++++++++++++++++++----------------
1 file changed, 45 insertions(+), 23 deletions(-)
diff --git a/Documentation/config.txt b/Documentation/config.txt
index ba01b8d3df..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` and its use is discouraged.
+ 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.
--
2.15.0-rc1-154-g0b692121ee
