Jeff King <peff@xxxxxxxx> writes: > I'd agree it is worth a mention in the log (and possibly release notes), > but I don't think it is worth polluting the documentation forever > (though explaining that we never inherit might be worth doing, and that > is perhaps what you meant). Yes, I do not know how well the attached will render, but something along the lines of this patch is what I had in mind. -- >8 -- Subject: config.txt: spell out how certain typed values are written Many variables have values that are not arbitrary strings and there are ways to spell these values of certain types. The way to spell colors was described in a section for color.branch.<slot> and other variables refered to that section, which was technically wrong, but was a bit awkward. I didn't attempt to de-dup descriptions for boolean and integer valued variables in this change, but somebody may want to read the existing descriptions of these variables over and drop them as necessary. Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx> --- Documentation/config.txt | 58 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 42 insertions(+), 16 deletions(-) diff --git a/Documentation/config.txt b/Documentation/config.txt index 097fdd4..171287e 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -126,6 +126,45 @@ 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'. + true;; Boolean true can be spelled as `yes`, `on`, `true`, + or `1`. Also, a variable defined without `= <value>` + is taken as true. + false;; Boolean false can be spelled as `no`, `off`, + `false`, or `0`. + +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. + +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. ++ +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 ~~~~~~~~~ @@ -817,14 +856,6 @@ color.branch.<slot>:: `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. @@ -844,8 +875,7 @@ color.diff.<slot>:: 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.<slot>. + (highlighting whitespace errors). color.decorate.<slot>:: Use customized color for 'git log --decorate' output. `<slot>` is one @@ -878,8 +908,6 @@ color.grep.<slot>:: separators between fields on a line (`:`, `-`, and `=`) and between hunks (`--`) -- -+ -The values of these variables may be specified as in color.branch.<slot>. color.interactive:: When set to `always`, always use colors for interactive prompts @@ -892,8 +920,7 @@ color.interactive.<slot>:: Use customized color for 'git add --interactive' and 'git clean --interactive' output. `<slot>` 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.<slot>. + interactive commands. color.pager:: A boolean to enable/disable colored output when the pager is in @@ -919,8 +946,7 @@ color.status.<slot>:: `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.<slot>. + to red). color.ui:: This variable determines the default value for variables such -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html