Debian Codegraph @

upstream/debian-trixie/man5/dir_colors.5

raw
1 '\" t
2 .\" Copyright (c) 2001 Martin Schulze <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\"
6 .TH dir_colors 5 2024-06-16 "Linux man-pages 6.9.1"
7 .SH NAME
8 dir_colors \- configuration file for dircolors(1)
9 .SH DESCRIPTION
10 The program
11 .BR ls (1)
12 uses the environment variable
13 .B LS_COLORS
14 to determine the colors in which the filenames are to be displayed.
15 This environment variable is usually set by a command like
16 .P
17 .RS
18 eval \`dircolors some_path/dir_colors\`
19 .RE
20 .P
21 found in a system default shell initialization file, like
22 .I /etc/profile
23 or
24 .IR /etc/csh.cshrc .
25 (See also
26 .BR dircolors (1).)
27 Usually, the file used here is
28 .I /etc/DIR_COLORS
29 and can be overridden by a
30 .I .dir_colors
31 file in one's home directory.
32 .P
33 This configuration file consists of several statements, one per line.
34 Anything right of a hash mark (#) is treated as a comment, if the
35 hash mark is at the beginning of a line or is preceded by at least one
36 whitespace.
37 Blank lines are ignored.
38 .P
39 The
40 .I global
41 section of the file consists of any statement before the first
42 .B TERM
43 statement.
44 Any statement in the global section of the file is
45 considered valid for all terminal types.
46 Following the global section
47 is one or more
48 .I terminal-specific
49 sections, preceded by one or more
50 .B TERM
51 statements which specify the terminal types (as given by the
52 .B TERM
53 environment variable) the following declarations apply to.
54 It is always possible to override a global declaration by a subsequent
55 terminal-specific one.
56 .P
57 The following statements are recognized; case is insignificant:
58 .TP
59 .B TERM \fIterminal-type\fR
60 Starts a terminal-specific section and specifies which terminal it
61 applies to.
62 Multiple
63 .B TERM
64 statements can be used to create a section which applies for several
65 terminal types.
66 .TP
67 .B COLOR yes|all|no|none|tty
68 (Slackware only; ignored by GNU
69 .BR dircolors (1).)
70 Specifies that colorization should always be enabled (\fIyes\fR or
71 \fIall\fR), never enabled (\fIno\fR or \fInone\fR), or enabled only if
72 the output is a terminal (\fItty\fR).
73 The default is \fIno\fR.
74 .TP
75 .B EIGHTBIT yes|no
76 (Slackware only; ignored by GNU
77 .BR dircolors (1).)
78 Specifies that eight-bit ISO/IEC\~8859 characters should be enabled by
79 default.
80 For compatibility reasons, this can also be specified as 1 for
81 \fIyes\fR or 0 for \fIno\fR.
82 The default is \fIno\fR.
83 .TP
84 .B OPTIONS \fIoptions\fR
85 (Slackware only; ignored by GNU
86 .BR dircolors (1).)
87 Adds command-line options to the default
88 .B ls
89 command line.
90 The options can be any valid
91 .B ls
92 command-line options, and should include the leading minus sign.
93 Note that
94 .B dircolors
95 does not verify the validity of these options.
96 .TP
97 .B NORMAL \fIcolor-sequence\fR
98 Specifies the color used for normal (nonfilename) text.
99 .IP
100 Synonym:
101 .BR NORM .
102 .TP
103 .B FILE \fIcolor-sequence\fR
104 Specifies the color used for a regular file.
105 .TP
106 .B DIR \fIcolor-sequence\fR
107 Specifies the color used for directories.
108 .TP
109 .B LINK \fIcolor-sequence\fR
110 Specifies the color used for a symbolic link.
111 .IP
112 Synonyms:
113 .BR LNK ,
114 .BR SYMLINK .
115 .TP
116 .B ORPHAN \fIcolor-sequence\fR
117 Specifies the color used for an orphaned symbolic link (one which
118 points to a nonexistent file).
119 If this is unspecified,
120 .B ls
121 will use the
122 .B LINK
123 color instead.
124 .TP
125 .B MISSING \fIcolor-sequence\fR
126 Specifies the color used for a missing file (a nonexistent file which
127 nevertheless has a symbolic link pointing to it).
128 If this is unspecified,
129 .B ls
130 will use the
131 .B FILE
132 color instead.
133 .TP
134 .B FIFO \fIcolor-sequence\fR
135 Specifies the color used for a FIFO (named pipe).
136 .IP
137 Synonym:
138 .BR PIPE .
139 .TP
140 .B SOCK \fIcolor-sequence\fR
141 Specifies the color used for a socket.
142 .TP
143 .B DOOR \fIcolor-sequence\fR
144 (Supported since fileutils 4.1)
145 Specifies the color used for a door (Solaris 2.5 and later).
146 .TP
147 .B BLK \fIcolor-sequence\fR
148 Specifies the color used for a block device special file.
149 .IP
150 Synonym:
151 .BR BLOCK .
152 .TP
153 .B CHR \fIcolor-sequence\fR
154 Specifies the color used for a character device special file.
155 .IP
156 Synonym:
157 .BR CHAR .
158 .TP
159 .B EXEC \fIcolor-sequence\fR
160 Specifies the color used for a file with the executable attribute set.
161 .TP
162 .B SUID \fIcolor-sequence\fR
163 Specifies the color used for a file with the set-user-ID attribute set.
164 .IP
165 Synonym:
166 .BR SETUID .
167 .TP
168 .B SGID \fIcolor-sequence\fR
169 Specifies the color used for a file with the set-group-ID attribute set.
170 .IP
171 Synonym:
172 .BR SETGID .
173 .TP
174 .B STICKY \fIcolor-sequence\fR
175 Specifies the color used for a directory with the sticky attribute set.
176 .TP
177 .B STICKY_OTHER_WRITABLE \fIcolor-sequence\fR
178 Specifies the color used for
179 an other-writable directory with the executable attribute set.
180 .IP
181 Synonym:
182 .BR OWT .
183 .TP
184 .B OTHER_WRITABLE \fIcolor-sequence\fR
185 Specifies the color used for
186 an other-writable directory without the executable attribute set.
187 .IP
188 Synonym:
189 .BR OWR .
190 .TP
191 .B LEFTCODE \fIcolor-sequence\fR
192 Specifies the
193 .I "left code"
194 for non-ISO/IEC\~6429 terminals (see below).
195 .IP
196 Synonym:
197 .BR LEFT .
198 .TP
199 .B RIGHTCODE \fIcolor-sequence\fR
200 Specifies the
201 .I "right code"
202 for non-ISO/IEC\~6429 terminals (see below).
203 .IP
204 Synonym:
205 .BR RIGHT .
206 .TP
207 .B ENDCODE \fIcolor-sequence\fR
208 Specifies the
209 .I "end code"
210 for non-ISO/IEC\~6429 terminals (see below).
211 .IP
212 Synonym:
213 .BR END .
214 .TP
215 .BI * "extension color-sequence"
216 Specifies the color used for any file that ends in \fIextension\fR.
217 .TP
218 .BI . "extension color-sequence"
219 Same as \fB*\fR.\fIextension\fR.
220 Specifies the color used for any file that
221 ends in .\fIextension\fR.
222 Note that the period is included in the
223 extension, which makes it impossible to specify an extension not
224 starting with a period, such as
225 .B \[ti]
226 for
227 .B emacs
228 backup files.
229 This form should be considered obsolete.
230 .SS ISO/IEC\~6429 (ANSI) color sequences
231 Most color-capable ASCII terminals today use
232 ISO/IEC\~6429 (ANSI) color sequences,
233 and many common terminals without color capability, including
234 .B xterm
235 and the widely used and cloned DEC VT100, will recognize ISO/IEC\~6429 color
236 codes and harmlessly eliminate them from the output or emulate them.
237 .B ls
238 uses ISO/IEC\~6429 codes by default, assuming colorization is enabled.
239 .P
240 ISO/IEC\~6429 color sequences are composed of sequences of numbers
241 separated by semicolons.
242 The most common codes are:
243 .RS
244 .TS
245 l l.
246 0 to restore default color
247 1 for brighter colors
248 4 for underlined text
249 5 for flashing text
250 30 for black foreground
251 31 for red foreground
252 32 for green foreground
253 33 for yellow (or brown) foreground
254 34 for blue foreground
255 35 for purple foreground
256 36 for cyan foreground
257 37 for white (or gray) foreground
258 40 for black background
259 41 for red background
260 42 for green background
261 43 for yellow (or brown) background
262 44 for blue background
263 45 for purple background
264 46 for cyan background
265 47 for white (or gray) background
266 .TE
267 .RE
268 .P
269 Not all commands will work on all systems or display devices.
270 .P
271 .B ls
272 uses the following defaults:
273 .TS
274 lb l l.
275 NORMAL 0 Normal (nonfilename) text
276 FILE 0 Regular file
277 DIR 32 Directory
278 LINK 36 Symbolic link
279 ORPHAN undefined Orphaned symbolic link
280 MISSING undefined Missing file
281 FIFO 31 Named pipe (FIFO)
282 SOCK 33 Socket
283 BLK 44;37 Block device
284 CHR 44;37 Character device
285 EXEC 35 Executable file
286 .TE
287 .P
288 A few terminal programs do not recognize the default
289 properly.
290 If all text gets colorized after you do a directory
291 listing, change the
292 .B NORMAL
293 and
294 .B FILE
295 codes to the numerical codes for your normal foreground and background
296 colors.
297 .SS Other terminal types (advanced configuration)
298 If you have a color-capable (or otherwise highlighting) terminal (or
299 printer!) which uses a different set of codes, you can still generate
300 a suitable setup.
301 To do so, you will have to use the
302 .BR LEFTCODE ,
303 .BR RIGHTCODE ,
304 and
305 .B ENDCODE
306 definitions.
307 .P
308 When writing out a filename,
309 .B ls
310 generates the following output sequence:
311 .B LEFTCODE
312 .I typecode
313 .B RIGHTCODE
314 .I filename
315 .BR ENDCODE ,
316 where the
317 .I typecode
318 is the color sequence that depends on the type or name of file.
319 If the
320 .B ENDCODE
321 is undefined, the sequence
322 .B "LEFTCODE NORMAL RIGHTCODE"
323 will be used instead.
324 The purpose of the left- and rightcodes is
325 merely to reduce the amount of typing necessary (and to hide ugly
326 escape codes away from the user).
327 If they are not appropriate for
328 your terminal, you can eliminate them by specifying the respective
329 keyword on a line by itself.
330 .P
331 .B NOTE:
332 If the
333 .B ENDCODE
334 is defined in the global section of the setup file, it
335 .I cannot
336 be undefined in a terminal-specific section of the file.
337 This means any
338 .B NORMAL
339 definition will have no effect.
340 A different
341 .B ENDCODE
342 can, however, be specified, which would have the same effect.
343 .SS Escape sequences
344 To specify control- or blank characters in the color sequences or
345 filename extensions, either C-style \[rs]-escaped notation or
346 .BR stty \-style
347 \[ha]-notation can be used.
348 The C-style notation
349 includes the following characters:
350 .RS
351 .TS
352 lb l.
353 \[rs]a Bell (ASCII 7)
354 \[rs]b Backspace (ASCII 8)
355 \[rs]e Escape (ASCII 27)
356 \[rs]f Form feed (ASCII 12)
357 \[rs]n Newline (ASCII 10)
358 \[rs]r Carriage Return (ASCII 13)
359 \[rs]t Tab (ASCII 9)
360 \[rs]v Vertical Tab (ASCII 11)
361 \[rs]? Delete (ASCII 127)
362 \[rs]\fInnn Any character (octal notation)
363 \[rs]x\fInnn Any character (hexadecimal notation)
364 \[rs]_ Space
365 \[rs]\[rs] Backslash (\[rs])
366 \[rs]\[ha] Caret (\[ha])
367 \[rs]# Hash mark (#)
368 .TE
369 .RE
370 .P
371 Note that escapes are necessary to enter a space, backslash,
372 caret, or any control character anywhere in the string, as well as a
373 hash mark as the first character.
374 .SH FILES
375 .TP
376 .I /etc/DIR_COLORS
377 System-wide configuration file.
378 .\" Rejected upstream
379 (Slackware, SuSE and RedHat only; ignored by GNU
380 .BR dircolors (1)
381 and thus Debian.)
382 .TP
383 .I \[ti]/.dir_colors
384 .\" Rejected upstream
385 (Slackware, SuSE and RedHat only; ignored by GNU
386 .BR dircolors (1)
387 and thus Debian.)
388 Per-user configuration file.
389 .P
390 This page describes the
391 .B dir_colors
392 file format as used in the fileutils-4.1 package;
393 other versions may differ slightly.
394 .SH NOTES
395 The default
396 .B LEFTCODE
397 and
398 .B RIGHTCODE
399 definitions, which are used by ISO/IEC\~6429 terminals are:
400 .RS
401 .TS
402 lb l.
403 LEFTCODE \[rs]e[
404 RIGHTCODE m
405 .TE
406 .RE
407 .P
408 The default
409 .B ENDCODE
410 is undefined.
411 .SH SEE ALSO
412 .BR dircolors (1),
413 .BR ls (1),
414 .BR stty (1),
415 .BR xterm (1)