Go to the first, previous, next, last section, table of contents.
This chapter describes the ls
command and its variants dir
and vdir
, which list information about files.
The ls
program lists information about files (of any type,
including directories). Options and file arguments can be intermixed
arbitrarily, as usual.
For non-option command-line arguments that are directories, by default
ls
lists the contents of directories, not recursively, and
omitting files with names beginning with .
. For other non-option
arguments, by default ls
lists just the file name. If no
non-option arguments are specified, ls
lists the contents of the
current directory.
By default, the output is sorted alphabetically. If standard output is
a terminal, the output is in columns (sorted vertically) and control
characters are output as question marks; otherwise, the output is listed
one per line and control characters are output as-is.
Because ls
is such a fundamental program, it has accumulated many
options over the years. They are described in the subsections below;
within each section, options are listed alphabetically (ignoring case).
The division of options into the subsections is not absolute, since some
options affect more than one aspect of ls
's operation.
The `-g' option is accepted but ignored, for compatibility
with Unix. Also see section 2. Common options.
These options determine which files ls
lists information for.
By default, any files and the contents of any directories on the command
line are shown.
- `-a'
-
- `--all'
-
List all files in directories, including files that start with `.'.
- `-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.
- `-d'
-
- `--directory'
-
List just the names of directories, as with other types of files, rather
than listing their contents.
- `-I PATTERN'
-
- `--ignore=PATTERN'
-
Do not list files whose names match the shell pattern (not regular
expression) pattern unless they are given on the command line. As
in the shell, an initial `.' in a file name does not match a
wildcard at the start of pattern. Sometimes it is useful
to give this option several times. For example,
$ ls --ignore='.??*' --ignore='.[^.]' --ignore='#*'
The first option ignores names of length 3 or more that start with `.',
the second ignores all two-character names that start with `.'
except `..', and the third ignores names that start with `#'.
- `-L'
-
- `--dereference'
-
In a long listing, show file information (e.g., times and permissions)
for the referents of symbolic links rather than for the symbolic links
themselves.
- `-R'
-
- `--recursive'
-
List the contents of all directories recursively.
These options affect the information that ls
displays. By
default, only file names are shown.
- `-D'
-
- `--dired'
-
With the long listing (`-l') format, print an additional line after
the main output:
//DIRED// beg1 end1 beg2 end2 ...
The begN and endN are unsigned integers that record the
byte position of the beginning and end of each file name in the output.
This makes it easy for Emacs to find the names, even when they contain
unusual characters such as space or newline, without fancy searching.
If directories are being listed recursively (-R
), output a similar
line after each subdirectory:
//SUBDIRED// format beg1 end1 ...
Finally, output a line of the form:
//DIRED-OPTIONS// --quoting-style=word
where word is the quoting style (see section 5.1.6 Formatting the file names).
- `-G'
-
- `--no-group'
-
Inhibit display of group information in a long format directory listing.
(This is the default in some non-GNU versions of
ls
, so we
provide this option for compatibility.)
- `-h'
-
- `--human-readable'
-
Append a size letter such as `M' for megabytes to each size.
Powers of 1024 are used, not 1000; `M' stands for 1,048,576 bytes.
Use the `-H' or `--si' option if you prefer powers of 1000.
- `-H'
-
- `--si'
-
Append a size letter such as `M' for megabytes to each size. (SI
is the International System of Units, which defines these letters as
prefixes.) Powers of 1000 are used, not 1024; `M' stands for
1,000,000 bytes. Use the `-h' or `--human-readable' option if
you prefer powers of 1024.
- `-i'
-
- `--inode'
-
Print the inode number (also called the file serial number and index
number) of each file to the left of the file name. (This number
uniquely identifies each file within a particular filesystem.)
- `-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 (by default, the modification time). For files with a time
more than six months old or more than one hour into the future, the
timestamp contains the year instead of the time of day.
For each directory that is listed, preface the files with a line
`total blocks', where blocks is the total disk allocation
for all files in that directory. The block size currently defaults to 1024
bytes, but this can be overridden (see section 2.2 Block size).
The blocks computed counts each hard link separately;
this is arguably a deficiency.
The permissions listed are similar to symbolic mode specifications
(see section 3.2 Symbolic Modes). But
ls
combines multiple bits into the
third character of each set of permissions as follows:
- `s'
-
If the setuid or setgid bit and the corresponding executable bit
are both set.
- `S'
-
If the setuid or setgid bit is set but the corresponding executable bit
is not set.
- `t'
-
If the sticky bit and the other-executable bit are both set.
- `T'
-
If the sticky bit is set but the other-executable bit is not set.
- `x'
-
If the executable bit is set and none of the above apply.
- `-'
-
Otherwise.
- `-o'
-
Produce long format directory listings, but don't display group information.
It is equivalent to using `--format=long' with `--no-group' .
This option is provided for compatibility with other versions of
ls
.
- `-s'
-
- `--size'
-
Print the disk allocation of each file to the left of the file name.
This is the amount of disk space used by the file, which is usually a
bit more than the file's size, but it can be less if the file has holes.
Normally the disk allocation is printed in units of
1024 bytes, but this can be overridden (see section 2.2 Block size).
For files that are NFS-mounted from an HP-UX system to a BSD system,
this option reports sizes that are half the correct values. 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.
These options change the order in which ls
sorts the information
it outputs. By default, sorting is done by character code (e.g., ASCII
order).
- `-c'
-
Sort according to the status change time (the `ctime' in the
inode). If the long listing format (`-l') is being used, print the
status change time instead of the modification time.
- `-f'
-
Primarily, like `-U'---do not sort; list the files in whatever
order they are stored in the directory. But also enable `-a' (list
all files) and disable `-l', `--color', and `-s' (if they
were specified before the `-f').
- `-r'
-
- `--reverse'
-
Reverse whatever the sorting method is--e.g., list files in reverse
alphabetical order, youngest first, smallest first, or whatever.
- `-S'
-
- `--sort=size'
-
Sort by file size, largest first.
- `-t'
-
- `--sort=time'
-
Sort by modification time (the `mtime' in the inode), newest first.
- `-u'
-
Sort by access time (the `atime' in the inode). If the long
listing format is being used, print the last access time.
- `--time=atime'
-
- `--time=access'
-
When used with `--sort=time' (`-t'), this is equivalent to `-u'.
With options that print times (e.g., `--format=long'), print each file's
time of last access, rather than its time of last modification.
- `--time=ctime'
-
- `--time=status'
-
- `--time=use'
-
When used with `--sort=time' (`-t'), this is equivalent to `-c'.
With options that print times (e.g., `--format=long'), print each file's
time of last inode change, rather than its time of last modification.
- `-U'
-
- `--sort=none'
-
Do not sort; list the files in whatever order they are
stored in the directory. (Do not do any of the other unrelated things
that `-f' does.) This is especially useful when listing very large
directories, since not doing any sorting can be noticeably faster.
- `-v'
-
- `--sort=version'
-
Sort by version name and number, lowest first. It behaves like a default
sort, excepted that each sequence of decimal digits is treated numericaly
as an index/version number. (See section 5.1.4 More details about version sort.)
- `-X'
-
- `--sort=extension'
-
Sort directory contents alphabetically by file extension (characters
after the last `.'); files with no extension are sorted first.
The version sort takes into account the fact that file names frequently include
indices or version numbers. Standard sorting functions usually do not produce
the ordering that people expect because comparisons are made on a
character-by-character basis. The version
sort adresses this problem, and is especially useful when browsing
directories that contain many files with indices/version numbers in their
names:
> ls -1 > ls -1v
foo.zml-1.gz foo.zml-1.gz
foo.zml-100.gz foo.zml-2.gz
foo.zml-12.gz foo.zml-6.gz
foo.zml-13.gz foo.zml-12.gz
foo.zml-2.gz foo.zml-13.gz
foo.zml-25.gz foo.zml-25.gz
foo.zml-6.gz foo.zml-100.gz
Note also that numeric parts with leading zeroes are considered as
fractional one:
> ls -1 > ls -1v
abc-1.007.tgz abc-1.007.tgz
abc-1.012b.tgz abc-1.01a.tgz
abc-1.01a.tgz abc-1.012b.tgz
These options affect the appearance of the overall output.
- `-1'
-
- `--format=single-column'
-
List one file per line. This is the default for
ls
when standard
output is not a terminal.
- `-C'
-
- `--format=vertical'
-
List files in columns, sorted vertically. This is the default for
ls
if standard output is a terminal. It is always the default
for the dir
and d
programs.
GNU ls
uses variable width columns to display as many files as
possible in the fewest lines.
- `--color [=when]'
-
Specify whether to use color for distinguishing file types. when
may be omitted, or one of:
- none
Do not use color at all. This is the default.
- auto
Only use color if standard output is a terminal.
- always
Always use color.
Specifying `--color' and no when is equivalent to
`--color=always'.
- `-F'
-
- `--classify'
-
- `--indicator-style=classify'
-
Append a character to each file name indicating the file type. Also,
for regular files that are executable, append `*'. The file type
indicators are `/' for directories, `@' for symbolic links,
`|' for FIFOs, `=' for sockets, and nothing for regular files.
- `--full-time'
-
List times in full, rather than using the standard abbreviation
heuristics. The format is the same as
date
's default; it's not
possible to change this, but you can extract out the date string with
cut
and then pass the result to date -d
. See section `date invocation' in Shell utilities.
This is most useful because the time output includes the seconds. (Unix
filesystems store file timestamps only to the nearest second, so this
option shows all the information there is.) For example, this can help
when you have a Makefile that is not regenerating files properly.
- `--indicator-style=word'
-
Append a character indicator with style word to entry names,
as follows:
- `none'
-
Do not append any character indicator; this is the default.
- `file-type'
-
Append `/' for directories, `@' for symbolic links, `|'
for FIFOs, `=' for sockets, and nothing for regular files. This is
the same as the `-p' or `--file-type' option.
- `classify'
-
Append `*' for executable regular files, otherwise behave as for
`file-type'. This is the same as the `-F' or
`--classify' option.
- `-k'
-
- `--kilobytes'
-
Print file sizes in 1024-byte blocks, overriding the default block
size (see section 2.2 Block size).
- `-m'
-
- `--format=commas'
-
List files horizontally, with as many as will fit on each line,
separated by `, ' (a comma and a space).
- `-n'
-
- `--numeric-uid-gid'
-
List the numeric UID and GID instead of the names.
- `-p'
-
- `--file-type'
-
- `--indicator-style=file-type'
-
Append a character to each file name indicating the file type. This is
like `-F', except that executables are not marked.
- `-x format'
-
- `--format=across'
-
- `--format=horizontal'
-
List the files in columns, sorted horizontally.
- `-T cols'
-
- `--tabsize=cols'
-
Assume that each tabstop is cols columns wide. The default is 8.
ls
uses tabs where possible in the output, for efficiency. If
cols is zero, do not use tabs at all.
- `-w'
-
- `--width=cols'
-
Assume the screen is cols columns wide. The default is taken
from the terminal settings if possible; otherwise the environment
variable
COLUMNS
is used if it is set; otherwise the default
is 80.
These options change how file names themselves are printed.
- `-b'
-
- `--escape'
-
- `--quoting-style=escape'
-
Quote nongraphic characters in file names using alphabetic and octal
backslash sequences like those used in C.
- `-N'
-
- `--literal'
-
Do not quote file names.
- `-q'
-
- `--hide-control-chars'
-
Print question marks instead of nongraphic characters in file names.
This is the default if the output is a terminal and the program is
ls
.
- `-Q'
-
- `--quote-name'
-
- `--quoting-style=c'
-
Enclose file names in double quotes and quote nongraphic characters as
in C.
- `--quoting-style=word'
-
Use style word to quote output names. The word should
be one of the following:
- `literal'
-
Output names as-is.
- `shell'
-
Quote names for the shell if they contain shell metacharacters or would
cause ambiguous output.
- `shell-always'
-
Quote names for the shell, even if they would normally not require quoting.
- `c'
-
Quote names as for a C language string; this is the same as the
`-Q' or `--quote-name' option.
- `escape'
-
Quote as with `c' except omit the surrounding double-quote
characters; this is the same as the `-b' or `--escape' option.
You can specify the default value of the `--quoting-style' option
with the environment variable QUOTING_STYLE
. If that environment
variable is not set, the default value is `literal', but this
default may change to `shell' in a future version of this package.
- `--show-control-chars'
-
Print nongraphic characters as-is in file names.
This is the default unless the output is a terminal and the program is
ls
.
dir
(also installed as d
) is equivalent to ls -C
-b
; that is, by default files are listed in columns, sorted vertically,
and special characters are represented by backslash escape sequences.
See section 5.1 ls
: List directory contents.
vdir
(also installed as v
) is equivalent to ls -l
-b
; that is, by default files are listed in long format and special
characters are represented by backslash escape sequences.
dircolors
outputs a sequence of shell commands to set up the
terminal for color output from ls
(and dir
, etc.).
Typical usage:
eval `dircolors [option]... [file]`
If file is specified, 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 `dircolors --print-database'.
The output is a shell command to set the LS_COLORS
environment
variable. You can specify the shell syntax to use on the command line,
or dircolors
will guess it from the value of the SHELL
environment variable.
The program accepts the following options. Also see section 2. Common options.
- `-b'
-
- `--sh'
-
- `--bourne-shell'
-
Output Bourne shell commands. This is the default if the
SHELL
environment variable is set and does not end with `csh' or
`tcsh'.
- `-c'
-
- `--csh'
-
- `--c-shell'
-
Output C shell commands. This is the default if
SHELL
ends with
csh
or tcsh
.
- `-p'
-
- `--print-database'
-
Print the (compiled-in) default color configuration database. This
output is itself a valid configuration file, and is fairly descriptive
of the possibilities.
Go to the first, previous, next, last section, table of contents.