From adb3356664fbf15646fd90eb1d5ddd9e66ce913f Mon Sep 17 00:00:00 2001 From: Jeff King Date: Thu, 23 Jun 2016 13:32:30 -0400 Subject: doc: refactor description of color format This is a general cleanup of the description of colors in git-config, mostly to address inaccuracies and confusion that had grown over time: - you can have many attributes, not just one - the discussion flip-flopped between colors and attributes; now we discuss everything about colors, then everything about attributes - many concepts were lumped into the first paragraph, making it hard to read, and especially to find the actual lists of colors and attributes. I stopped short of breaking those out into their own lists, as it seemed like an excessive use of vertical screen real estate. - we introduced negated attributes, but then the next paragraph basically explains how each item starts off with no attributes. So why would one need negated attributes? We now explain. - minor typo, language, and typography fixes Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/config.txt | 47 ++++++++++++++++++++++++++--------------------- 1 file changed, 26 insertions(+), 21 deletions(-) (limited to 'Documentation') diff --git a/Documentation/config.txt b/Documentation/config.txt index 2e919f0df8..836f731873 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -147,27 +147,32 @@ integer:: 1024", "by 1024x1024", etc. color:: - The value for a variables that takes a color is a list of - colors (at most two) and attributes (at most one), separated - by spaces. The colors accepted are `normal`, `black`, - `red`, `green`, `yellow`, `blue`, `magenta`, `cyan` and - `white`; the attributes are `bold`, `dim`, `ul`, `blink` and - `reverse`. The first color given is the foreground; the - second is the background. The position of the attribute, if - any, doesn't matter. Attributes may be turned off specifically - by prefixing them with `no` (e.g., `noreverse`, `noul`, etc). -+ -Colors (foreground and background) may also be given as numbers between -0 and 255; these use ANSI 256-color mode (but note that not all -terminals may support this). If your terminal supports it, you may also -specify 24-bit RGB values as hex, like `#ff0ab3`. -+ -The attributes are meant to be reset at the beginning of each item -in the colored output, so setting color.decorate.branch to `black` -will paint that branch name in a plain `black`, even if the previous -thing on the same output line (e.g. opening parenthesis before the -list of branch names in `log --decorate` output) is set to be -painted with `bold` or some other attribute. + The value for a variable that takes a color is a list of + colors (at most two, one for foreground and one for background) + and attributes (as many as you want), separated by spaces. ++ +The basic colors accepted are `normal`, `black`, `red`, `green`, `yellow`, +`blue`, `magenta`, `cyan` and `white`. The first color given is the +foreground; the second is the background. ++ +Colors may also be given as numbers between 0 and 255; these use ANSI +256-color mode (but note that not all terminals may support this). If +your terminal supports it, you may also specify 24-bit RGB values as +hex, like `#ff0ab3`. ++ +The accepted attributes are `bold`, `dim`, `ul`, `blink`, and `reverse`. +The position of any attributes with respect to the colors (before, after, +or in between), doesn't matter. Specific attributes may be turned off +by prefixing them with `no` (e.g., `noreverse`, `noul`, etc). ++ +For git's pre-defined color slots, the attributes are meant to be reset +at the beginning of each item in the colored output. So setting +`color.decorate.branch` to `black` will paint that branch name in a +plain `black`, even if the previous thing on the same output line (e.g. +opening parenthesis before the list of branch names in `log --decorate` +output) is set to be painted with `bold` or some other attribute. +However, custom log formats may do more complicated and layered +coloring, and the negated forms may be useful there. Variables -- cgit v1.2.3 From 5621068f3d3c537b79b76201928c0b06025479ee Mon Sep 17 00:00:00 2001 From: Jeff King Date: Thu, 23 Jun 2016 13:38:44 -0400 Subject: color: allow "no-" for negating attributes Using "no-bold" rather than "nobold" is easier to read and more natural to type (to me, anyway, even though I was the person who introduced "nobold" in the first place). It's easy to allow both. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/config.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation') diff --git a/Documentation/config.txt b/Documentation/config.txt index 836f731873..93ecd728ab 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -163,7 +163,7 @@ hex, like `#ff0ab3`. The accepted attributes are `bold`, `dim`, `ul`, `blink`, and `reverse`. The position of any attributes with respect to the colors (before, after, or in between), doesn't matter. Specific attributes may be turned off -by prefixing them with `no` (e.g., `noreverse`, `noul`, etc). +by prefixing them with `no` or `no-` (e.g., `noreverse`, `no-ul`, etc). + For git's pre-defined color slots, the attributes are meant to be reset at the beginning of each item in the colored output. So setting -- cgit v1.2.3 From 54590a0eda10ecfdc39398d662ab3f663491067e Mon Sep 17 00:00:00 2001 From: Jeff King Date: Thu, 23 Jun 2016 13:39:07 -0400 Subject: color: support "italic" attribute We already support bold, underline, and similar attributes. Let's add italic to the mix. According to the Wikipedia page on ANSI colors, this attribute is "not widely supported", but it does seem to work on my xterm. We don't have to bump the maximum color size because we were already over-allocating it (but we do adjust the comment appropriately). Requested-by: Simon Courtois Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/config.txt | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/config.txt b/Documentation/config.txt index 93ecd728ab..cea3835c8f 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -160,10 +160,11 @@ Colors may also be given as numbers between 0 and 255; these use ANSI your terminal supports it, you may also specify 24-bit RGB values as hex, like `#ff0ab3`. + -The accepted attributes are `bold`, `dim`, `ul`, `blink`, and `reverse`. -The position of any attributes with respect to the colors (before, after, -or in between), doesn't matter. Specific attributes may be turned off -by prefixing them with `no` or `no-` (e.g., `noreverse`, `no-ul`, etc). +The accepted attributes are `bold`, `dim`, `ul`, `blink`, `reverse`, and +`italic`. The position of any attributes with respect to the colors +(before, after, or in between), doesn't matter. Specific attributes may +be turned off by prefixing them with `no` or `no-` (e.g., `noreverse`, +`no-ul`, etc). + For git's pre-defined color slots, the attributes are meant to be reset at the beginning of each item in the colored output. So setting -- cgit v1.2.3 From 9dc3515cf005639317fb95492b3157aadf056923 Mon Sep 17 00:00:00 2001 From: Jeff King Date: Thu, 23 Jun 2016 13:40:16 -0400 Subject: color: support strike-through attribute This is the only remaining attribute that is commonly supported (at least by xterm) that we don't support. Let's add it for completeness. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano --- Documentation/config.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'Documentation') diff --git a/Documentation/config.txt b/Documentation/config.txt index cea3835c8f..6882e7065a 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -160,8 +160,9 @@ Colors may also be given as numbers between 0 and 255; these use ANSI your terminal supports it, you may also specify 24-bit RGB values as hex, like `#ff0ab3`. + -The accepted attributes are `bold`, `dim`, `ul`, `blink`, `reverse`, and -`italic`. The position of any attributes with respect to the colors +The accepted attributes are `bold`, `dim`, `ul`, `blink`, `reverse`, +`italic`, and `strike` (for crossed-out or "strikethrough" letters). +The position of any attributes with respect to the colors (before, after, or in between), doesn't matter. Specific attributes may be turned off by prefixing them with `no` or `no-` (e.g., `noreverse`, `no-ul`, etc). -- cgit v1.2.3