help: colorize man pages
PATCH v6 1/1 help: colorize man pages
We already colorize tools traditionally not colorized by default, like diff and grep. Let's do the same for man.
Our man pages don't contain many useful colors (just blue links), moreover, many people have groff SGR disabled, so they don't see any colors with man pages.
We can set LESS_TERMCAP variables to render bold and underlined text with colors in the pager; a common trick[1].
Bold is rendered as red, underlined as blue, and standout (prompt and highlighted search) as inverse cyan.
Obviously this only works when the less pager is used.
If the user already has LESS_TERMCAP variables set in his/her environment, those are respected and nothing changes.
A new color configuration is added: color.man for the people that want to turn this feature off, otherwise color.ui is respected. Additionally, if color.pager is not enabled, this is disregarded.
Normally check_auto_color() would check the value of color.pager, but in this particular case it's not git the one executing the pager, but man. Therefore we need to check pager_use_color ourselves.
Also--unlike other color.* configurations--color.man=always does not make any sense here; git help is always run for a tty (it would be very strange for a user to do git help $page > output, but in fact, that works anyway, we don't even need to check if stdout is a tty, but just to be consistent we do). So it's simply a boolean in our case.
So, in order for this change to have any effect:
1. The user must use less
2. Not have the same LESS_TERMCAP variables set
3. Have color.ui enabled
4. Not have color.pager disabled
5. Not have color.man disabled
7. Not have git with stdout directed to a file
Fortunately the vast majority of our users meet all of the above, and anybody who doesn't would not be affected negatively (plus very likely comprises a very tiny minority).
[1] https://unix.stackexchange.com/questions/119/colors-in-man-pages/147
Phillip Wood <[email protected]>
---
I returned back to the LESS_TERMCAP variables because -D options only exists for non-dos systems since 2021.
I tested this with a version of less that is 10 years old, and everything works as expected.
Also, I noticed less already chooses nice colors for standout with --use-color, and the prompt color is cyan, which is the fist one visible, so I changed standout to cyan.
Range-diff against v5:
1: 64c93d501f ! 1: 3a3e2837ad help: colorize man pages
@@ Commit message
moreover, many people have groff SGR disabled, so they don't see any colors with man pages.
- We can set the LESS variable to render bold, underlined, and standout
- text with colors in the less pager.
+ We can set LESS_TERMCAP variables to render bold and underlined text
+ with colors in the pager; a common trick[1].
Bold is rendered as red, underlined as blue, and standout (prompt and
- highlighted search) as inverse magenta.
+ highlighted search) as inverse cyan.
Obviously this only works when the less pager is used.
- If the user has already set the LESS variable in his/her environment,
- that is respected, and nothing changes. The same if any LESS_TERMCAP_*
- variables are set.
+ If the user already has LESS_TERMCAP variables set in his/her
+ environment, those are respected and nothing changes.
A new color configuration is added: color.man for the people that want to turn this feature off, otherwise color.ui is respected.
@@ Commit message
So, in order for this change to have any effect:
1. The user must use less
- 2. Not have the LESS variable set
+ 2. Not have the same LESS_TERMCAP variables set
3. Have color.ui enabled
4. Not have color.pager disabled
5. Not have color.man disabled
@@ Commit message
anybody who doesn't would not be affected negatively (plus very likely comprises a very tiny minority).
+ [1] https://unix.stackexchange.com/questions/119/colors-in-man-pages/147
+
Phillip Wood <[email protected]>
@@ builtin/help.c: static void exec_man_konqueror(const char *path, const char *pag
+ if (!man_color || !want_color(GIT_COLOR_UNKNOWN) || !pager_use_color)
+ return;
+
-+ /* User already has configured less colors */
-+ if (getenv("LESS_TERMCAP_md") ||
-+ getenv("LESS_TERMCAP_us") ||
-+ getenv("LESS_TERMCAP_so")) {
-+ return;
-+ }
-+
+ /* Disable groff colors */
+ setenv("GROFF_NO_SGR", "1", 0);
+
-+ /* Add red to bold, blue to underline, and magenta to standout */
-+ /* No visual information is lost */
-+ setenv("LESS", "Dd+r$Du+b$Ds+m", 0);
++ /* Bold */
++ setenv("LESS_TERMCAP_md", GIT_COLOR_BOLD_RED, 0);
++ setenv("LESS_TERMCAP_me", GIT_COLOR_RESET, 0);
++
++ /* Underline */
++ setenv("LESS_TERMCAP_us", GIT_COLOR_BLUE GIT_COLOR_UNDERLINE, 0);
++ setenv("LESS_TERMCAP_ue", GIT_COLOR_RESET, 0);
++
++ /* Standout */
++ setenv("LESS_TERMCAP_so", GIT_COLOR_CYAN GIT_COLOR_REVERSE, 0);
++ setenv("LESS_TERMCAP_se", GIT_COLOR_RESET, 0);
+}
+
static void exec_man_man(const char *path, const char *page)
@@ builtin/help.c: static int git_help_config(const char *var, const char *value, v
}
static struct cmdnames main_cmds, other_cmds;
+
+ ## color.h ##
+@@ color.h: struct strbuf;
+ #define GIT_COLOR_FAINT "\033[2m"
+ #define GIT_COLOR_FAINT_ITALIC "\033[2;3m"
+ #define GIT_COLOR_REVERSE "\033[7m"
++#define GIT_COLOR_UNDERLINE "\033[4m"
+
+ /* A special value meaning "no color selected" */
+ #define GIT_COLOR_NIL "NIL"
Documentation/config/color.txt | 5 +++++ builtin/help.c | 32 +++++++++++++++++++++++++++++++- color.h | 1 + 3 files changed, 37 insertions(+), 1 deletion(-)
Documentation/config/color.txt +5 -0
@@ -126,6 +126,11 @@ color.interactive.<slot>:: or `error`, for four distinct types of normal output from interactive commands. +color.man:: + This flag can be used to disable the automatic colorizaton of man + pages when using the less pager. It's activated only when color.ui + allows it, and also when color.pager is on. (`true` by default). + color.pager:: A boolean to enable/disable colored output when the pager is in use (default is true).
builtin/help.c +31 -1
@@ -11,6 +11,7 @@#include "config-list.h" #include "help.h" #include "alias.h" +#include "color.h" #ifndef DEFAULT_HELP_FORMAT #define DEFAULT_HELP_FORMAT "man"
@@ -43,6 +44,7 @@ static int verbose = 1;static unsigned int colopts;static enum help_format help_format =HELP_FORMAT_NONE ;static int exclude_guides; +static int man_color =1 ;static struct option builtin_help_options[] = {OPT_BOOL ('a' ,"all" , &show_all,N_ ("print all available commands" )),OPT_HIDDEN_BOOL (0 ,"exclude-guides" , &exclude_guides,N_ ("exclude guides" )),
@@ -253,10 +255,33 @@ static void exec_man_konqueror(const char *path, const char *page) } } +static void colorize_man (void ) +{ +if (!man_color || !want_color (GIT_COLOR_UNKNOWN ) || !pager_use_color) +return ; + +/* Disable groff colors */ +setenv ("GROFF_NO_SGR" ,"1" ,0 ); + +/* Bold */ +setenv ("LESS_TERMCAP_md" ,GIT_COLOR_BOLD_RED ,0 ); +setenv ("LESS_TERMCAP_me" ,GIT_COLOR_RESET ,0 ); + +/* Underline */ + setenv("LESS_TERMCAP_us", GIT_COLOR_BLUE GIT_COLOR_UNDERLINE, 0); +setenv ("LESS_TERMCAP_ue" ,GIT_COLOR_RESET ,0 ); + +/* Standout */ + setenv("LESS_TERMCAP_so", GIT_COLOR_CYAN GIT_COLOR_REVERSE, 0); +setenv ("LESS_TERMCAP_se" ,GIT_COLOR_RESET ,0 ); +} +static void exec_man_man (const char *path,const char *page) {if (!path) path ="man" ; + +colorize_man ();execlp (path,"man" , page, (char *)NULL );warning_errno (_ ("failed to exec '%s'" ), path); }
@@ -264,6 +289,7 @@ static void exec_man_man(const char *path, const char *page)static void exec_man_cmd (const char *cmd,const char *page) {struct strbuf shell_cmd =STRBUF_INIT ; +colorize_man ();strbuf_addf (&shell_cmd,"%s %s" , cmd, page);execl (SHELL_PATH ,SHELL_PATH ,"-c" , shell_cmd.buf, (char *)NULL );warning (_ ("failed to exec '%s'" ), cmd);
@@ -371,8 +397,12 @@ static int git_help_config(const char *var, const char *value, void *cb) }if (starts_with (var,"man." ))return add_man_viewer_info (var, value); +if (!strcmp (var,"color.man" )) { + man_color =git_config_bool (var, value); +return 0 ; + } -return git_default_config (var, value, cb); +return git_color_default_config (var, value, cb); }static struct cmdnames main_cmds, other_cmds;
color.h +1 -0
@@ -51,6 +51,7 @@ struct strbuf;#define GIT_COLOR_FAINT "\033[2m"#define GIT_COLOR_FAINT_ITALIC "\033[2;3m"#define GIT_COLOR_REVERSE "\033[7m" +#define GIT_COLOR_UNDERLINE "\033[4m"/* A special value meaning "no color selected" */ #define GIT_COLOR_NIL "NIL"
Signature · 1 line
2.32.0.rc0
Quoted 41 lines · Felipe Contreras
We already colorize tools traditionally not colorized by default, like diff and grep. Let's do the same for man.
Our man pages don't contain many useful colors (just blue links), moreover, many people have groff SGR disabled, so they don't see any colors with man pages.
We can set
LESS_TERMCAPvariables to render bold and underlined text with colors in the pager; a common trick[1].Bold is rendered as red, underlined as blue, and standout (prompt and highlighted search) as inverse cyan.
Obviously this only works when the less pager is used.
If the user already has
LESS_TERMCAPvariables set in his/her environment, those are respected and nothing changes.A new color configuration is added:
color.manfor the people that want to turn this feature off, otherwisecolor.uiis respected. Additionally, if color.pager is not enabled, this is disregarded.Normally
check_auto_color()would check the value ofcolor.pager, but in this particular case it's not git the one executing the pager, but man. Therefore we need to checkpager_use_colorourselves.Also--unlike other color.* configurations--color.man=always does not make any sense here;
git helpis always run for a tty (it would be very strange for a user to dogit help $page > output, but in fact, that works anyway, we don't even need to check if stdout is a tty, but just to be consistent we do). So it's simply a boolean in our case.So, in order for this change to have any effect:
1. The user must use less
2. Not have the sameLESS_TERMCAPvariables set
3. Have color.ui enabled
4. Not have color.pager disabled
5. Not have color.man disabled
7. Not have git with stdout directed to a file
Quoted 8 lines
Fortunately the vast majority of our users meet all of the above, and anybody who doesn't would not be affected negatively (plus very likely comprises a very tiny minority).
[1] https://unix.stackexchange.com/questions/119/colors-in-man-pages/147
Suggested-by Ævar Arnfjörð Bjarmason <[email protected]>Phillip Wood <[email protected]>
This footer seems to have got broken between v5 and v6 - were you intending to delete it (which is fine by me) as my comments were about the approach of the last patch?
I'm still not convinced that git should be messing with the appearance of man pages but I don't think we're ever going to agree on that.
Best Wishes
Phillip
Quoted 213 lines
Comments-by Jeff King <[email protected]>Signed-off-by Felipe Contreras <[email protected]>---
I returned back to the
LESS_TERMCAPvariables because -D options only exists for non-dos systems since 2021.I tested this with a version of less that is 10 years old, and everything works as expected.
Also, I noticed less already chooses nice colors for standout with --use-color, and the prompt color is cyan, which is the fist one visible, so I changed standout to cyan.
Range-diff against v5:
1:64c93d501f! 1:3a3e2837adhelp: colorize man pages
@@ Commit message
moreover, many people have groff SGR disabled, so they don't see any colors with man pages.- We can set the LESS variable to render bold, underlined, and standout
- text with colors in the less pager.
+ We can setLESS_TERMCAPvariables to render bold and underlined text
+ with colors in the pager; a common trick[1].Bold is rendered as red, underlined as blue, and standout (prompt and
- highlighted search) as inverse magenta.
+ highlighted search) as inverse cyan.Obviously this only works when the less pager is used.
- If the user has already set the LESS variable in his/her environment,
- that is respected, and nothing changes. The same if any LESS_TERMCAP_*
- variables are set.
+ If the user already hasLESS_TERMCAPvariables set in his/her
+ environment, those are respected and nothing changes.A new color configuration is added:
color.manfor the people that want to turn this feature off, otherwisecolor.uiis respected.
@@ Commit message
So, in order for this change to have any effect:1. The user must use less
- 2. Not have the LESS variable set
+ 2. Not have the sameLESS_TERMCAPvariables set
3. Have color.ui enabled
4. Not have color.pager disabled
5. Not have color.man disabled
@@ Commit message
anybody who doesn't would not be affected negatively (plus very likely comprises a very tiny minority).+ [1] https://unix.stackexchange.com/questions/119/colors-in-man-pages/147
+Suggested-by Ævar Arnfjörð Bjarmason <[email protected]>Phillip Wood <[email protected]>
Comments-by Jeff King <[email protected]>@@
builtin/help.c: static void exec_man_konqueror(const char *path, const char *pag
+ if (!man_color || !want_color(GIT_COLOR_UNKNOWN) || !pager_use_color)
+ return;
+
-+ /* User already has configured less colors */
-+ if (getenv("LESS_TERMCAP_md")||
-+getenv("LESS_TERMCAP_us")||
-+getenv("LESS_TERMCAP_so")) {
-+ return;
-+ }
-+
+ /* Disable groff colors */
+setenv("GROFF_NO_SGR", "1", 0);
+
-+ /* Add red to bold, blue to underline, and magenta to standout */
-+ /* No visual information is lost */
-+setenv("LESS", "Dd+r$Du+b$Ds+m", 0);
++ /* Bold */
++setenv("LESS_TERMCAP_md", GIT_COLOR_BOLD_RED, 0);
++setenv("LESS_TERMCAP_me", GIT_COLOR_RESET, 0);
++
++ /* Underline */
++setenv("LESS_TERMCAP_us", GIT_COLOR_BLUE GIT_COLOR_UNDERLINE, 0);
++setenv("LESS_TERMCAP_ue", GIT_COLOR_RESET, 0);
++
++ /* Standout */
++setenv("LESS_TERMCAP_so", GIT_COLOR_CYAN GIT_COLOR_REVERSE, 0);
++setenv("LESS_TERMCAP_se", GIT_COLOR_RESET, 0);
+}
+
static voidexec_man_man(const char *path, const char *page)
@@builtin/help.c: static int git_help_config(const char *var, const char *value, v
}static struct cmdnames
main_cmds,other_cmds;
+
+ ##color.h##
+@@color.h: struct strbuf;
+ #defineGIT_COLOR_FAINT"\033[2m"
+ #defineGIT_COLOR_FAINT_ITALIC"\033[2;3m"
+ #defineGIT_COLOR_REVERSE"\033[7m"
++#defineGIT_COLOR_UNDERLINE"\033[4m"
+
+ /* A special value meaning "no color selected" */
+ #defineGIT_COLOR_NIL"NIL"Documentation/config/color.txt | 5 +++++ builtin/help.c | 32 +++++++++++++++++++++++++++++++- color.h | 1 + 3 files changed, 37 insertions(+), 1 deletion(-)Documentation/config/color.txt +5
-0@@ -126,6 +126,11 @@ color.interactive.<slot>:: or `error`, for four distinct types of normal output from interactive commands. +color.man:: + This flag can be used to disable the automatic colorizaton of man + pages when using the less pager. It's activated only when color.ui + allows it, and also when color.pager is on. (`true` by default). + color.pager:: A boolean to enable/disable colored output when the pager is in use (default is true).builtin/help.c +31
-1@@ -11,6 +11,7 @@#include "config-list.h" #include "help.h" #include "alias.h" +#include "color.h" #ifndef DEFAULT_HELP_FORMAT #define DEFAULT_HELP_FORMAT "man"@@ -43,6 +44,7 @@ static int verbose = 1;static unsigned int colopts;static enum help_format help_format =HELP_FORMAT_NONE ;static int exclude_guides; +static int man_color =1 ;static struct option builtin_help_options[] = {OPT_BOOL ('a' ,"all" , &show_all,N_ ("print all available commands" )),OPT_HIDDEN_BOOL (0 ,"exclude-guides" , &exclude_guides,N_ ("exclude guides" )),@@ -253,10 +255,33 @@ static void exec_man_konqueror(const char *path, const char *page) } } +static void colorize_man (void ) +{ +if (!man_color || !want_color (GIT_COLOR_UNKNOWN ) || !pager_use_color) +return ; + +/* Disable groff colors */ +setenv ("GROFF_NO_SGR" ,"1" ,0 ); + +/* Bold */ +setenv ("LESS_TERMCAP_md" ,GIT_COLOR_BOLD_RED ,0 ); +setenv ("LESS_TERMCAP_me" ,GIT_COLOR_RESET ,0 ); + +/* Underline */ + setenv("LESS_TERMCAP_us", GIT_COLOR_BLUE GIT_COLOR_UNDERLINE, 0); +setenv ("LESS_TERMCAP_ue" ,GIT_COLOR_RESET ,0 ); + +/* Standout */ + setenv("LESS_TERMCAP_so", GIT_COLOR_CYAN GIT_COLOR_REVERSE, 0); +setenv ("LESS_TERMCAP_se" ,GIT_COLOR_RESET ,0 ); +} +static void exec_man_man (const char *path,const char *page) {if (!path) path ="man" ; + +colorize_man ();execlp (path,"man" , page, (char *)NULL );warning_errno (_ ("failed to exec '%s'" ), path); }@@ -264,6 +289,7 @@ static void exec_man_man(const char *path, const char *page)static void exec_man_cmd (const char *cmd,const char *page) {struct strbuf shell_cmd =STRBUF_INIT ; +colorize_man ();strbuf_addf (&shell_cmd,"%s %s" , cmd, page);execl (SHELL_PATH ,SHELL_PATH ,"-c" , shell_cmd.buf, (char *)NULL );warning (_ ("failed to exec '%s'" ), cmd);@@ -371,8 +397,12 @@ static int git_help_config(const char *var, const char *value, void *cb) }if (starts_with (var,"man." ))return add_man_viewer_info (var, value); +if (!strcmp (var,"color.man" )) { + man_color =git_config_bool (var, value); +return 0 ; + } -return git_default_config (var, value, cb); +return git_color_default_config (var, value, cb); }static struct cmdnames main_cmds, other_cmds;color.h +1
-0@@ -51,6 +51,7 @@ struct strbuf;#define GIT_COLOR_FAINT "\033[2m"#define GIT_COLOR_FAINT_ITALIC "\033[2;3m"#define GIT_COLOR_REVERSE "\033[7m" +#define GIT_COLOR_UNDERLINE "\033[4m"/* A special value meaning "no color selected" */ #define GIT_COLOR_NIL "NIL"
Quoted 8 lines · Phillip Wood
Quoted 2 lines · Felipe Contreras
Suggested-by Ævar Arnfjörð Bjarmason <[email protected]>Phillip Wood <[email protected]>
This footer seems to have got broken between v5 and v6 - were you intending to delete it (which is fine by me) as my comments were about the approach of the last patch?
I was probably trying to put you in the Cc list.
Quoted 2 lines
I'm still not convinced that git should be messing with the appearance of man pages but I don't think we're ever going to agree on that.
That's your opinion, and it's fine, we all have opinions.
But the interesting thing for everyone else is *why*. Why aren't you convinced?
I still haven't heard a convincing argument regarding what makes git help fundamentally different from git diff _for the user_.
Cheers.
Signature · 1 line
Felipe Contreras
Quoted 45 lines · Felipe Contreras
We already colorize tools traditionally not colorized by default, like diff and grep. Let's do the same for man.
Our man pages don't contain many useful colors (just blue links), moreover, many people have groff SGR disabled, so they don't see any colors with man pages.
We can set
LESS_TERMCAPvariables to render bold and underlined text with colors in the pager; a common trick[1].Bold is rendered as red, underlined as blue, and standout (prompt and highlighted search) as inverse cyan.
Obviously this only works when the less pager is used.
If the user already has
LESS_TERMCAPvariables set in his/her environment, those are respected and nothing changes.A new color configuration is added:
color.manfor the people that want to turn this feature off, otherwisecolor.uiis respected. Additionally, if color.pager is not enabled, this is disregarded.Normally
check_auto_color()would check the value ofcolor.pager, but in this particular case it's not git the one executing the pager, but man. Therefore we need to checkpager_use_colorourselves.Also--unlike other color.* configurations--color.man=always does not make any sense here;
git helpis always run for a tty (it would be very strange for a user to dogit help $page > output, but in fact, that works anyway, we don't even need to check if stdout is a tty, but just to be consistent we do). So it's simply a boolean in our case.So, in order for this change to have any effect:
1. The user must use less
2. Not have the sameLESS_TERMCAPvariables set
3. Have color.ui enabled
4. Not have color.pager disabled
5. Not have color.man disabled
7. Not have git with stdout directed to a fileFortunately the vast majority of our users meet all of the above, and anybody who doesn't would not be affected negatively (plus very likely comprises a very tiny minority).
Quoted 7 lines
[1] https://unix.stackexchange.com/questions/119/colors-in-man-pages/147
Suggested-by Ævar Arnfjörð Bjarmason <[email protected]>Phillip Wood <[email protected]>
Comments-by Jeff King <[email protected]>Signed-off-by Felipe Contreras <[email protected]>---
I've been running with this on my personal git build since May 26th. I haven't had any issues with it, and I like the new coloring.
I for one would like to have this picked up by Junio.
I think this is a good example of a change that we're better off just merging down and then reverting if the wider audience of git users hates it, rather than trying to come to some perfect consensus here on-list.
We have a wider audience running "next" than "seen" (but this didn't even make "seen"), if this were to make it into a release and users overwhelmingly dislike it it's no big deal. There's a config option to turn it off, and/or we could make it opt-in later.
Alternatively this could be opt-in and not fall under the color.ui=auto umbrella, or only in combination with feature.experimental (or a new ui.experimental?, which would default to that?).
But in any case if judgement call UI changes are always hidden behind options we'll never make forward progress on things that are possibly better defaults (and if they're not, we can always simply revert the change).
Quoted 7 lines · Ævar Arnfjörð Bjarmason
I've been running with this on my personal git build since May 26th. I haven't had any issues with it, and I like the new coloring.
...
I think this is a good example of a change that we're better off just merging down and then reverting if the wider audience of git users hates it, rather than trying to come to some perfect consensus here on-list.
My impression was tht we already had a rough consensus here on-list that it may be good to educate users who like this "new coloring" like you do to configure their "less", so that they consistently get the "new coloring" they like whether they are doing "git help git", "man git", or even "man ls", and the approach the posted patch takes will not help (it only affects "git help git" among these).
I'd rather not to take it.
Thanks.
Quoted 10 lines · Junio C Hamano
Quoted 7 lines · Ævar Arnfjörð Bjarmason
I've been running with this on my personal git build since May 26th. I haven't had any issues with it, and I like the new coloring.
...
I think this is a good example of a change that we're better off just merging down and then reverting if the wider audience of git users hates it, rather than trying to come to some perfect consensus here on-list.
Quoted 3 lines
My impression was tht we already had a rough consensus here on-list that it may be good to educate users who like this "new coloring" like you do to configure their "less",
Not true.
Jeff said users would probably have configured man to use colors themselves, but he never responded back when I asked him *how* [1].
It is a tricky question, because I already know it's not possible to do it in a way that works in all distributions, for all programs without polluting the user environment to do things she probably doesn't want.
Quoted 4 lines
so that they consistently get the "new coloring" they like whether they are doing "git help git", "man git", or even "man ls", and the approach the posted patch takes will not help (it only affects "git help git" among these).
Please explain exactly *how* the user will be able to do that.
Moreover. I don't think git should be in the business of educating users how to use other software. The way they use less in conjunction with other software is up to them.
And in fact we already help naive users that have not configured their pager, so that it works better in git.
We do this for them:
LESS=FRX LV=-c # see PAGER_ENV
Why aren't we "educating them" about LESS=FRX instead?
We have set good defaults for less since pretty much the start:
f67b45f862 (Introduce trivial new pager.c helper infrastructure, 2006-02-28)
I don't think Jeff is the consensus. He expressed an opinion that perhaps X is better, but without clearly defining X, that's not really a viable option.
Quoted 1 line
I'd rather not to take it.
Can you explain why? All the outstanding comments have been addressed.
Cheers.
[1] https://lore.kernel.org/git/[email protected]/
Signature · 1 line
Felipe Contreras
PATCH v7 1/1 help: colorize man pages if man.color=true under less(1)
In reply to Junio C HamanoFrom: Felipe Contreras <[email protected]>
We already colorize tools traditionally not colorized by default, like diff and grep. Let's do the same for man, but only if color.man is explicitly set to "true".
Unlike other color.* output this colorization is not enabled by color.ui being true, the user needs to explicitly set the color.man variable to `true.
When it was proposed to treat color.man like any other color.* variable some thought that git opting in coloring for an external program such as man(1) was a step too far[1], even if the user invoked it via the "git help <topic>" wrapper.
So let's make this explicitly opt-in for now. As noted in the documentation we're leaving ourselves an out to turn this on by default in the future, or e.g. putting it under the feature.experimental umbrella. We probably won't, but let's not promise users that color.man will forever be a special-case.
As for what this actually does the effect of having this enabled is that a documentation blurb like (some parts elided with "[...]"):
NAME ---- git-config - Get and set [...] SYNOPSIS -------- [...] 'git config' [<file-option>] [...] [...] The `--type=<type>` option instructs 'git config' to ensure [...]
Will have "NAME" and "SECTION" shown as BOLD RED instead of BOLD, "git config" and other '-quoted parts in BLUE UNDERLINE instead of UNDERLINE, and --type=<type> and other `-quoted parts in RED BOLD instead of BOLD. The "Standout" setting is then used for the user's own search bar (invoked with "/") and prompt. See [2] for more examples
Normally check_auto_color() would check the value of color.pager, but in this particular case it's not git the one executing the pager, but man. Therefore we need to check pager_use_color ourselves.
We do not need to support color.man being set to always; The git help command is always run for a tty (it would be very strange for a user to do git help $page > output, but in fact, that works anyway, we don't even need to check if stdout is a tty, but just to be consistent we do). So it's simply a boolean in our case.
So, in order for this change to have any effect:
1. color.man=true must be set in the config
2. The user must use less
3. Not have the same LESS_TERMCAP variables set (we call setenv(3) with overwrite=0)
4. Have color.ui enabled
5. Not have color.pager disabled
6. Not have git with stdout directed to a file
1. https://lore.kernel.org/git/[email protected]/
2. https://unix.stackexchange.com/questions/119/colors-in-man-pages/147
---
Quoted 10 lines · Junio C Hamano
Quoted 7 lines · Ævar Arnfjörð Bjarmason
I've been running with this on my personal git build since May 26th. I haven't had any issues with it, and I like the new coloring.
...
I think this is a good example of a change that we're better off just merging down and then reverting if the wider audience of git users hates it, rather than trying to come to some perfect consensus here on-list.
Quoted 8 lines
My impression was tht we already had a rough consensus here on-list that it may be good to educate users who like this "new coloring" like you do to configure their "less", so that they consistently get the "new coloring" they like whether they are doing "git help git", "man git", or even "man ls", and the approach the posted patch takes will not help (it only affects "git help git" among these).
I'd rather not to take it.
Fair enough, here's a version I think you and others will find acceptable then. It allows users like me who like this to explicitly opt-in via color.man=true.
I also took the liberty of making some changes to the commit message to reword it for this new behavior, and to show an example of the sort of colors that change with this patch.
The only change to the patch itself is that now color_man is set to 0 by default, not 1. I also moved its declaration so that it's with the one other config variable, insted of with the other command-line options to "git help".
Range-diff against v6:
1: e021ca1da21 ! 1: a950ef49e28 help: colorize man pages
@@ Metadata
Author: Felipe Contreras <[email protected]>
## Commit message ##
- help: colorize man pages
+ help: colorize man pages if man.color=true under less(1)
We already colorize tools traditionally not colorized by default, like
- diff and grep. Let's do the same for man.
-
- Our man pages don't contain many useful colors (just blue links),
- moreover, many people have groff SGR disabled, so they don't see any
- colors with man pages.
-
- We can set LESS_TERMCAP variables to render bold and underlined text
- with colors in the pager; a common trick[1].
-
- Bold is rendered as red, underlined as blue, and standout (prompt and
- highlighted search) as inverse cyan.
-
- Obviously this only works when the less pager is used.
-
- If the user already has LESS_TERMCAP variables set in his/her
- environment, those are respected and nothing changes.
-
- A new color configuration is added: color.man for the people that want
- to turn this feature off, otherwise color.ui is respected.
- Additionally, if color.pager is not enabled, this is disregarded.
+ diff and grep. Let's do the same for man, but only if color.man is
+ explicitly set to "true".
+
+ Unlike other color.* output this colorization is not enabled by
+ color.ui being true, the user needs to explicitly set the
+ color.man variable to `true.
+
+ When it was proposed to treat color.man like any other color.*
+ variable some thought that git opting in coloring for an external
+ program such as man(1) was a step too far[1], even if the user invoked
+ it via the "git help <topic>" wrapper.
+
+ So let's make this explicitly opt-in for now. As noted in the
+ documentation we're leaving ourselves an out to turn this on by
+ default in the future, or e.g. putting it under the
+ feature.experimental umbrella. We probably won't, but let's not
+ promise users that color.man will forever be a special-case.
+
+ As for what this actually does the effect of having this enabled is
+ that a documentation blurb like (some parts elided with "[...]"):
+
+ NAME
+ ----
+ git-config - Get and set [...]
+
+ SYNOPSIS
+ --------
+ [...]
+ 'git config' [<file-option>] [...]
+ [...]
+ The --type=<type> option instructs 'git config' to ensure [...]
+
+ Will have "NAME" and "SECTION" shown as BOLD RED instead of BOLD, "git
+ config" and other '-quoted parts in BLUE UNDERLINE instead of
+ UNDERLINE, and --type=<type> and other `-quoted parts in RED BOLD
+ instead of BOLD. The "Standout" setting is then used for the user's
+ own search bar (invoked with "/") and prompt. See [2] for more
+ examples
Normally check_auto_color() would check the value of color.pager, but in this particular case it's not git the one executing the pager, but man. Therefore we need to check pager_use_color ourselves.
- Also--unlike other color.* configurations--color.man=always does not
- make any sense here; git help is always run for a tty (it would be very
- strange for a user to do git help $page > output, but in fact, that
- works anyway, we don't even need to check if stdout is a tty, but just
- to be consistent we do). So it's simply a boolean in our case.
+ We do not need to support color.man being set to always; The `git
+ help` command is always run for a tty (it would be very strange for a
+ user to do git help $page > output, but in fact, that works anyway,
+ we don't even need to check if stdout is a tty, but just to be
+ consistent we do). So it's simply a boolean in our case.
So, in order for this change to have any effect:
- 1. The user must use less
- 2. Not have the same LESS_TERMCAP variables set
- 3. Have color.ui enabled
- 4. Not have color.pager disabled
- 5. Not have color.man disabled
- 7. Not have git with stdout directed to a file
-
- Fortunately the vast majority of our users meet all of the above, and
- anybody who doesn't would not be affected negatively (plus very likely
- comprises a very tiny minority).
+ 1. color.man=true must be set in the config
+ 2. The user must use less
+ 3. Not have the same LESS_TERMCAP variables set (we call setenv(3) with overwrite=0)
+ 4. Have color.ui enabled
+ 5. Not have color.pager disabled
+ 6. Not have git with stdout directed to a file
- [1] https://unix.stackexchange.com/questions/119/colors-in-man-pages/147
+ 1. https://lore.kernel.org/git/[email protected]/
+ 2. https://unix.stackexchange.com/questions/119/colors-in-man-pages/147
- Phillip Wood <[email protected]>
- Comments-by: Jeff King <[email protected]>
+ Signed-off-by: Ævar Arnfjörð Bjarmason <[email protected]>
## Documentation/config/color.txt ##
@@ Documentation/config/color.txt: color.interactive.<slot>::
@@ Documentation/config/color.txt: color.interactive.<slot>::
interactive commands.
+color.man::
-+ This flag can be used to disable the automatic colorizaton of man
-+ pages when using the less pager. It's activated only when color.ui
-+ allows it, and also when color.pager is on. (true by default).
++ This flag can be used to enable the automatic colorizaton of man
++ pages when using the less pager, false by default. When set to
++ true it's activated only when color.ui allows it, and if
++ color.pager enable (which it is by default).
+
color.pager::
- A boolean to enable/disable colored output when the pager is in
- use (default is true).
+ A boolean to specify whether auto color modes should colorize
+ output going to the pager. Defaults to true; set this to false
+@@ Documentation/config/color.txt: color.ui::
+ output not intended for machine consumption to use color, to
+ true or auto (this is the default since Git 1.8.4) if you
+ want such output to use color when written to the terminal.
+++
++When set to true certain other color.* variables may still not be ++turned on unless explicitly enabled. Currently this only applies to ++color.man, see above. Such opt-in variables may be moved under the ++default color.ui umbrella in the future.
## builtin/help.c ##
@@
@@ builtin/help.c
#ifndef DEFAULT_HELP_FORMAT
#define DEFAULT_HELP_FORMAT "man"
-@@ builtin/help.c: static int verbose = 1;
- static unsigned int colopts;
- static enum help_format help_format = HELP_FORMAT_NONE;
- static int exclude_guides;
-+static int man_color = 1;
- static struct option builtin_help_options[] = {
- OPT_BOOL('a', "all", &show_all, N_("print all available commands")),
- OPT_HIDDEN_BOOL(0, "exclude-guides", &exclude_guides, N_("exclude guides")),
+@@ builtin/help.c: enum help_format {
+ HELP_FORMAT_WEB
+ };
+
++static int man_color;
+ static const char *html_path;
+
+ static int show_all = 0;
@@ builtin/help.c: static void exec_man_konqueror(const char *path, const char *page)
}
}
Documentation/config/color.txt | 11 +++++++++++ builtin/help.c | 32 +++++++++++++++++++++++++++++++- color.h | 1 + 3 files changed, 43 insertions(+), 1 deletion(-)
Documentation/config/color.txt +11 -0
@@ -126,6 +126,12 @@ color.interactive.<slot>:: or `error`, for four distinct types of normal output from interactive commands. +color.man:: + This flag can be used to enable the automatic colorizaton of man + pages when using the less pager, `false` by default. When set to + `true` it's activated only when `color.ui` allows it, and if + `color.pager` enable (which it is by default). + color.pager:: A boolean to specify whether `auto` color modes should colorize output going to the pager. Defaults to true; set this to false
@@ -200,3 +206,8 @@ color.ui:: output not intended for machine consumption to use color, to `true` or `auto` (this is the default since Git 1.8.4) if you want such output to use color when written to the terminal. ++ +When set to `true` certain other `color.*` variables may still not be +turned on unless explicitly enabled. Currently this only applies to +`color.man`, see above. Such opt-in variables may be moved under the +default `color.ui` umbrella in the future.
builtin/help.c +31 -1
@@ -11,6 +11,7 @@#include "config-list.h" #include "help.h" #include "alias.h" +#include "color.h" #ifndef DEFAULT_HELP_FORMAT #define DEFAULT_HELP_FORMAT "man"
@@ -34,6 +35,7 @@ enum help_format { HELP_FORMAT_WEB }; +static int man_color;static const char *html_path;static int show_all =0 ;
@@ -253,10 +255,33 @@ static void exec_man_konqueror(const char *path, const char *page) } } +static void colorize_man (void ) +{ +if (!man_color || !want_color (GIT_COLOR_UNKNOWN ) || !pager_use_color) +return ; + +/* Disable groff colors */ +setenv ("GROFF_NO_SGR" ,"1" ,0 ); + +/* Bold */ +setenv ("LESS_TERMCAP_md" ,GIT_COLOR_BOLD_RED ,0 ); +setenv ("LESS_TERMCAP_me" ,GIT_COLOR_RESET ,0 ); + +/* Underline */ + setenv("LESS_TERMCAP_us", GIT_COLOR_BLUE GIT_COLOR_UNDERLINE, 0); +setenv ("LESS_TERMCAP_ue" ,GIT_COLOR_RESET ,0 ); + +/* Standout */ + setenv("LESS_TERMCAP_so", GIT_COLOR_CYAN GIT_COLOR_REVERSE, 0); +setenv ("LESS_TERMCAP_se" ,GIT_COLOR_RESET ,0 ); +} +static void exec_man_man (const char *path,const char *page) {if (!path) path ="man" ; + +colorize_man ();execlp (path,"man" , page, (char *)NULL );warning_errno (_ ("failed to exec '%s'" ), path); }
@@ -264,6 +289,7 @@ static void exec_man_man(const char *path, const char *page)static void exec_man_cmd (const char *cmd,const char *page) {struct strbuf shell_cmd =STRBUF_INIT ; +colorize_man ();strbuf_addf (&shell_cmd,"%s %s" , cmd, page);execl (SHELL_PATH ,SHELL_PATH ,"-c" , shell_cmd.buf, (char *)NULL );warning (_ ("failed to exec '%s'" ), cmd);
@@ -371,8 +397,12 @@ static int git_help_config(const char *var, const char *value, void *cb) }if (starts_with (var,"man." ))return add_man_viewer_info (var, value); +if (!strcmp (var,"color.man" )) { + man_color =git_config_bool (var, value); +return 0 ; + } -return git_default_config (var, value, cb); +return git_color_default_config (var, value, cb); }static struct cmdnames main_cmds, other_cmds;
color.h +1 -0
@@ -51,6 +51,7 @@ struct strbuf;#define GIT_COLOR_FAINT "\033[2m"#define GIT_COLOR_FAINT_ITALIC "\033[2;3m"#define GIT_COLOR_REVERSE "\033[7m" +#define GIT_COLOR_UNDERLINE "\033[4m"/* A special value meaning "no color selected" */ #define GIT_COLOR_NIL "NIL"
Signature · 1 line
2.32.0.599.g672d808136f
Re: [PATCH v7] help: colorize man pages if man.color=true under less(1)
Quoted 61 lines · Ævar Arnfjörð Bjarmason
From: Felipe Contreras <[email protected]>
We already colorize tools traditionally not colorized by default, like diff and grep. Let's do the same for man, but only if
color.manis explicitly set to "true".Unlike other
color.*output this colorization is not enabled bycolor.uibeing true, the user needs to explicitly set thecolor.manvariable to `true.When it was proposed to treat
color.manlike any othercolor.*variable some thought that git opting in coloring for an external program such as man(1) was a step too far[1], even if the user invoked it via the "git help <topic>" wrapper.So let's make this explicitly opt-in for now. As noted in the documentation we're leaving ourselves an out to turn this on by default in the future, or e.g. putting it under the feature.experimental umbrella. We probably won't, but let's not promise users that
color.manwill forever be a special-case.As for what this actually does the effect of having this enabled is that a documentation blurb like (some parts elided with "[...]"):
NAME ---- git-config - Get and set [...] SYNOPSIS -------- [...] 'git config' [<file-option>] [...] [...] The `--type=<type>` option instructs 'git config' to ensure [...]Will have "NAME" and "SECTION" shown as BOLD RED instead of BOLD, "git config" and other '-quoted parts in BLUE UNDERLINE instead of UNDERLINE, and
--type=<type>and other `-quoted parts in RED BOLD instead of BOLD. The "Standout" setting is then used for the user's own search bar (invoked with "/") and prompt. See [2] for more examplesNormally
check_auto_color()would check the value ofcolor.pager, but in this particular case it's not git the one executing the pager, but man. Therefore we need to checkpager_use_colorourselves.We do not need to support
color.manbeing set toalways; Thegit helpcommand is always run for a tty (it would be very strange for a user to dogit help $page > output, but in fact, that works anyway, we don't even need to check if stdout is a tty, but just to be consistent we do). So it's simply a boolean in our case.So, in order for this change to have any effect:
1. color.man=true must be set in the config
2. The user must use less
3. Not have the sameLESS_TERMCAPvariables set (we call setenv(3) with overwrite=0)
4. Have color.ui enabled
5. Not have color.pager disabled
6. Not have git with stdout directed to a file
Quoted 2 lines
1. https://lore.kernel.org/git/[email protected]/
2. https://unix.stackexchange.com/questions/119/colors-in-man-pages/147
Thanks for taking the time to write such a clear and comprehensive message, I think making this setting opt in for now makes sense. I've left a couple of comments below.
Quoted 217 lines
Suggested-by Ævar Arnfjörð Bjarmason <[email protected]>Signed-off-by Felipe Contreras <[email protected]>Signed-off-by Ævar Arnfjörð Bjarmason <[email protected]>---
Quoted 10 lines · Junio C Hamano
Quoted 7 lines · Ævar Arnfjörð Bjarmason
I've been running with this on my personal git build since May 26th. I haven't had any issues with it, and I like the new coloring.
...
I think this is a good example of a change that we're better off just merging down and then reverting if the wider audience of git users hates it, rather than trying to come to some perfect consensus here on-list.Quoted 8 lines
My impression was tht we already had a rough consensus here on-list that it may be good to educate users who like this "new coloring" like you do to configure their "less", so that they consistently get the "new coloring" they like whether they are doing "git help git", "man git", or even "man ls", and the approach the posted patch takes will not help (it only affects "git help git" among these).
I'd rather not to take it.
Fair enough, here's a version I think you and others will find acceptable then. It allows users like me who like this to explicitly opt-in via color.man=true.
I also took the liberty of making some changes to the commit message to reword it for this new behavior, and to show an example of the sort of colors that change with this patch.
The only change to the patch itself is that now
color_manis set to 0 by default, not 1. I also moved its declaration so that it's with the one other config variable, insted of with the other command-line options to "git help".Range-diff against v6:
1:e021ca1da21! 1:a950ef49e28help: colorize man pages
@@ Metadata
Author: Felipe Contreras <[email protected]>## Commit message ##
- help: colorize man pages
+ help: colorize man pages if man.color=true under less(1)We already colorize tools traditionally not colorized by default, like
- diff and grep. Let's do the same for man.
-
- Our man pages don't contain many useful colors (just blue links),
- moreover, many people have groff SGR disabled, so they don't see any
- colors with man pages.
-
- We can setLESS_TERMCAPvariables to render bold and underlined text
- with colors in the pager; a common trick[1].
-
- Bold is rendered as red, underlined as blue, and standout (prompt and
- highlighted search) as inverse cyan.
-
- Obviously this only works when the less pager is used.
-
- If the user already hasLESS_TERMCAPvariables set in his/her
- environment, those are respected and nothing changes.
-
- A new color configuration is added:color.manfor the people that want
- to turn this feature off, otherwisecolor.uiis respected.
- Additionally, if color.pager is not enabled, this is disregarded.
+ diff and grep. Let's do the same for man, but only ifcolor.manis
+ explicitly set to "true".
+
+ Unlike othercolor.*output this colorization is not enabled by
+color.uibeing true, the user needs to explicitly set the
+color.manvariable to `true.
+
+ When it was proposed to treatcolor.manlike any othercolor.*
+ variable some thought that git opting in coloring for an external
+ program such as man(1) was a step too far[1], even if the user invoked
+ it via the "git help <topic>" wrapper.
+
+ So let's make this explicitly opt-in for now. As noted in the
+ documentation we're leaving ourselves an out to turn this on by
+ default in the future, or e.g. putting it under the
+ feature.experimental umbrella. We probably won't, but let's not
+ promise users thatcolor.manwill forever be a special-case.
+
+ As for what this actually does the effect of having this enabled is
+ that a documentation blurb like (some parts elided with "[...]"):
+
+ NAME
+ ----
+ git-config - Get and set [...]
+
+ SYNOPSIS
+ --------
+ [...]
+ 'git config' [<file-option>] [...]
+ [...]
+ The--type=<type>option instructs 'git config' to ensure [...]
+
+ Will have "NAME" and "SECTION" shown as BOLD RED instead of BOLD, "git
+ config" and other '-quoted parts in BLUE UNDERLINE instead of
+ UNDERLINE, and--type=<type>and other `-quoted parts in RED BOLD
+ instead of BOLD. The "Standout" setting is then used for the user's
+ own search bar (invoked with "/") and prompt. See [2] for more
+ examplesNormally
check_auto_color()would check the value ofcolor.pager, but in this particular case it's not git the one executing the pager, but man. Therefore we need to checkpager_use_colorourselves.- Also--unlike other color.* configurations--color.man=always does not
- make any sense here;git helpis always run for a tty (it would be very
- strange for a user to dogit help $page > output, but in fact, that
- works anyway, we don't even need to check if stdout is a tty, but just
- to be consistent we do). So it's simply a boolean in our case.
+ We do not need to supportcolor.manbeing set toalways; The `git
+ help` command is always run for a tty (it would be very strange for a
+ user to dogit help $page > output, but in fact, that works anyway,
+ we don't even need to check if stdout is a tty, but just to be
+ consistent we do). So it's simply a boolean in our case.So, in order for this change to have any effect:
- 1. The user must use less
- 2. Not have the sameLESS_TERMCAPvariables set
- 3. Have color.ui enabled
- 4. Not have color.pager disabled
- 5. Not have color.man disabled
- 7. Not have git with stdout directed to a file
-
- Fortunately the vast majority of our users meet all of the above, and
- anybody who doesn't would not be affected negatively (plus very likely
- comprises a very tiny minority).
+ 1. color.man=true must be set in the config
+ 2. The user must use less
+ 3. Not have the sameLESS_TERMCAPvariables set (we call setenv(3) with overwrite=0)
+ 4. Have color.ui enabled
+ 5. Not have color.pager disabled
+ 6. Not have git with stdout directed to a file- [1] https://unix.stackexchange.com/questions/119/colors-in-man-pages/147
+ 1. https://lore.kernel.org/git/[email protected]/
+ 2. https://unix.stackexchange.com/questions/119/colors-in-man-pages/147Suggested-by Ævar Arnfjörð Bjarmason <[email protected]>- Phillip Wood <[email protected]>
- Comments-by: Jeff King <[email protected]>Signed-off-by Felipe Contreras <[email protected]>+ Signed-off-by: Ævar Arnfjörð Bjarmason <[email protected]>
##
Documentation/config/color.txt##
@@Documentation/config/color.txt: color.interactive.<slot>::
@@Documentation/config/color.txt: color.interactive.<slot>::
interactive commands.+color.man::
-+ This flag can be used to disable the automatic colorizaton of man
-+ pages when using the less pager. It's activated only when color.ui
-+ allows it, and also when color.pager is on. (trueby default).
++ This flag can be used to enable the automatic colorizaton of man
++ pages when using the less pager,falseby default. When set to
++trueit's activated only whencolor.uiallows it, and if
++color.pagerenable (which it is by default).
+
color.pager::
- A boolean to enable/disable colored output when the pager is in
- use (default is true).
+ A boolean to specify whetherautocolor modes should colorize
+ output going to the pager. Defaults to true; set this to false
+@@Documentation/config/color.txt: color.ui::
+ output not intended for machine consumption to use color, to
+trueorauto(this is the default since Git 1.8.4) if you
+ want such output to use color when written to the terminal.
+++
++When set totruecertain othercolor.*variables may still not be ++turned on unless explicitly enabled. Currently this only applies to ++color.man, see above. Such opt-in variables may be moved under the ++defaultcolor.uiumbrella in the future.##
builtin/help.c##
@@
@@builtin/help.c#ifndef
DEFAULT_HELP_FORMAT
#defineDEFAULT_HELP_FORMAT"man"
-@@builtin/help.c: static int verbose = 1;
- static unsigned int colopts;
- static enumhelp_formathelp_format=HELP_FORMAT_NONE;
- static intexclude_guides;
-+static intman_color= 1;
- static struct option builtin_help_options[] = {
-OPT_BOOL('a', "all", &show_all, N_("print all available commands")),
-OPT_HIDDEN_BOOL(0, "exclude-guides", &exclude_guides, N_("exclude guides")),
+@@builtin/help.c: enumhelp_format{
+HELP_FORMAT_WEB
+ };
+
++static intman_color;
+ static const char*html_path;
+
+ static intshow_all= 0;
@@builtin/help.c: static voidexec_man_konqueror(const char *path, const char *page)
}
}Documentation/config/color.txt | 11 +++++++++++ builtin/help.c | 32 +++++++++++++++++++++++++++++++- color.h | 1 + 3 files changed, 43 insertions(+), 1 deletion(-)Documentation/config/color.txt +0
-0
Documentation/config/color.txt color.interactive.<slot>:: · line 133
Quoted 8 lines
Documentation/config/color.txt +5
-0@@ -126,6 +126,12 @@ color.interactive.<slot>:: or `error`, for four distinct types of normal output from interactive commands. +color.man:: + This flag can be used to enable the automatic colorizaton of man + pages when using the less pager, `false` by default. When set to + `true` it's activated only when `color.ui` allows it, and if + `color.pager` enable (which it is by default).
s/and if color.pager enable/and color.pager is enabled/?
Quoted 38 lines
Documentation/config/color.txt +6
-0+ color.pager:: A boolean to specify whether `auto` color modes should colorize output going to the pager. Defaults to true; set this to false@@ -200,3 +206,8 @@ color.ui:: output not intended for machine consumption to use color, to `true` or `auto` (this is the default since Git 1.8.4) if you want such output to use color when written to the terminal. ++ +When set to `true` certain other `color.*` variables may still not be +turned on unless explicitly enabled. Currently this only applies to +`color.man`, see above. Such opt-in variables may be moved under the +default `color.ui` umbrella in the future.builtin/help.c +3
-0@@ -11,6 +11,7 @@#include "config-list.h" #include "help.h" #include "alias.h" +#include "color.h" #ifndef DEFAULT_HELP_FORMAT #define DEFAULT_HELP_FORMAT "man"@@ -34,6 +35,7 @@ enum help_format { HELP_FORMAT_WEB }; +static int man_color;static const char *html_path;static int show_all =0 ;@@ -253,10 +255,33 @@ static void exec_man_konqueror(const char *path, const char *page) } } +static void colorize_man (void )
builtin/help.c static void exec_man_konqueror(const char *path, const char *page) · line 268
Quoted 10 lines
builtin/help.c +10
-0+{ +if (!man_color || !want_color (GIT_COLOR_UNKNOWN ) || !pager_use_color) +return ; + +/* Disable groff colors */ +setenv ("GROFF_NO_SGR" ,"1" ,0 ); + +/* Bold */ +setenv ("LESS_TERMCAP_md" ,GIT_COLOR_BOLD_RED ,0 ); +setenv ("LESS_TERMCAP_me" ,GIT_COLOR_RESET ,0 );
We take care not to override the user's preference if these variables are set individually, but there is a possible corner case where the user sets a subset of these LESS_TERMCAP_* because they like the defaults for some of them but not others, in that case we wouldn't want to set any of them. Whether this is likely to be a problem in practice or not I'm not sure. Version 5 [1] of this patch took care not to override the users settings in this case.
Best Wishes
Phillip
Quoted 54 lines
builtin/help.c +18
-1+ +/* Underline */ + setenv("LESS_TERMCAP_us", GIT_COLOR_BLUE GIT_COLOR_UNDERLINE, 0); +setenv ("LESS_TERMCAP_ue" ,GIT_COLOR_RESET ,0 ); + +/* Standout */ + setenv("LESS_TERMCAP_so", GIT_COLOR_CYAN GIT_COLOR_REVERSE, 0); +setenv ("LESS_TERMCAP_se" ,GIT_COLOR_RESET ,0 ); +} +static void exec_man_man (const char *path,const char *page) {if (!path) path ="man" ; + +colorize_man ();execlp (path,"man" , page, (char *)NULL );warning_errno (_ ("failed to exec '%s'" ), path); }@@ -264,6 +289,7 @@ static void exec_man_man(const char *path, const char *page)static void exec_man_cmd (const char *cmd,const char *page) {struct strbuf shell_cmd =STRBUF_INIT ; +colorize_man ();strbuf_addf (&shell_cmd,"%s %s" , cmd, page);execl (SHELL_PATH ,SHELL_PATH ,"-c" , shell_cmd.buf, (char *)NULL );warning (_ ("failed to exec '%s'" ), cmd);@@ -371,8 +397,12 @@ static int git_help_config(const char *var, const char *value, void *cb) }if (starts_with (var,"man." ))return add_man_viewer_info (var, value); +if (!strcmp (var,"color.man" )) { + man_color =git_config_bool (var, value); +return 0 ; + } -return git_default_config (var, value, cb); +return git_color_default_config (var, value, cb); }static struct cmdnames main_cmds, other_cmds;color.h +1
-0@@ -51,6 +51,7 @@ struct strbuf;#define GIT_COLOR_FAINT "\033[2m"#define GIT_COLOR_FAINT_ITALIC "\033[2;3m"#define GIT_COLOR_REVERSE "\033[7m" +#define GIT_COLOR_UNDERLINE "\033[4m"/* A special value meaning "no color selected" */ #define GIT_COLOR_NIL "NIL"
Re: [PATCH v7] help: colorize man pages if man.color=true under less(1)
In reply to Ævar Arnfjörð BjarmasonQuoted 36 lines · Ævar Arnfjörð Bjarmason
So, in order for this change to have any effect:
1. color.man=true must be set in the config
2. The user must use less
3. Not have the sameLESS_TERMCAPvariables set (we call setenv(3) with overwrite=0)
4. Have color.ui enabled
5. Not have color.pager disabled
6. Not have git with stdout directed to a file1. https://lore.kernel.org/git/[email protected]/
2. https://unix.stackexchange.com/questions/119/colors-in-man-pages/147Suggested-by Ævar Arnfjörð Bjarmason <[email protected]>Signed-off-by Felipe Contreras <[email protected]>Signed-off-by Ævar Arnfjörð Bjarmason <[email protected]>---
Quoted 17 lines · Junio C Hamano
Quoted 7 lines · Ævar Arnfjörð Bjarmason
I've been running with this on my personal git build since May 26th. I haven't had any issues with it, and I like the new coloring.
...
I think this is a good example of a change that we're better off just merging down and then reverting if the wider audience of git users hates it, rather than trying to come to some perfect consensus here on-list.My impression was tht we already had a rough consensus here on-list that it may be good to educate users who like this "new coloring" like you do to configure their "less", so that they consistently get the "new coloring" they like whether they are doing "git help git", "man git", or even "man ls", and the approach the posted patch takes will not help (it only affects "git help git" among these).
Quoted 5 lines
Quoted 1 line
I'd rather not to take it.
Fair enough, here's a version I think you and others will find acceptable then. It allows users like me who like this to explicitly opt-in via color.man=true.
Not really.
Since the implementation of the posted patch, as I understand it, does not aim to affect both "git help -m foo" and "man git-foo" identically, I think it would be easier to understand to end-users if this were exposed as a new "mode", like "git help --web" and "git help --info" are different modes from the "git help --man", something like "git help --fancy-man" (or whatever is easy to type and explain, and also add it to the variants help.format knows about to make it easy to set the default).
One advantage of doing so is that we do not have to worry about "ah, user has LESS_BLAH environment variable so we should disable this new mode here" etc. As long as the new mode is requested either via the command line option or help.format configuration, it can completely take it over. That simplifies the necessary explanation given to the users quite a lot, no?
Quoted 10 lines
---- git-config - Get and set [...] SYNOPSIS -------- [...] 'git config' [<file-option>] [...] [...] The `--type=<type>` option instructs 'git config' to ensure [...]
Quoted 6 lines
Will have "NAME" and "SECTION" shown as BOLD RED instead of BOLD, "git config" and other '-quoted parts in BLUE UNDERLINE instead of UNDERLINE, and
--type=<type>and other `-quoted parts in RED BOLD instead of BOLD. The "Standout" setting is then used for the user's own search bar (invoked with "/") and prompt. See [2] for more examples
There are BOLD RED and READ BOLD; are they differently rendered?
Re: [PATCH v7] help: colorize man pages if man.color=true under less(1)
Quoted 11 lines · Junio C Hamano
Quoted 3 lines · Ævar Arnfjörð Bjarmason
Fair enough, here's a version I think you and others will find acceptable then. It allows users like me who like this to explicitly opt-in via color.man=true.
Not really.
Since the implementation of the posted patch, as I understand it, does not aim to affect both "git help -m foo" and "man git-foo" identically,
It cannot aim to do what is not possible.
Quoted 6 lines
I think it would be easier to understand to end-users
if this were exposed as a new "mode", like "git help --web" and "git help --info" are different modes from the "git help --man", something like "git help --fancy-man" (or whatever is easy to type and explain, and also add it to the variants help.format knows about to make it easy to set the default).
But it is not a new mode.
I presume you mean format, since man, info, and web are formats, controlled by help.format.
But no, it's not a format either, because we still want to see the same format (man).
Perhaps you meant a man viewer (controlled with man.viewer), but there's no command line option to launch help with for example emacs woman.
But still, it's not a new viewer; it's an improvement of an already existing viewer.
Quoted 3 lines
One advantage of doing so is that we do not have to worry about "ah, user has
LESS_BLAHenvironment variable so we should disable this new mode here" etc.
We don't have to worry about that with the current patch.
Quoted 3 lines
As long as the new mode is requested either via the command line option or help.format configuration, it can completely take it over.
That is already the case.
Quoted 2 lines
That simplifies the necessary explanation given to the users quite a lot, no?
No, it would still be:
1. man.viewer=fancyman must be set in the config
2. The user must use less
3. Not have the same LESS_TERMCAP variables set (we call setenv(3) with overwrite=0)
4. Have color.ui enabled
5. Not have color.pager disabled
6. Not have git with stdout directed to a file
Moreover, this explanation is for developers.
Realistically all the user needs to know is that color.man=true turns this on (man.viewer=fancyman is not better in any way).
Signature · 1 line
Felipe Contreras
Re: [PATCH v7] help: colorize man pages if man.color=true under less(1)
In reply to Junio C HamanoQuoted 53 lines · Junio C Hamano
Quoted 36 lines · Ævar Arnfjörð Bjarmason
So, in order for this change to have any effect:
1. color.man=true must be set in the config
2. The user must use less
3. Not have the sameLESS_TERMCAPvariables set (we call setenv(3) with overwrite=0)
4. Have color.ui enabled
5. Not have color.pager disabled
6. Not have git with stdout directed to a file1. https://lore.kernel.org/git/[email protected]/
2. https://unix.stackexchange.com/questions/119/colors-in-man-pages/147Suggested-by Ævar Arnfjörð Bjarmason <[email protected]>Signed-off-by Felipe Contreras <[email protected]>Signed-off-by Ævar Arnfjörð Bjarmason <[email protected]>---
Quoted 17 lines · Junio C Hamano
Quoted 7 lines · Ævar Arnfjörð Bjarmason
I've been running with this on my personal git build since May 26th. I haven't had any issues with it, and I like the new coloring.
...
I think this is a good example of a change that we're better off just merging down and then reverting if the wider audience of git users hates it, rather than trying to come to some perfect consensus here on-list.My impression was tht we already had a rough consensus here on-list that it may be good to educate users who like this "new coloring" like you do to configure their "less", so that they consistently get the "new coloring" they like whether they are doing "git help git", "man git", or even "man ls", and the approach the posted patch takes will not help (it only affects "git help git" among these).
Quoted 5 lines
Quoted 1 line
I'd rather not to take it.
Fair enough, here's a version I think you and others will find acceptable then. It allows users like me who like this to explicitly opt-in via color.man=true.
Not really.
[snip] I think it would be easier to understand to end-users if this were exposed as a new "mode", like "git help --web" and "git help --info" are different modes from the "git help --man", something like "git help --fancy-man" (or whatever is easy to type and explain, and also add it to the variants help.format knows about to make it easy to set the default).
Quoted 6 lines
One advantage of doing so is that we do not have to worry about "ah, user has
LESS_BLAHenvironment variable so we should disable this new mode here" etc. As long as the new mode is requested either via the command line option or help.format configuration, it can completely take it over. That simplifies the necessary explanation given to the users quite a lot, no?
The interaction between "git help" and "man"/"less" doesn't really have an equivalent in the rest of git as far as color output goes. Usually we emit colors via our own programs.
But no, I think it makes the most sense to consider this orthagonal to help.format=man or man.viewer=<cmd>.
We're not invoking a different man viewer or command, we're just expecting that mode to invoke the pager, and if that pager is less to have these variables tweak our color preferences.
Quoted 3 lines
[unsnip] Since the implementation of the posted patch, as I understand it, does not aim to affect both "git help -m foo" and "man git-foo" identically,
Aside from this patch I don't think it makes sense to view git's UI and interaction with the pager like that.
To probably >95% of our users the "we invoke the pager" is just a technical implementation details they're not aware of. Git just has pretty colors by default, so I don't think it's jarring that "git help xyz" and "man git-xyz" look different.
We also don't try to maintain the UI that:
git cmd >file &&
pager fileGives you the same UX as:
# Invokes pager(1) for you
git cmd
Since we set e.g. PAGER_ENV already, I believe this was brought up in past discussions. So we're already past the point of git adding its own magic custom options to feed to the pager.
So I don't see the problem with having "a bit more like PAGER_ENV" hidden behind a color.man=true config option in this case.
Quoted 10 lines
Quoted 10 lines
---- git-config - Get and set [...] SYNOPSIS -------- [...] 'git config' [<file-option>] [...] [...] The `--type=<type>` option instructs 'git config' to ensure [...]
Quoted 8 lines
Quoted 6 lines
Will have "NAME" and "SECTION" shown as BOLD RED instead of BOLD, "git config" and other '-quoted parts in BLUE UNDERLINE instead of UNDERLINE, and
--type=<type>and other `-quoted parts in RED BOLD instead of BOLD. The "Standout" setting is then used for the user's own search bar (invoked with "/") and prompt. See [2] for more examplesThere are BOLD RED and READ BOLD; are they differently rendered?
Yes, that's just an omission/mistake. It should be the "RED BOLD", i.e. "<COLOR> <ATTR>".
Re: [PATCH v7] help: colorize man pages if man.color=true under less(1)
Quoted 18 lines · Ævar Arnfjörð Bjarmason
Quoted 7 lines
[snip] I think it would be easier to understand to end-users if this were exposed as a new "mode", like "git help --web" and "git help --info" are different modes from the "git help --man", something like "git help --fancy-man" (or whatever is easy to type and explain, and also add it to the variants help.format knows about to make it easy to set the default).
Quoted 6 lines
One advantage of doing so is that we do not have to worry about "ah, user has
LESS_BLAHenvironment variable so we should disable this new mode here" etc. As long as the new mode is requested either via the command line option or help.format configuration, it can completely take it over. That simplifies the necessary explanation given to the users quite a lot, no?The interaction between "git help" and "man"/"less" doesn't really have an equivalent in the rest of git as far as color output goes. Usually we emit colors via our own programs.
Quoted 6 lines
But no, I think it makes the most sense to consider this orthagonal to help.format=man or man.viewer=<cmd>.
We're not invoking a different man viewer or command, we're just expecting that mode to invoke the pager, and if that pager is less to have these variables tweak our color preferences.
FWIW, if we are going to do this, then just having it as "color.man" makes the most sense to me. It is easily explained as "when we invoke man, set up some environment variables that may enable colors in the output".
I'm still entirely unconvinced that this should be in Git at all; pointing GIT_MAN_VIEWER or man.*.cmd at a color-man wrapper seems like it would be sufficient. But it feels like that conversation was not going anywhere productive; I mention it here only to indicate that my response above is not an endorsement of the concept.
-Peff
Re: [PATCH v7] help: colorize man pages if man.color=true under less(1)
Quoted 27 lines · Jeff King
Quoted 18 lines · Ævar Arnfjörð Bjarmason
Quoted 7 lines
[snip] I think it would be easier to understand to end-users if this were exposed as a new "mode", like "git help --web" and "git help --info" are different modes from the "git help --man", something like "git help --fancy-man" (or whatever is easy to type and explain, and also add it to the variants help.format knows about to make it easy to set the default).
Quoted 6 lines
One advantage of doing so is that we do not have to worry about "ah, user has
LESS_BLAHenvironment variable so we should disable this new mode here" etc. As long as the new mode is requested either via the command line option or help.format configuration, it can completely take it over. That simplifies the necessary explanation given to the users quite a lot, no?The interaction between "git help" and "man"/"less" doesn't really have an equivalent in the rest of git as far as color output goes. Usually we emit colors via our own programs.
Quoted 6 lines
But no, I think it makes the most sense to consider this orthagonal to help.format=man or man.viewer=<cmd>.
We're not invoking a different man viewer or command, we're just expecting that mode to invoke the pager, and if that pager is less to have these variables tweak our color preferences.
Quoted 6 lines
FWIW, if we are going to do this, then just having it as "color.man" makes the most sense to me. It is easily explained as "when we invoke man, set up some environment variables that may enable colors in the output".
I'm still entirely unconvinced that this should be in Git at all;
That's OK, you don't need to be convinced for this change to be a positive one.
Quoted 2 lines
pointing
GIT_MAN_VIEWERor man.*.cmd at a color-man wrapper seems like it would be sufficient.
What color-man wrapper?
Quoted 1 line
But it feels like that conversation was not going anywhere productive;
Feelings are not facts.
Bailing from a discussion doesn't resolve the discussion, and the question "how is a user supposed to configure this properly?" remains unanswered by you, or anyone [1].
This patch is the closest to a convenient solution anybody has come up with.
If anybody has any other proposal it would be good to hear them.
[1] https://lore.kernel.org/git/[email protected]/
Signature · 1 line
Felipe Contreras
Re: [PATCH v7] help: colorize man pages if man.color=true under less(1)
In reply to Jeff KingQuoted 5 lines · Jeff King
I'm still entirely unconvinced that this should be in Git at all; pointing
GIT_MAN_VIEWERor man.*.cmd at a color-man wrapper seems like it would be sufficient. But it feels like that conversation was not going anywhere productive; I mention it here only to indicate that my response above is not an endorsement of the concept.
I have the same reaction to the patch.
Re: [PATCH v7] help: colorize man pages if man.color=true under less(1)
Quoted 9 lines · Junio C Hamano
Quoted 5 lines · Jeff King
I'm still entirely unconvinced that this should be in Git at all; pointing
GIT_MAN_VIEWERor man.*.cmd at a color-man wrapper seems like it would be sufficient. But it feels like that conversation was not going anywhere productive; I mention it here only to indicate that my response above is not an endorsement of the concept.I have the same reaction to the patch.
Do you care to explain why you think so?
What is the alternative in your view? What configuration should users use instead?
Signature · 1 line
Felipe Contreras
RE: [PATCH v7] help: colorize man pages if man.color=true under less(1)
In reply to Ævar Arnfjörð BjarmasonQuoted 61 lines · Ævar Arnfjörð Bjarmason
From: Felipe Contreras <[email protected]>
We already colorize tools traditionally not colorized by default, like diff and grep. Let's do the same for man, but only if
color.manis explicitly set to "true".Unlike other
color.*output this colorization is not enabled bycolor.uibeing true, the user needs to explicitly set thecolor.manvariable to `true.When it was proposed to treat
color.manlike any othercolor.*variable some thought that git opting in coloring for an external program such as man(1) was a step too far[1], even if the user invoked it via the "git help <topic>" wrapper.So let's make this explicitly opt-in for now. As noted in the documentation we're leaving ourselves an out to turn this on by default in the future, or e.g. putting it under the feature.experimental umbrella. We probably won't, but let's not promise users that
color.manwill forever be a special-case.As for what this actually does the effect of having this enabled is that a documentation blurb like (some parts elided with "[...]"):
NAME ---- git-config - Get and set [...] SYNOPSIS -------- [...] 'git config' [<file-option>] [...] [...] The `--type=<type>` option instructs 'git config' to ensure [...]Will have "NAME" and "SECTION" shown as BOLD RED instead of BOLD, "git config" and other '-quoted parts in BLUE UNDERLINE instead of UNDERLINE, and
--type=<type>and other `-quoted parts in RED BOLD instead of BOLD. The "Standout" setting is then used for the user's own search bar (invoked with "/") and prompt. See [2] for more examplesNormally
check_auto_color()would check the value ofcolor.pager, but in this particular case it's not git the one executing the pager, but man. Therefore we need to checkpager_use_colorourselves.We do not need to support
color.manbeing set toalways; Thegit helpcommand is always run for a tty (it would be very strange for a user to dogit help $page > output, but in fact, that works anyway, we don't even need to check if stdout is a tty, but just to be consistent we do). So it's simply a boolean in our case.So, in order for this change to have any effect:
1. color.man=true must be set in the config
2. The user must use less
3. Not have the sameLESS_TERMCAPvariables set (we call setenv(3) with overwrite=0)
4. Have color.ui enabled
5. Not have color.pager disabled
6. Not have git with stdout directed to a file
Quoted 6 lines
1. https://lore.kernel.org/git/[email protected]/
2. https://unix.stackexchange.com/questions/119/colors-in-man-pages/147Suggested-by Ævar Arnfjörð Bjarmason <[email protected]>Signed-off-by Felipe Contreras <[email protected]>Signed-off-by Ævar Arnfjörð Bjarmason <[email protected]>
Looks good to me.
Signature · 1 line
Felipe Contreras
Re: [PATCH v7] help: colorize man pages if man.color=true under less(1)
In reply to Ævar Arnfjörð BjarmasonDocumentation/config/color.txt color.interactive.<slot>:: · line 133
Quoted 13 lines · Ævar Arnfjörð Bjarmason
Documentation/config/color.txt +5
-0@@ -126,6 +126,12 @@ color.interactive.<slot>:: or `error`, for four distinct types of normal output from interactive commands. +color.man:: + This flag can be used to enable the automatic colorizaton of man + pages when using the less pager, `false` by default. When set to + `true` it's activated only when `color.ui` allows it, and if + `color.pager` enable (which it is by default).
A few typos here:
Documentation/config/color.txt +2 -2
@@ -127,10 +127,10 @@ color.interactive.<slot>:: interactive commands. color.man:: - This flag can be used to enable the automatic colorizaton of man + This flag can be used to enable the automatic colorization of man pages when using the less pager, `false` by default. When set to `true` it's activated only when `color.ui` allows it, and if - `color.pager` enable (which it is by default). + `color.pager` is enabled (which it is by default). color.pager:: A boolean to specify whether `auto` color modes should colorize
The interaction with color.ui seems unusual. Normally it is not a gate-keeper for specific colorizations, but rather a fallback when more-specific color config is unspecified. E.g.:
[color]
ui = false
branch = true
would colorize branch output, but nothing else. But from your description (and I think the code matches this), doing:
[color]
ui = false
man = true
would still disable the man-colors. So there's no way to enable this feature without enabling colors everywhere else. I think it should simply be independent of color.ui (with the exception that it may eventually use it as a fallback like all the other color.* booleans, _if_ we want to move it to default-to-on).
-Peff
Re: [PATCH v7] help: colorize man pages if man.color=true under less(1)
Quoted 7 lines · Jeff King
.... But from your
description (and I think the code matches this), doing:[color]
ui = false
man = true
Quoted 5 lines
would still disable the man-colors. So there's no way to enable this feature without enabling colors everywhere else. I think it should simply be independent of color.ui (with the exception that it may eventually use it as a fallback like all the other color.* booleans, _if_ we want to move it to default-to-on).
That matches my perception. Thanks.
Re: [PATCH v7] help: colorize man pages if man.color=true under less(1)
Quoted 9 lines · Junio C Hamano
Quoted 7 lines · Jeff King
.... But from your
description (and I think the code matches this), doing:[color]
ui = false
man = true
Quoted 7 lines
Quoted 5 lines
would still disable the man-colors. So there's no way to enable this feature without enabling colors everywhere else. I think it should simply be independent of color.ui (with the exception that it may eventually use it as a fallback like all the other color.* booleans, _if_ we want to move it to default-to-on).
That matches my perception. Thanks.
This is already integrated into v8.
https://lore.kernel.org/git/[email protected]/
Signature · 1 line
Felipe Contreras
builtin/help.c static void exec_man_man(const char *path, const char *page) · line 292
Quoted 8 lines
builtin/help.c +1
-0@@ -264,6 +289,7 @@ static void exec_man_man(const char *path, const char *page)static void exec_man_cmd (const char *cmd,const char *page) {struct strbuf shell_cmd =STRBUF_INIT ; +colorize_man ();
On further reflection I don't think this colorize belongs here. exec_man_cmd() is meant to execute any custom command, not necessarily man.
Signature · 1 line
Felipe Contreras
PATCH v8 1/1 help: add option to colorize man pages under less
In reply to Felipe ContrerasWe already colorize tools traditionally not colorized by default--like diff and grep. Let's do the same for man, but only if color.man is explicitly set to "true".
Unlike other color.* output, this colorization is not enabled when color.ui is true; the user needs to explicitly set the color.man variable to `true.
When it was proposed to treat color.man like any other color.* variable, some thought that git opting to add color for an external program such as man(1) was a step too far [1]--even if the user invoked it via the "git help <topic>" wrapper. So let's make this explicitly opt-in for now.
As noted in the documentation we're leaving ourselves an out to turn this on by default in the future, for example putting it under the feature.experimental umbrella. We probably won't, but let's not promise users that color.man will forever be a special-case.
As for what this actually does, the effect of having this enabled is that a documentation blurb like (some parts elided with "[...]"):
NAME ---- git-config - Get and set [...] SYNOPSIS -------- [...] 'git config' [<file-option>] [...] [...] The `--type=<type>` option instructs 'git config' to ensure [...]
Will have "NAME" and "SYNOPSIS" shown as RED BOLD instead of BOLD, "git config" and other '-quoted parts in BLUE UNDERLINE instead of UNDERLINE, and --type=<type> and other `-quoted parts in RED BOLD instead of BOLD. The "standout" setting is then used for the user's own search bar (invoked with "/") and prompt. See [2] for more examples
Normally check_auto_color() would check the value of color.pager, but in this particular case it's not git the one executing the pager, but man. Therefore we need to check pager_use_color ourselves.
We do not need to support color.man being set to always; the git help command is always run for a tty (it would be very strange for a user to do git help $page > output, but in fact, that works anyway, we don't even need to check if stdout is a tty, but just to be consistent we do). So it's simply a boolean in our case.
So, in order for this change to have any effect:
1. color.man=true must be set in the config
2. The user must use less
3. Not have the same LESS_TERMCAP variables set (we call setenv(3) with overwrite=0)
4. Not have color.pager disabled
5. Not have git with stdout directed to a file
1. https://lore.kernel.org/git/[email protected]/
2. https://unix.stackexchange.com/questions/119/colors-in-man-pages/147
---
This a reroll of Ævar's v7 with comments from Jeff King so that color.ui=never doesn't disable color.man, and the documentation was updated accordingly.
Additinally I removed one call to colorize_man() in exec_man_cmd() which is not meant for the man command (although it could be used for that).
Plus a bunch of style changes to the commit message.
Range-diff against v7:
1: 167f5c8b39 ! 1: 1b3f7ee1aa help: colorize man pages if man.color=true under less(1)
@@ Metadata
Author: Felipe Contreras <[email protected]>
## Commit message ##
- help: colorize man pages if man.color=true under less(1)
+ help: add option to colorize man pages under less
- We already colorize tools traditionally not colorized by default, like
+ We already colorize tools traditionally not colorized by default--like
diff and grep. Let's do the same for man, but only if color.man is explicitly set to "true".
- Unlike other color.* output this colorization is not enabled by
- color.ui being true, the user needs to explicitly set the
+ Unlike other color.* output, this colorization is not enabled when
+ color.ui is true; the user needs to explicitly set the
color.man variable to `true.
When it was proposed to treat color.man like any other color.*
- variable some thought that git opting in coloring for an external
- program such as man(1) was a step too far[1], even if the user invoked
- it via the "git help <topic>" wrapper.
+ variable, some thought that git opting to add color for an external
+ program such as man(1) was a step too far [1]--even if the user invoked
+ it via the "git help <topic>" wrapper. So let's make this explicitly
+ opt-in for now.
- So let's make this explicitly opt-in for now. As noted in the
- documentation we're leaving ourselves an out to turn this on by
- default in the future, or e.g. putting it under the
- feature.experimental umbrella. We probably won't, but let's not
- promise users that color.man will forever be a special-case.
+ As noted in the documentation we're leaving ourselves an out to turn
+ this on by default in the future, for example putting it under the
+ feature.experimental umbrella. We probably won't, but let's not promise
+ users that color.man will forever be a special-case.
- As for what this actually does the effect of having this enabled is
+ As for what this actually does, the effect of having this enabled is
that a documentation blurb like (some parts elided with "[...]"):
NAME
@@ Commit message
[...]
The --type=<type> option instructs 'git config' to ensure [...]
- Will have "NAME" and "SECTION" shown as BOLD RED instead of BOLD, "git
- config" and other '-quoted parts in BLUE UNDERLINE instead of
+ Will have "NAME" and "SYNOPSIS" shown as RED BOLD instead of BOLD,
+ "git config" and other '-quoted parts in BLUE UNDERLINE instead of
UNDERLINE, and --type=<type> and other `-quoted parts in RED BOLD
- instead of BOLD. The "Standout" setting is then used for the user's
+ instead of BOLD. The "standout" setting is then used for the user's
own search bar (invoked with "/") and prompt. See [2] for more examples
@@ Commit message
in this particular case it's not git the one executing the pager, but man. Therefore we need to check pager_use_color ourselves.
- We do not need to support color.man being set to always; The `git
+ We do not need to support color.man being set to always; the `git
help command is always run for a tty (it would be very strange for a user to do git help $page > output`, but in fact, that works anyway, we don't even need to check if stdout is a tty, but just to be
@@ Commit message
1. color.man=true must be set in the config
2. The user must use less
3. Not have the same LESS_TERMCAP variables set (we call setenv(3) with overwrite=0)
- 4. Have color.ui enabled
- 5. Not have color.pager disabled
- 6. Not have git with stdout directed to a file
+ 4. Not have color.pager disabled
+ 5. Not have git with stdout directed to a file
1. https://lore.kernel.org/git/[email protected]/
2. https://unix.stackexchange.com/questions/119/colors-in-man-pages/147
- Signed-off-by: Felipe Contreras <[email protected]>
+ Signed-off-by: Felipe Contreras <[email protected]>
## Documentation/config/color.txt ##
@@ Documentation/config/color.txt: color.interactive.<slot>::
@@ Documentation/config/color.txt: color.interactive.<slot>::
interactive commands.
+color.man::
-+ This flag can be used to enable the automatic colorizaton of man
++ This flag can be used to enable the automatic colorization of man
+ pages when using the less pager, false by default. When set to
-+ true it's activated only when color.ui allows it, and if
-+ color.pager enable (which it is by default).
++ true it's activated only if color.pager is enabled (which it
++ is by default).
+
color.pager::
A boolean to specify whether auto color modes should colorize
@@ builtin/help.c: static void exec_man_konqueror(const char *path, const char *pag
+static void colorize_man(void)
+{
-+ if (!man_color || !want_color(GIT_COLOR_UNKNOWN) || !pager_use_color)
++ if (!man_color || !pager_use_color)
+ return;
+
+ /* Disable groff colors */
@@ builtin/help.c: static void exec_man_konqueror(const char *path, const char *pag
execlp(path, "man", page, (char *)NULL);
warning_errno(_("failed to exec '%s'"), path);
}
-@@ builtin/help.c: static void exec_man_man(const char *path, const char *page)
- static void exec_man_cmd(const char *cmd, const char *page)
- {
- struct strbuf shell_cmd = STRBUF_INIT;
-+ colorize_man();
- strbuf_addf(&shell_cmd, "%s %s", cmd, page);
- execl(SHELL_PATH, SHELL_PATH, "-c", shell_cmd.buf, (char *)NULL);
- warning(_("failed to exec '%s'"), cmd);
@@ builtin/help.c: static int git_help_config(const char *var, const char *value, void *cb)
}
if (starts_with(var, "man."))
Documentation/config/color.txt | 11 +++++++++++ builtin/help.c | 31 ++++++++++++++++++++++++++++++- color.h | 1 + 3 files changed, 42 insertions(+), 1 deletion(-)
Documentation/config/color.txt +11 -0
@@ -126,6 +126,12 @@ color.interactive.<slot>:: or `error`, for four distinct types of normal output from interactive commands. +color.man:: + This flag can be used to enable the automatic colorization of man + pages when using the less pager, `false` by default. When set to + `true` it's activated only if `color.pager` is enabled (which it + is by default). + color.pager:: A boolean to specify whether `auto` color modes should colorize output going to the pager. Defaults to true; set this to false
@@ -200,3 +206,8 @@ color.ui:: output not intended for machine consumption to use color, to `true` or `auto` (this is the default since Git 1.8.4) if you want such output to use color when written to the terminal. ++ +When set to `true` certain other `color.*` variables may still not be +turned on unless explicitly enabled. Currently this only applies to +`color.man`, see above. Such opt-in variables may be moved under the +default `color.ui` umbrella in the future.
builtin/help.c +30 -1
@@ -11,6 +11,7 @@#include "config-list.h" #include "help.h" #include "alias.h" +#include "color.h" #ifndef DEFAULT_HELP_FORMAT #define DEFAULT_HELP_FORMAT "man"
@@ -34,6 +35,7 @@ enum help_format { HELP_FORMAT_WEB }; +static int man_color;static const char *html_path;static int show_all =0 ;
@@ -253,10 +255,33 @@ static void exec_man_konqueror(const char *path, const char *page) } } +static void colorize_man (void ) +{ +if (!man_color || !pager_use_color) +return ; + +/* Disable groff colors */ +setenv ("GROFF_NO_SGR" ,"1" ,0 ); + +/* Bold */ +setenv ("LESS_TERMCAP_md" ,GIT_COLOR_BOLD_RED ,0 ); +setenv ("LESS_TERMCAP_me" ,GIT_COLOR_RESET ,0 ); + +/* Underline */ + setenv("LESS_TERMCAP_us", GIT_COLOR_BLUE GIT_COLOR_UNDERLINE, 0); +setenv ("LESS_TERMCAP_ue" ,GIT_COLOR_RESET ,0 ); + +/* Standout */ + setenv("LESS_TERMCAP_so", GIT_COLOR_CYAN GIT_COLOR_REVERSE, 0); +setenv ("LESS_TERMCAP_se" ,GIT_COLOR_RESET ,0 ); +} +static void exec_man_man (const char *path,const char *page) {if (!path) path ="man" ; + +colorize_man ();execlp (path,"man" , page, (char *)NULL );warning_errno (_ ("failed to exec '%s'" ), path); }
@@ -371,8 +396,12 @@ static int git_help_config(const char *var, const char *value, void *cb) }if (starts_with (var,"man." ))return add_man_viewer_info (var, value); +if (!strcmp (var,"color.man" )) { + man_color =git_config_bool (var, value); +return 0 ; + } -return git_default_config (var, value, cb); +return git_color_default_config (var, value, cb); }static struct cmdnames main_cmds, other_cmds;
color.h +1 -0
@@ -51,6 +51,7 @@ struct strbuf;#define GIT_COLOR_FAINT "\033[2m"#define GIT_COLOR_FAINT_ITALIC "\033[2;3m"#define GIT_COLOR_REVERSE "\033[7m" +#define GIT_COLOR_UNDERLINE "\033[4m"/* A special value meaning "no color selected" */ #define GIT_COLOR_NIL "NIL"
Signature · 1 line
2.32.0
Re: [PATCH v8] help: add option to colorize man pages under less
Quoted 8 lines · Felipe Contreras
This a reroll of Ævar's v7 with comments from Jeff King so that color.ui=never doesn't disable color.man, and the documentation was updated accordingly.
Additinally I removed one call to
colorize_man()inexec_man_cmd()which is not meant for the man command (although it could be used for that).Plus a bunch of style changes to the commit message.
This version looks good to me, thanks for the style & grammar fixes on my commit message additions.
Quoted 8 lines
1. color.man=true must be set in the config
2. The user must use less
3. Not have the sameLESS_TERMCAPvariables set (we call setenv(3) with overwrite=0)
- 4. Have color.ui enabled
- 5. Not have color.pager disabled
- 6. Not have git with stdout directed to a file
+ 4. Not have color.pager disabled
+ 5. Not have git with stdout directed to a file
Even better.
color.h struct strbuf; · line 57
Quoted 13 lines
static struct cmdnames
main_cmds,other_cmds;color.h +1
-0@@ -51,6 +51,7 @@ struct strbuf;#define GIT_COLOR_FAINT "\033[2m"#define GIT_COLOR_FAINT_ITALIC "\033[2;3m"#define GIT_COLOR_REVERSE "\033[7m" +#define GIT_COLOR_UNDERLINE "\033[4m"/* A special value meaning "no color selected" */ #define GIT_COLOR_NIL "NIL"
Not really needing, but I note that this adds something that we don't have in test_decode_color(), not that we're testing this output directly, so it doesn't matter for now.