$OpenBSD: patch-colorls_1,v 1.10 2007/08/11 18:41:28 naddy Exp $
--- colorls.1.orig	Sat Aug 11 20:38:04 2007
+++ colorls.1	Sat Aug 11 20:37:37 2007
@@ -37,11 +37,11 @@
 .Dt COLORLS 1
 .Os
 .Sh NAME
-.Nm ls
+.Nm colorls
 .Nd list directory contents
 .Sh SYNOPSIS
-.Nm ls
-.Op Fl 1AaCcdFfghikLlmnopqRrSsTtux
+.Nm
+.Op Fl 1AaCcdFfGghikLlmnopqRrSsTtux
 .Op Ar file ...
 .Sh DESCRIPTION
 For each operand that names a
@@ -112,6 +112,12 @@ and a vertical bar
 after each that is a FIFO.
 .It Fl f
 Output is not sorted.
+.It Fl G
+Enable colorized output.
+This option is equivalent to defining
+.Ev CLICOLOR
+in the environment.
+(See below.)
 .It Fl g
 The same as
 .Fl l ,
@@ -414,7 +420,7 @@ The
 .Nm
 utility exits 0 on success or \*(Gt0 if an error occurred.
 .Sh ENVIRONMENT
-.Bl -tag -width BLOCKSIZE
+.Bl -tag -width CLICOLOR_FORCE
 .It Ev BLOCKSIZE
 If the environment variable
 .Ev BLOCKSIZE
@@ -424,6 +430,44 @@ option is not specified, the block counts
 (see
 .Fl s )
 will be displayed in units of that size block.
+.It Ev CLICOLOR
+Use
+\*[Ai]
+color sequences to distinguish file types.
+See
+.Ev LSCOLORS
+below.
+In addition to the file types mentioned in the
+.Fl F
+option some extra attributes (setuid bit set, etc.) are also displayed.
+The colorization is dependent on a terminal type with the proper
+.Xr termcap 5
+capabilities.
+To display the colors on the
+.Xr wscons 4
+console, for example,
+the
+.Ev TERM
+variable must be set to
+.Dq wsvt25
+and in an
+.Xr xterm 1
+to
+.Dq Li xterm-xfree86 .
+Other terminal types may require similar adjustments.
+Colorization is silently disabled if the output isn't directed to a terminal
+unless the
+.Ev CLICOLOR_FORCE
+variable is defined.
+.It Ev CLICOLOR_FORCE
+Color sequences are normally disabled if the output isn't directed to
+a terminal.
+This can be overridden by setting this flag.
+The
+.Ev TERM
+variable still needs to reference a color capable terminal however
+otherwise it is not possible to determine which color sequences to
+use.
 .It COLUMNS
 If this variable contains a string representing a
 decimal integer, it is used as the
@@ -436,6 +480,99 @@ many pathname text columns to display
 based on the width provided
 (see
 .Fl C ) .
+.It Ev LSCOLORS
+The value of this variable describes what color to use for which
+attribute when colors are enabled with
+.Ev CLICOLOR .
+This string is a concatenation of pairs of the format
+.Ar f Ns Ar b ,
+where
+.Ar f
+is the foreground color and
+.Ar b
+is the background color.
+.Pp
+The color designators are as follows:
+.Pp
+.Bl -tag -width 4n -offset indent -compact
+.It Sy a
+black
+.It Sy b
+red
+.It Sy c
+green
+.It Sy d
+brown
+.It Sy e
+blue
+.It Sy f
+magenta
+.It Sy g
+cyan
+.It Sy h
+light grey
+.It Sy A
+bold black, usually shows up as dark grey
+.It Sy B
+bold red
+.It Sy C
+bold green
+.It Sy D
+bold brown, usually shows up as yellow
+.It Sy E
+bold blue
+.It Sy F
+bold magenta
+.It Sy G
+bold cyan
+.It Sy H
+bold light grey; looks like bright white
+.It Sy x
+default foreground or background
+.El
+.Pp
+Note that the above are standard
+\*[Ai]
+colors.
+The actual display may differ
+depending on the color capabilities of the terminal in use.
+.Pp
+The order of the attributes are as follows:
+.Pp
+.Bl -enum -offset indent -compact
+.It
+directory
+.It
+symbolic link
+.It
+socket
+.It
+pipe
+.It
+executable
+.It
+block special
+.It
+character special
+.It
+executable with setuid bit set
+.It
+executable with setgid bit set
+.It
+directory writable to others, with sticky bit
+.It
+directory writable to others, without sticky bit
+.El
+.Pp
+The default is
+.Qq exfxcxdxbxegedabagacad ,
+i.e., blue foreground and
+default background for regular directories, black foreground and red
+background for setuid executables, etc.
+.It Ev TERM
+The
+.Ev CLICOLOR
+functionality depends on a terminal type with color capabilities.
 .It Ev TZ
 The time zone to use when displaying dates.
 See
@@ -445,24 +582,25 @@ for more information.
 .Sh EXAMPLES
 List the contents of the current working directory in long format:
 .Pp
-.Dl $ ls -l
+.Dl $ colorls -l
 .Pp
 In addition to listing the contents of the current working directory in
 long format, show inode numbers, file flags (see
 .Xr chflags 1 ) ,
 and suffix each filename with a symbol representing its file type:
 .Pp
-.Dl $ ls -lioF
+.Dl $ colorls -lioF
 .Pp
 List the files in
 .Pa /var/log ,
 sorting the output such that the mostly recently modified entries are
 printed first:
 .Pp
-.Dl $ ls -lt /var/log
+.Dl $ colorls -lt /var/log
 .Sh SEE ALSO
 .Xr chflags 1 ,
 .Xr chmod 1 ,
+.Xr termcap 5 ,
 .Xr symlink 7 ,
 .Xr sticky 8
 .Sh STANDARDS
@@ -492,6 +630,6 @@ flag differs between this implementation and
 .St -p1003.1-2004 .
 .Sh HISTORY
 An
-.Nm
+.Nm ls
 utility appeared in
 .At v3 .