From 05c3e5c7719a4b25237d00a696877bdd47488678 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Tue, 3 Mar 2015 20:03:50 -0800 Subject: [PATCH 1/7] Documentation/config.txt: avoid unnecessary negation Section names and variable names are both case-insensitive, but one is described as "not case sensitive". Use "case-insensitive" for both. Instead of saying "... have to be escaped" without telling what that escaping achieves, state it in a more positive way, i.e. "... can be included by escaping". Signed-off-by: Junio C Hamano --- Documentation/config.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index 097fdd47e1..dbe7035533 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -25,7 +25,7 @@ blank lines are ignored. The file consists of sections and variables. A section begins with the name of the section in square brackets and continues until the next -section begins. Section names are not case sensitive. Only alphanumeric +section begins. Section names are case-insensitive. Only alphanumeric characters, `-` and `.` are allowed in section names. Each variable must belong to some section, which means that there must be a section header before the first setting of a variable. @@ -40,8 +40,8 @@ in the section header, like in the example below: -------- Subsection names are case sensitive and can contain any characters except -newline (doublequote `"` and backslash have to be escaped as `\"` and `\\`, -respectively). Section headers cannot span multiple +newline (doublequote `"` and backslash can be included by escaping them +as `\"` and `\\`, respectively). Section headers cannot span multiple lines. Variables may belong directly to a section or to a given subsection. You can have `[section]` if you have `[section "subsection"]`, but you don't need to. From a5285b6c231b55e71007d89a4a29b151302abe09 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 4 Mar 2015 10:26:17 -0800 Subject: [PATCH 2/7] Documentation/config.txt: explain multi-valued variables once The syntax section repeats what the preamble explained already. That a variable can have multiple values is more about what a variable is than the syntax of the file. Signed-off-by: Junio C Hamano --- Documentation/config.txt | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index dbe7035533..405bf250cd 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -14,7 +14,8 @@ the fully qualified variable name of the variable itself is the last dot-separated segment and the section name is everything before the last dot. The variable names are case-insensitive, allow only alphanumeric characters and `-`, and must start with an alphabetic character. Some -variables may appear multiple times. +variables may appear multiple times; we say then that the variable is +multivalued. Syntax ~~~~~~ @@ -56,9 +57,7 @@ header) are recognized as setting variables, in the form 'name = value'. If there is no equal sign on the line, the entire line is taken as 'name' and the variable is recognized as boolean "true". The variable names are case-insensitive, allow only alphanumeric characters -and `-`, and must start with an alphabetic character. There can be more -than one value for a given variable; we say then that the variable is -multivalued. +and `-`, and must start with an alphabetic character. Leading and trailing whitespace in a variable value is discarded. Internal whitespace within a variable value is retained verbatim. From ff5507ed2a34f0eb8c8d4f0bd300d2b786031aff Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 4 Mar 2015 10:33:38 -0800 Subject: [PATCH 3/7] Documentation/config.txt: describe the structure first and then meaning A line can be continued via a backquote-LF and can be chomped at a comment character. But that is not specific to string-typed values. It is common to all, just like unquoted leading and trailing whitespaces are stripped and inter-word spacing are retained. Move the description around and desribe these structural rules first, then introduce the double-quote facility as a way to override them, and finally mention various types of values. Note that these structural rules only apply to the value part of the configuration file. E.g. [aSection] \ name \ = value does not work, because the rules kick in only after seeing "name =". Both the original and the updated text are phrased in an awkward way by singling out the "value" part of the line because of this. Signed-off-by: Junio C Hamano --- Documentation/config.txt | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index 405bf250cd..1444614587 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -59,32 +59,31 @@ is taken as 'name' and the variable is recognized as boolean "true". The variable names are case-insensitive, allow only alphanumeric characters and `-`, and must start with an alphabetic character. -Leading and trailing whitespace in a variable value is discarded. -Internal whitespace within a variable value is retained verbatim. +A line that defines a value can be continued to the next line by +ending it with a `\`; the backquote and the end-of-line are +stripped. Leading whitespaces after 'name =', the remainder of the +line after the first comment character '#' or ';', and trailing +whitespaces of the line are discarded unless they are enclosed in +double quotes. Internal whitespaces within the value are retained +verbatim. -The values following the equals sign in variable assign are all either -a string, an integer, or a boolean. Boolean values may be given as yes/no, -1/0, true/false or on/off. Case is not significant in boolean values, when -converting value to the canonical form using '--bool' type specifier; -'git config' will ensure that the output is "true" or "false". - -String values may be entirely or partially enclosed in double quotes. -You need to enclose variable values in double quotes if you want to -preserve leading or trailing whitespace, or if the variable value contains -comment characters (i.e. it contains '#' or ';'). -Double quote `"` and backslash `\` characters in variable values must -be escaped: use `\"` for `"` and `\\` for `\`. +Inside double quotes, double quote `"` and backslash `\` characters +must be escaped: use `\"` for `"` and `\\` for `\`. The following escape sequences (beside `\"` and `\\`) are recognized: `\n` for newline character (NL), `\t` for horizontal tabulation (HT, TAB) and `\b` for backspace (BS). No other char escape sequence, nor octal char sequences are valid. -Variable values ending in a `\` are continued on the next line in the -customary UNIX fashion. +The values following the equals sign in variable assign are all either +a string, an integer, or a boolean. Boolean values may be given as yes/no, +1/0, true/false or on/off. Case is not significant in boolean values, when +converting value to the canonical form using '--bool' type specifier; +'git config' will ensure that the output is "true" or "false". Some variables may require a special value format. + Includes ~~~~~~~~ From 5f7b91baca0693e80fa9230a2008107aa4779743 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 4 Mar 2015 10:57:43 -0800 Subject: [PATCH 4/7] Documentation/config.txt: have a separate "Values" section The various types of values set to the configuration variables deserve more than a brief footnote mention in the syntax section, and it will be more so after the later steps of this clean up effort. Move the mention of booleans from the syntax section to this new section, and describe how human-readble integers can be spelled with scaling there. Signed-off-by: Junio C Hamano --- Documentation/config.txt | 39 +++++++++++++++++++++++++++++++-------- 1 file changed, 31 insertions(+), 8 deletions(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index 1444614587..7be608b658 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -75,14 +75,6 @@ The following escape sequences (beside `\"` and `\\`) are recognized: and `\b` for backspace (BS). No other char escape sequence, nor octal char sequences are valid. -The values following the equals sign in variable assign are all either -a string, an integer, or a boolean. Boolean values may be given as yes/no, -1/0, true/false or on/off. Case is not significant in boolean values, when -converting value to the canonical form using '--bool' type specifier; -'git config' will ensure that the output is "true" or "false". - -Some variables may require a special value format. - Includes ~~~~~~~~ @@ -124,6 +116,37 @@ Example path = foo ; expand "foo" relative to the current file path = ~/foo ; expand "foo" in your $HOME directory + +Values +~~~~~~ + +Values of many variables are treated as a simple string, but there +are variables that take values of specific types and there are rules +as to how to spell them. + +boolean:: + + When a variable is said to take a boolean value, many + synonyms are accepted for 'true' and 'false'; these are all + case-insensitive. + + true;; Boolean true can be spelled as `yes`, `on`, `true`, + or `1`. Also, a variable defined without `= ` + is taken as true. + + false;; Boolean false can be spelled as `no`, `off`, + `false`, or `0`. ++ +When converting value to the canonical form using '--bool' type +specifier; 'git config' will ensure that the output is "true" or +"false" (spelled in lowercase). + +integer:: + The value for many variables that specify various sizes can + be suffixed with `k`, `M`,... to mean "scale the number by + 1024", "by 1024x1024", etc. + + Variables ~~~~~~~~~ From b92c1a28f832ede499a4f7e167d46cd5b2192fe4 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Tue, 3 Mar 2015 23:07:13 -0800 Subject: [PATCH 5/7] Documentation/config.txt: describe 'color' value type in the "Values" section Instead of describing it for color.branch. and have everybody else refer to it, explain how colors are spelled in "Values" section upfront. Signed-off-by: Junio C Hamano --- Documentation/config.txt | 29 +++++++++++++---------------- 1 file changed, 13 insertions(+), 16 deletions(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index 7be608b658..c40bf4a7ff 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -146,6 +146,16 @@ integer:: be suffixed with `k`, `M`,... to mean "scale the number by 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. + Variables ~~~~~~~~~ @@ -838,14 +848,6 @@ color.branch.:: `remote` (a remote-tracking branch in refs/remotes/), `upstream` (upstream tracking branch), `plain` (other refs). -+ -The value for these configuration variables 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. color.diff:: Whether to use ANSI escape sequences to add color to patches. @@ -865,8 +867,7 @@ color.diff.:: of `plain` (context text), `meta` (metainformation), `frag` (hunk header), 'func' (function in hunk header), `old` (removed lines), `new` (added lines), `commit` (commit headers), or `whitespace` - (highlighting whitespace errors). The values of these variables may be - specified as in color.branch.. + (highlighting whitespace errors). color.decorate.:: Use customized color for 'git log --decorate' output. `` is one @@ -899,8 +900,6 @@ color.grep.:: separators between fields on a line (`:`, `-`, and `=`) and between hunks (`--`) -- -+ -The values of these variables may be specified as in color.branch.. color.interactive:: When set to `always`, always use colors for interactive prompts @@ -913,8 +912,7 @@ color.interactive.:: Use customized color for 'git add --interactive' and 'git clean --interactive' output. `` may be `prompt`, `header`, `help` or `error`, for four distinct types of normal output from - interactive commands. The values of these variables may be - specified as in color.branch.. + interactive commands. color.pager:: A boolean to enable/disable colored output when the pager is in @@ -940,8 +938,7 @@ color.status.:: `untracked` (files which are not tracked by Git), `branch` (the current branch), or `nobranch` (the color the 'no branch' warning is shown in, defaulting - to red). The values of these variables may be specified as in - color.branch.. + to red). color.ui:: This variable determines the default value for variables such From 1c448b3b5c283d793d994808d0ec1174b9b4dc26 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 4 Mar 2015 11:08:34 -0800 Subject: [PATCH 6/7] Documentation/config.txt: simplify boolean description in the syntax section The 'true' short-hand doesn't deserve a separate sentence; even our own git config --bool foo.bar yes would not produce it. Signed-off-by: Junio C Hamano --- Documentation/config.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index c40bf4a7ff..f1cf571fcd 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -54,8 +54,8 @@ restrictions as section names. All the other lines (and the remainder of the line after the section header) are recognized as setting variables, in the form -'name = value'. If there is no equal sign on the line, the entire line -is taken as 'name' and the variable is recognized as boolean "true". +'name = value' (or just 'name', which is a short-hand to say that +the variable is the boolean "true"). The variable names are case-insensitive, allow only alphanumeric characters and `-`, and must start with an alphabetic character. From 5ee875852e3cb41c21c2e89a636fc1e40c4012b1 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 4 Mar 2015 11:07:12 -0800 Subject: [PATCH 7/7] log --decorate: do not leak "commit" color into the next item In "git log --decorate", you would see the commit header like this: commit ... (HEAD, jc/decorate-leaky-separator-color) where "commit ... (" is painted in color.diff.commit, "HEAD" in color.decorate.head, ", " in color.diff.commit, the branch name in color.decorate.branch and then closing ")" in color.diff.commit. If you wanted to paint the HEAD and local branch name in the same color as the body text (perhaps because cyan and green are too faint on a black-on-white terminal to be readable), you would not want to have to say [color "decorate"] head = black branch = black because that you would not be able to reuse same configuration on a white-on-black terminal. You would naively expect [color "decorate"] head = normal branch = normal to work, but unfortunately it does not. It paints the string "HEAD" and the branch name in the same color as the opening parenthesis or comma between the decoration elements. This is because the code forgets to reset the color after printing the "prefix" in its own color. It theoretically is possible that some people were expecting and relying on that the attribute set as the "diff.commit" color, which is used to draw these opening parenthesis and inter-item comma, is inherited by the drawing of branch names, but it is not how the coloring works everywhere else. Signed-off-by: Junio C Hamano --- Documentation/config.txt | 7 +++++++ log-tree.c | 1 + t/t4207-log-decoration-colors.sh | 16 ++++++++-------- 3 files changed, 16 insertions(+), 8 deletions(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index f1cf571fcd..6d65033e44 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -155,6 +155,13 @@ color:: `reverse`. The first color given is the foreground; the second is the background. The position of the attribute, if any, doesn't matter. ++ +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. Variables diff --git a/log-tree.c b/log-tree.c index 1982631ca4..11676d5235 100644 --- a/log-tree.c +++ b/log-tree.c @@ -200,6 +200,7 @@ void format_decorations(struct strbuf *sb, while (decoration) { strbuf_addstr(sb, color_commit); strbuf_addstr(sb, prefix); + strbuf_addstr(sb, color_reset); strbuf_addstr(sb, decorate_get_color(use_color, decoration->type)); if (decoration->type == DECORATION_REF_TAG) strbuf_addstr(sb, "tag: "); diff --git a/t/t4207-log-decoration-colors.sh b/t/t4207-log-decoration-colors.sh index 925f577a3c..6b8ad4f5b0 100755 --- a/t/t4207-log-decoration-colors.sh +++ b/t/t4207-log-decoration-colors.sh @@ -44,15 +44,15 @@ test_expect_success setup ' ' cat >expected <