lib/terminal-colors.d.5

   1 .\" terminal-colors.d.5 --
   2 .\" Copyright 2014 Ondrej Oprala <ooprala@redhat.com>
   3 .\" Copyright (C) 2014 Karel Zak <kzak@redhat.com>
   4 .\" Copyright 2014 Red Hat, Inc.
   5 .\" May be distributed under the GNU General Public License
   6 .TH "TERMINAL_COLORS.D" "5" "January 2014" "util-linux" "terminal-colors.d"
   7 .SH NAME
   8 terminal-colors.d \- Configure output colorization for various utilities
   9 .SH SYNOPSIS
  10 /etc/terminal-colors\&.d/[[\fIname\fR][@\fIterm\fR]\&.][\fItype\fR]
  11 .SH DESCRIPTION
  12 Files in this directory determine the default behavior for utilities
  13 when coloring output.
  14
  15 The
  16 .I name
  17 is a utility name.  The name is optional and when none is specified then the
  18 file is used for all unspecified utilities.
  19
  20 The
  21 .I term
  22 is a terminal identifier (the TERM environment variable).
  23 The terminal identifier is optional and when none is specified then the file
  24 is used for all unspecified terminals.
  25
  26 The
  27 .I type
  28 is a file type.  Supported file types are:
  29 .TP
  30 .B disable
  31 Turns off output colorization for all compatible utilities.
  32 .TP
  33 .B enable
  34 Turns on output colorization; any matching
  35 .B disable
  36 files are ignored.
  37 .TP
  38 .B scheme
  39 Specifies colors used for output.  The file format may be specific to the utility,
  40 the default format is described below.
  41 .PP
  42 If there are more files that match for a utility, then the file with the more
  43 specific filename wins.  For example, the filename "@xterm.scheme" has less
  44 priority than "dmesg@xterm.scheme".  The lowest priority are those files without a
  45 utility name and terminal identifier (e.g., "disable").
  46
  47 The user-specific
  48 .I $XDG_CONFIG_HOME/terminal-colors.d
  49 or
  50 .I $HOME/.config/terminal-colors.d
  51 overrides the global setting.
  52
  53 .SH EXAMPLE
  54 Disable colors for all compatible utilities:
  55 .RS
  56 .br
  57 .B "touch /etc/terminal-colors.d/disable"
  58 .br
  59 .RE
  60
  61 Disable colors for all compatible utils on a vt100 terminal:
  62 .RS
  63 .br
  64 .B "touch /etc/terminal-colors.d/@vt100.disable"
  65 .br
  66 .RE
  67
  68 Disable colors for all compatible utils except dmesg(1):
  69 .RS
  70 .br
  71 .B "touch /etc/terminal-colors.d/disable"
  72 .sp
  73 .B "touch /etc/terminal-colors.d/dmesg.enable"
  74 .br
  75 .RE
  76
  77 .SH DEFAULT SCHEME FILES FORMAT
  78 The following statement is recognized:
  79
  80 .RS
  81 .br
  82 .B "name color-sequence"
  83 .br
  84 .RE
  85
  86 The
  87 .B name
  88 is a logical name of color sequence (for example "error").  The names are
  89 specific to the utilities.  For more details always see the COLORS section
  90 in the man page for the utility.
  91
  92 The
  93 .B color-sequence
  94 is a color name, ASCII color sequences or escape sequences.
  95
  96 .SS Color names
  97 black, blink, blue, bold, brown, cyan, darkgray, gray, green, halfbright,
  98 lightblue, lightcyan, lightgray, lightgreen, lightmagenta, lightred, magenta,
  99 red, reset, reverse, and yellow.
 100
 101 .SS ANSI color sequences
 102 The color sequences are composed of sequences of numbers
 103 separated by semicolons.  The most common codes are:
 104 .sp
 105 .RS
 106 .TS
 107 l l.
 108  0      to restore default color
 109  1      for brighter colors
 110  4      for underlined text
 111  5      for flashing text
 112 30      for black foreground
 113 31      for red foreground
 114 32      for green foreground
 115 33      for yellow (or brown) foreground
 116 34      for blue foreground
 117 35      for purple foreground
 118 36      for cyan foreground
 119 37      for white (or gray) foreground
 120 40      for black background
 121 41      for red background
 122 42      for green background
 123 43      for yellow (or brown) background
 124 44      for blue background
 125 45      for purple background
 126 46      for cyan background
 127 47      for white (or gray) background
 128 .TE
 129 .RE
 130 .SS Escape sequences
 131 To specify control or blank characters in the color sequences,
 132 C-style \e-escaped notation can be used:
 133 .sp
 134 .RS
 135 .TS
 136 lb l.
 137 \ea     Bell (ASCII 7)
 138 \eb     Backspace (ASCII 8)
 139 \ee     Escape (ASCII 27)
 140 \ef     Form feed (ASCII 12)
 141 \en     Newline (ASCII 10)
 142 \er     Carriage Return (ASCII 13)
 143 \et     Tab (ASCII 9)
 144 \ev     Vertical Tab (ASCII 11)
 145 \e?     Delete (ASCII 127)
 146 \e_     Space
 147 \e\e    Backslash (\e)
 148 \e^     Caret (^)
 149 \e#     Hash mark (#)
 150 .TE
 151 .RE
 152 .sp
 153 Please note that escapes are necessary to enter a space, backslash,
 154 caret, or any control character anywhere in the string, as well as a
 155 hash mark as the first character.
 156
 157 For example, to use a red background for alert messages in the output of
 158 .BR dmesg (1),
 159 use:
 160
 161 .RS
 162 .br
 163 .B "echo 'alert 37;41' >> /etc/terminal-colors.d/dmesg.scheme"
 164 .br
 165 .RE
 166
 167 .SS Comments
 168 Lines where the first non-blank character is a # (hash) are ignored.
 169 Any other use of the hash character is not interpreted as introducing
 170 a comment.
 171
 172 .SH FILES
 173 .I $XDG_CONFIG_HOME/terminal-colors.d
 174 .br
 175 .I $HOME/.config/terminal-colors.d
 176 .br
 177 .I /etc/terminal-colors.d
 178
 179 .SH ENVIRONMENT
 180 .IP TERMINAL_COLORS_DEBUG=all
 181 enables debug output.
 182
 183 .SH COMPATIBILITY
 184 The terminal-colors.d functionality is currently supported by all util-linux
 185 utilities which provides colorized output.  For more details always see the
 186 COLORS section in the man page for the utility.
 187
 188 .SH AVAILABILITY
 189 terminal-colors.d is part of the util-linux package and is available from
 190 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
 191 Linux Kernel Archive
 192 .UE .