config.txt,diff-options.txt: porcelain vs. plumbing for color.diff
Reading the diff-family and config man pages one may think that the color.diff and color.ui settings apply to all diff commands. Make it clearer that they do not apply to the plumbing variants diff-{files,index,tree}. Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Michael J Gruber committed
Apr 27, 2011 at 09:38 UTC
6999c54029b42ea996c2fff4fa37303f79b9d8c2
2 files changed
+30
-12
Documentation/config.txt
+19
-8
@@ -708,9 +708,16 @@ second is the background. The position of the attribute, if any,
708
doesn't matter.
709
710
color.diff::
711
- When set to `always`, always use colors in patch.
712
- When false (or `never`), never. When set to `true` or `auto`, use
713
- colors only when the output is to the terminal. Defaults to false.
711
+ Whether to use ANSI escape sequences to add color to patches.
712
+ If this is set to `always`, linkgit:git-diff[1],
713
+ linkgit:git-log[1], and linkgit:git-show[1] will use color
714
+ for all patches. If it is set to `true` or `auto`, those
715
+ commands will only use color when output is to the terminal.
716
+ Defaults to false.
717
++
718
+This does not affect linkgit:git-format-patch[1] nor the
719
+'git-diff-{asterisk}' plumbing commands. Can be overridden on the
720
+command line with the `--color[=<when>]` option.
721
722
color.diff.<slot>::
723
Use customized color for diff colorization. `<slot>` specifies
@@ -796,11 +803,15 @@ color.status.<slot>::
803
color.branch.<slot>.
804
805
color.ui::
799
- When set to `always`, always use colors in all git commands which
800
- are capable of colored output. When false (or `never`), never. When
801
- set to `true` or `auto`, use colors only when the output is to the
802
- terminal. When more specific variables of color.* are set, they always
803
- take precedence over this setting. Defaults to false.
806
+ This variable determines the default value for variables such
807
+ as `color.diff` and `color.grep` that control the use of color
808
+ per command family. Its scope will expand as more commands learn
809
+ configuration to set a default for the `--color` option. Set it
810
+ to `always` if you want all output not intended for machine
811
+ consumption to use color, to `true` or `auto` if you want such
812
+ output to use color when written to the terminal, or to `false` or
813
+ `never` if you prefer git commands not to use color unless enabled
814
+ explicitly with some other configuration or the `--color` option.
815
816
commit.status::
817
A boolean to enable/disable inclusion of status information in the
Documentation/diff-options.txt
+11
-4
@@ -120,12 +120,19 @@ any of those replacements occurred.
120
121
--color[=<when>]::
122
Show colored diff.
123
- The value must be always (the default), never, or auto.
123
+ The value must be `always` (the default for `<when>`), `never`, or `auto`.
124
+ The default value is `never`.
125
+ifdef::git-diff[]
126
+ It can be changed by the `color.ui` and `color.diff`
127
+ configuration settings.
128
+endif::git-diff[]
129
130
--no-color::
126
- Turn off colored diff, even when the configuration file
127
- gives the default to color output.
128
- Same as `--color=never`.
131
+ Turn off colored diff.
132
+ifdef::git-diff[]
133
+ This can be used to override configuration settings.
134
+endif::git-diff[]
135
+ It is the same as `--color=never`.
136
137
--word-diff[=<mode>]::
138
Show a word diff, using the <mode> to delimit changed words.