Table of Contents
ls, dir, vdir - list contents of directories
ls [-abcdfgiklmnpqrstuxABCFGLNQRSUX1] [-w cols] [-T cols]
[-I pattern] [--all] [--escape] [--directory] [--inode]
[--kilobytes] [--numeric-uid-gid] [--no-group] [--hidecontrol-chars]
[--reverse] [--size] [--width=cols]
[--tabsize=cols] [--almost-all] [--ignore-backups] [--classify]
[--file-type] [--full-time] [--ignore=pattern]
[--dereference] [--literal] [--quote-name] [--recursive]
[--sort={none,time,size,extension}]
[--format={long,verbose,commas,across,vertical,singlecolumn}]
[--time={atime,access,use,ctime,status}] [--help]
- [--version]
- [--color[={yes,no,tty}]]
[--colour[={yes,no,tty}]] [name...]
This documentation is no longer being maintained and may be
inaccurate or incomplete. The Texinfo documentation is now
the authoritative source.
This manual page documents the GNU version of ls. dir and
vdir are versions of ls with different default output formats.
These programs list each given file or directory
name. Directory contents are sorted alphabetically. For
ls, files are by default listed in columns, sorted vertically,
if the standard output is a terminal; otherwise they
are listed one per line. For dir, files are by default
listed in columns, sorted vertically. For vdir, files are
by default listed in long format.
OPTIONS
-a, --all
List all files in directories, including all files that
start with `.'.
- -b, --escape
-
Quote nongraphic characters in file names using alphabetic
and octal backslash sequences like those used in
C.
- -c, --time=ctime, --time=status
-
Sort directory contents according to the files' status
change time instead of the modification time. If the
long listing format is being used, print the status
change time instead of the modification time.
- -d, --directory
-
List directories like other files, rather than listing
their contents.
- -f
- Do not sort directory contents; list them in whatever
order they are stored on the disk. The same as enabling
-a and -U and disabling -l, -s, and -t.
- --full-time
-
List times in full, rather than using the standard
abbreviation heuristics.
- -g
- Ignored; for Unix compatibility.
- -i, --inode
-
Print the index number of each file to the left of the
file name.
- -k, --kilobytes
-
If file sizes are being listed, print them in kilobytes.
This overrides the environment variable
POSIXLY_CORRECT.
- -l, --format=long, --format=verbose
-
In addition to the name of each file, print the file
type, permissions, number of hard links, owner name,
group name, size in bytes, and timestamp (the modification
time unless other times are selected). For files
with a time that is more than 6 months old or more than
1 hour into the future, the timestamp contains the year
instead of the time of day.
- -m, --format=commas
-
List files horizontally, with as many as will fit on
each line, separated by commas.
- -n, --numeric-uid-gid
-
List the numeric UID and GID instead of the names.
- -p
- Append a character to each file name indicating the
file type.
- -q, --hide-control-chars
-
Print question marks instead of nongraphic characters
in file names.
- -r, --reverse
-
Sort directory contents in reverse order.
- -s, --size
-
Print the size of each file in 1K blocks to the left of
the file name. If the environment variable
POSIXLY_CORRECT is set, 512-byte blocks are used
instead.
- -t, --sort=time
-
Sort directory contents by timestamp instead of alphabetically,
with the newest files listed first.
- -u, --time=atime, --time=access, --time=use
-
Sort directory contents according to the files' last
access time instead of the modification time. If the
long listing format is being used, print the last
access time instead of the modification time.
- -x, --format=across, --format=horizontal
-
List the files in columns, sorted horizontally.
- -A, --almost-all
-
List all files in directories, except for `.' and `..'.
- -B, --ignore-backups
-
Do not list files that end with `~', unless they are
given on the command line.
- -C, --format=vertical
-
List files in columns, sorted vertically.
- -F, --classify
-
Append a character to each file name indicating the
file type. For regular files that are executable,
append a `*'. The file type indicators are `/' for
directories, `@' for symbolic links, `|' for FIFOs, `='
for sockets, and nothing for regular files.
- -G, --no-group
-
Inhibit display of group information in a long format
directory listing.
- -L, --dereference
-
List the files linked to by symbolic links instead of
listing the contents of the links.
- -N, --literal
-
Do not quote file names.
- -Q, --quote-name
-
Enclose file names in double quotes and quote nongraphic
characters as in C.
- -R, --recursive
-
List the contents of all directories recursively.
- -S, --sort=size
-
Sort directory contents by file size instead of alphabetically,
with the largest files listed first.
- -U, --sort=none
-
Do not sort directory contents; list them in whatever
order they are stored on the disk. This option is not
called -f because the Unix ls -f option also enables -a
and disables -l, -s, and -t. It seems useless and ugly
to group those unrelated things together in one option.
Since this option doesn't do that, it has a different
name.
- -X, --sort=extension
-
Sort directory contents alphabetically by file extension
(characters after the last `.'); files with no
extension are sorted first.
- -1, --format=single-column
-
List one file per line.
- -w, --width cols
-
Assume the screen is cols columns wide. The default is
taken from the terminal driver if possible; otherwise
the environment variable COLUMNS is used if it is set;
otherwise the default is 80.
- -T, --tabsize cols
-
Assume that each tabstop is cols columns wide. The
default is 8.
- -I, --ignore pattern
-
Do not list files whose names match the shell pattern
pattern unless they are given on the command line. As
in the shell, an initial `.' in a filename does not
match a wildcard at the start of pattern.
- --color, --colour, --color=yes, --colour=yes
-
Colorize the names of files depending on the type of
file. See DISPLAY COLORIZATION below.
- --color=tty, --colour=tty
-
Same as --color but only if standard output is a terminal.
This is very useful for shell scripts and command
aliases, especially if your favorite pager does not
support color control codes.
- --color=no, --colour=no
-
Disables colorization. This is the default. Provided
to override a previous color option.
- --help
-
Print a usage message on standard output and exit successfully.
- --version
-
Print version information on standard output then exit
successfully.
DISPLAY COLORIZATION
When using the --color option, this version of ls will
colorize the file names printed according to the name and
type of file. By default, this colorization is by type
only, and the codes used are ISO 6429 (ANSI) compliant.
You can override the default colors by defining the environment
variable LS_COLORS (or LS_COLOURS). The format of this
variable is reminicent of the termcap(5) file format; a
colon-separated list of expressions of the form "xx=string",
where "xx" is a two-character variable name. The variables
with their associated defaults are:
- no
- 0 Normal (non-filename) text
- fi
- 0 Regular file
di 32 Directory
- ln
- 36 Symbolic link
- pi
- 31 Named pipe (FIFO)
so 33 Socket
- bd
- 44;37 Block device
- cd
- 44;37 Character device
- ex
- 35 Executable file
- mi
- (none) Missing file (defaults to fi)
- or
- (none) Orphanned symbolic link (defaults to ln)
- lc
- \e[ Left code
- rc
- m Right code
- ec
- (none) End code (replaces lc+no+rc)
You only need to include the variables you want to change
from the default.
File names can also be colorized based on filename extension.
This is specified in the LS_COLORS variable using the
syntax "*ext=string". For example, using ISO 6429 codes, to
color all C-language source files blue you would specify
"*.c=34". This would color all files ending in .c in blue
(34) color.
Control characters can be written either in C-style \escaped
notation, or in stty-like ^-notation. The C-style
notation adds \e for Escape, \_ for a normal space characer,
and \? for Delete. In addition, the \ escape character can
be used to override the default interpretation of \, ^, :
and =.
Each file will be written as <lc> <color code> <rc>
<filename> <ec>. If the <ec> code is undefined, the
sequence <lc> <no> <rc> will be used instead. This is generally
more convenient to use, but less general. The left,
right and end codes are provided so you don't have to type
common parts over and over again and to support weird terminals;
you will generally not need to change them at all
unless your terminal does not use ISO 6429 color sequences
but a different system.
If your terminal does use ISO 6429 color codes, you can compose
the type codes (i.e. all except the lc, rc, and ec
codes) from numerical commands separated by semicolons. The
most common commands are:
- 0
- to restore default color
- 1
- for brighter colors
- 4
- for underlined text
- 5
- for flashing text
- 30
- for black foreground
- 31
- for red foreground
- 32
- for green foreground
- 33
- for yellow (or brown) foreground
- 34
- for blue foreground
- 35
- for purple foreground
- 36
- for cyan foreground
- 37
- for white (or gray) foreground
- 40
- for black background
- 41
- for red background
- 42
- for green background
- 43
- for yellow (or brown) background
- 44
- for blue background
- 45
- for purple background
- 46
- for cyan background
- 47
- for white (or gray) background
Not all commands will work on all systems or display devices.
A few terminal programs do not recognize the default end
code properly. If all text gets colorized after you do a
directory listing, try changing the no and fi codes from 0
to the numerical codes for your standard fore- and background
colors.
On BSD systems, the -s option reports sizes that are half
the correct values for files that are NFS-mounted from HP-UX
systems. On HP-UX systems, it reports sizes that are twice
the correct values for files that are NFS-mounted from BSD
systems. This is due to a flaw in HP-UX; it also affects
the HP-UX ls program.
If there was a single standard for the English language it
would not be necessary to support redundant spellings.
Table of Contents