[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
dircolors database documentation
From: |
Eric Blake |
Subject: |
dircolors database documentation |
Date: |
Mon, 17 Oct 2005 07:15:39 -0600 |
User-agent: |
Mozilla Thunderbird 1.0.2 (Windows/20050317) |
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Now that my copyright papers are finally in the mail, I can contribute
this for eventual inclusion! I am not very experienced with texinfo yet,
so I would appreciate a proofread (although I did validate that everything
looks readable in info). When this is applied, we can (once again) patch
src/dcgen to strip comments from the built-in database.
doc/ChangeLog
2005-10-17 Eric Blake <address@hidden>
* coreutils.texi (ls invocation): Document effect of
LS_COLORS on --color.
(dircolors database format): New section.
- --
Life is short - so eat dessert first!
Eric Blake address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org
iD8DBQFDU6P784KuGfSFAYARAn9KAKDTWn1hnMLQ7K5RV+wo7GU7TxvHjgCeJWGF
rUUzwef5iWKHzMLN6gqB+M0=
=OciN
-----END PGP SIGNATURE-----
Index: doc/coreutils.texi
===================================================================
RCS file: /cvsroot/coreutils/coreutils/doc/coreutils.texi,v
retrieving revision 1.289
diff -u -p -r1.289 coreutils.texi
--- doc/coreutils.texi 16 Oct 2005 07:27:04 -0000 1.289
+++ doc/coreutils.texi 17 Oct 2005 13:10:56 -0000
@@ -4558,7 +4558,7 @@ c
$ paste num2 let3
1 a
2 b
- c
+ @ c
@end example
Synopsis:
@@ -5235,6 +5235,7 @@ and @command{vdir}, which list informati
* dir invocation:: Briefly ls.
* vdir invocation:: Verbosely ls.
* dircolors invocation:: Color setup for ls, etc.
+* dircolors database format:: Input for dircolors.
@end menu
@@ -5820,8 +5821,11 @@ possible in the fewest lines.
@item --color address@hidden
@opindex --color
@cindex color, distinguishing file types with
-Specify whether to use color for distinguishing file types. @var{when}
-may be omitted, or one of:
+Specify whether to use color for distinguishing file types. If the
+environment variable @env{LS_COLORS} is set, the color scheme is
+parsed from that variable; otherwise, ls comes with a builtin default
+color scheme. For more details on setting @env{LS_COLORS}, see
address@hidden invocation}. @var{when} may be omitted, or one of:
@itemize @bullet
@item none
@vindex none @r{color option}
@@ -6202,8 +6206,9 @@ eval "`dircolors address@hidden@dots{} [
If @var{file} is specified, @command{dircolors} reads it to determine which
colors to use for which file types and extensions. Otherwise, a
-precompiled database is used. For details on the format of these files,
-run @samp{dircolors --print-database}.
+precompiled database is used, whose contents are visible by running
address@hidden --print-database}. For details on the format of these
+files, see @ref{dircolors database format}.
@vindex LS_COLORS
@vindex SHELL @r{environment variable, and color}
@@ -6246,12 +6251,193 @@ Output C shell commands. This is the de
@cindex database for color setup, printing
@cindex printing color database
Print the (compiled-in) default color configuration database. This
-output is itself a valid configuration file, and is fairly descriptive
-of the possibilities.
+output is itself a valid configuration file, although it is rather
+compact.
@end table
@exitstatus
+
+
address@hidden dircolors database format
address@hidden @command{dircolors} database format: Input for
@command{dircolors}
+
address@hidden dircolors file format
address@hidden input format, dircolors
address@hidden format, dircolors input file
+Dircolors parses a database to determine the color configuration that
+is appropriate for the current @env{TERM}. It consists of a series of
+lines containing a keyword and argument, separated by whitespace. A #
+character starts a comment anywhere in the line, except inside of a .
+or * keyword. Blank lines are ignored, and whitespace is ignored at
+the beginning of a line and prior to a comment or line end. There is
+no way to quote whitespace.
+
+It is an error if a keyword does not contain an argument, or if an
+unrecognized keyword is encountered. Except for . and * keywords,
+case is ignored when recognizing keywords, although the keywords are
+usually written in uppercase.
+
+Most arguments are color descriptions, strings that are echoed
+verbatim inside of a terminal escape sequence. Most terminals these
+days recognize @acronym{ANSI} color sequences. @acronym{ANSI} color
+sequences are a semicolon-separated list of numbers. The font
+attributes can be set with 0=none, 1=bold, 4=underscore, 5=blink,
+7=reverse, and 8=concealed. The foreground colors can be set with
+30=black, 31=red, 32=green, 33=yellow, 34=blue, 35=magenta, 36=cyan,
+and 37=white. The background colors can be set with 40=black, 41=red,
+42=green, 43=yellow, 44=blue, 45=magenta, 46=cyan, and 47=white. For
+example, on a terminal that recognizes @acronym{ANSI} colors, the line
+``DIR 01;34'' would set the color of directory entries to a bold blue
+on the default background.
+
+The database is divided into a series of terminal descriptions. Each
+terminal description begins with one or more TERM lines, followed by
+any number of non-TERM lines that will apply to any of the terminal
+types mentioned in the TERM lines. This capability allows a single
+database to specify different escape codes for different terminals, by
+using multiple terminal descriptions. A terminal type can be named in
+more than one terminal section; the effect is cumulative. If more
+than one rule applies to a file, the last one specified takes
+precedence.
+
+The following keywords are recognized.
+
address@hidden @samp
address@hidden .<string>
+A suffix pattern-matching rule, equivalent to *.<string>. For
+example, @samp{.tar 01;31} will color files that match *.tar with a
+bright red foreground.
+
address@hidden *<string>
+A pattern-matching rule. The entire keyword, including the leading *,
+is treated as a shell glob, case sensitively. Files that match the
+glob will be colored by this rule. There are no default
+pattern-matching rules in ls, so you must use dircolors to get
+pattern-matching.
+
address@hidden BLK
address@hidden BLOCK
+The color string for block special devices. If not specified, ls
+defaults this category to @samp{01;33}.
+
address@hidden CHAR
address@hidden CHR
+The color string for character special devices. If not specified, ls
+defaults this category to @samp{01;33}.
+
address@hidden COLOR
+Ignored for compatibility. Instead, to turn ls coloring on when
+stdout is a terminal, you should use a shell alias for ls that
+includes '--color=auto'.
+
address@hidden DIR
+The color string for directories that are not sticky (+t) and not
+world-writable (o+w). If not specified, ls defaults this category to
address@hidden;34}.
+
address@hidden DOOR
+The color string for doors, on systems that support this file type.
+If not specified, ls defaults this category to @samp{01;35}.
+
address@hidden EIGHTBIT
+Ignored for compatibility. GNU ls is eight-bit clean by default, but
+you may need to change your shell settings. You may also be
+interested in adding the --quoting-style argument in your alias for
+ls.
+
address@hidden END
address@hidden ENDCODE
+The string to use to reset the terminal to normal coloration. If not
+specified, ls uses the sequence LEFT, NORM, RIGHT.
+
address@hidden EXEC
+The color string for executable files. If not specified, ls defaults
+this category to @samp{01;32}.
+
address@hidden FIFO
address@hidden PIPE
+The color string for pipes (named fifos). If not specified, ls
+defaults this category to @samp{33}.
+
address@hidden FILE
+The color string for files that do not fit any of the other
+categories or string matching rules. If not specified, ls defaults
+this category to @samp{0}.
+
address@hidden LEFT
address@hidden LEFTCODE
+The string that begins a terminal escape sequence. If not specified,
+ls defaults this to @samp{\033[}.
+
address@hidden LINK
address@hidden LNK
address@hidden SYMLINK
+The color string for symbolic links, or the special argument
+``target'' to set the color according to the file type the symbolic
+link points to. If set to target, then the MISSING category
+determines the color of broken symlinks. If not specified, ls
+defaults this category to @samp{01;36}.
+
address@hidden MISSING
+The color string for broken symlinks, when LINK is set to
+``target''. If not specified, ls reuses the FILE specification.
+
address@hidden NORM
address@hidden NORMAL
+The color string for restoring the terminal color sequence to
+normal. If not specified, ls defaults this category to @samp{0}.
+
address@hidden OPTIONS
+Ignored for compatibility. Instead, if you want options to be added
+by default to ls when invoked from the command line, consider using a
+shell alias for ls.
+
address@hidden ORPHAN
+The color string for a broken (orphaned) symlink. If not specified,
+ls reuses the LINK specification.
+
address@hidden OTHER_WRITABLE
address@hidden OWR
+The color string for directories that are world-writable (o+w,-t).
+If not specified, ls defaults this category to @samp{34;42}.
+
address@hidden RIGHT
address@hidden RIGHTCODE
+The string that ends a terminal escape sequence. If not specified,
+ls defaults this to @samp{m}.
+
address@hidden SETGID
address@hidden SGID
+The color string for a setgid (g+s) file. If not specified, ls
+defaults this category to @samp{30;43}.
+
address@hidden SETUID
address@hidden SUID
+The color string for a setuid (u+s) file. If not specified, ls
+defaults this category to @samp{37;41}.
+
address@hidden SOCK
+The color string for sockets. If not specified, ls defaults this
+category to @samp{01;35}.
+
address@hidden STICKY
+The color string for directories with only the sticky bit set
+(+t,o-w). If not specified, ls defaults this category to @samp{30;42}.
+
address@hidden STICKY_OTHER_WRITABLE
address@hidden OWT
+The color string for directories with both the sticky bit set and
+world-writable (+t,o+w). If not specified, ls defaults this category
+to @samp{30;42}.
+
address@hidden TERM
+Add a terminal type to the current terminal description, beginning a
+new terminal description if the previous line was not a TERM line. If
+the environment variable @env{TERM} matches the argument of the TERM
+keyword, then the current description affects the output.
+
address@hidden table
@node Basic operations
- dircolors database documentation,
Eric Blake <=
- Re: dircolors database documentation, Jim Meyering, 2005/10/17
- Re: dircolors database documentation, Eric Blake, 2005/10/18
- Re: dircolors database documentation, Eric Blake, 2005/10/18
- Re: dircolors database documentation, Eric Blake, 2005/10/18
- Re: dircolors database documentation, Paul Eggert, 2005/10/18
- Re: dircolors database documentation, Jim Meyering, 2005/10/18
- Re: dircolors database documentation, Jim Meyering, 2005/10/19
- Re: dircolors database documentation, Eric Blake, 2005/10/22
- Re: dircolors database documentation, Paul Eggert, 2005/10/23