From d94e3eac1011a5d54acb304a125f4cd2e0f2f4ab Mon Sep 17 00:00:00 2001 From: Brad King Date: Tue, 19 Nov 2024 10:45:42 -0500 Subject: [PATCH] Help: Clarify CLICOLOR and CLICOLOR_FORCE environment variables Document variable precedence. Link to third-party documentation of the convention these follow. For now, link to an older view of the documentation since our implementation has not been updated for `NO_COLOR`. Issue: #26458 --- Help/envvar/CLICOLOR.rst | 7 ++++++- Help/envvar/CLICOLOR_FORCE.rst | 7 ++++++- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/Help/envvar/CLICOLOR.rst b/Help/envvar/CLICOLOR.rst index 176bbfd9bb..404e79e7cb 100644 --- a/Help/envvar/CLICOLOR.rst +++ b/Help/envvar/CLICOLOR.rst @@ -5,10 +5,15 @@ CLICOLOR .. include:: ENV_VAR.txt -Set to ``0`` to tell CMake command-line tools not to print color +Set to ``0`` to tell command-line tools not to print color messages even if connected to a terminal. +This is a `common convention`_ among command-line tools in general. See also the :envvar:`CLICOLOR_FORCE` environment variable. +:envvar:`CLICOLOR_FORCE`, if activated, takes precedence over +:envvar:`!CLICOLOR`. See the :variable:`CMAKE_COLOR_DIAGNOSTICS` variable to control color in a generated build system. + +.. _`common convention`: https://web.archive.org/web/20230417221418/https://bixense.com/clicolors/ diff --git a/Help/envvar/CLICOLOR_FORCE.rst b/Help/envvar/CLICOLOR_FORCE.rst index b7b911823b..639ed8517e 100644 --- a/Help/envvar/CLICOLOR_FORCE.rst +++ b/Help/envvar/CLICOLOR_FORCE.rst @@ -5,10 +5,15 @@ CLICOLOR_FORCE .. include:: ENV_VAR.txt -Set to a non-empty value, other than ``0``, to tell CMake command-line +Set to a non-empty value, other than ``0``, to tell command-line tools to print color messages even if not connected to a terminal. +This is a `common convention`_ among command-line tools in general. See also the :envvar:`CLICOLOR` environment variable. +:envvar:`!CLICOLOR_FORCE`, if activated, takes precedence over +:envvar:`CLICOLOR`. See the :variable:`CMAKE_COLOR_DIAGNOSTICS` variable to control color in a generated build system. + +.. _`common convention`: https://web.archive.org/web/20230417221418/https://bixense.com/clicolors/