Debian Codegraph @

upstream/debian-unstable/man5/dir_colors.5

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