ls

list directory contents

Reordered and tersified by DGerman

10.1 ls: List directory contents

lists information about files and directories

For 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 just the name.
With no arguments operates on the current directory, as if invoked with a ..

By default, the output is sorted alphabetically, according to the locale settings in effect.
(1) If stdout is a terminal, the output is in columns (sorted vertically) and control characters are output as question marks
Not to a termoinal the output is listed one per line and control characters are output as-is.
See *Note Common options

  1. Which files
  2. What information
  3. Sorting
  4. version sort
  5. output formatting
  6. timestamps
  7. names
(1) With non-POSIX locale (e.g., by setting LC_ALL to en_US, output that is sorted differently To change the sorting set $LC_ALL to C.

10.1.1 Which files are listed

Default: any files, directories and the contents of any directories on the command line are shown except those beginning with a dot('.')

-a
--all List all files and directories , including those that start with ..
-A
--almost-all List all files and directories in directories except for . and .. (Current directory and parent).
-B
--ignore-backups Do not list files that end with ~, unless they are given on the command line. These are usually created by editors like vi.
-d
--directory List just the names of directories, as with other types of files, rather than listing their contents. Do not follow symbolic links listed on the command line unless the --dereference-command-line -H, --dereference -L, or --dereference-command-line-symlink-to-dir options are specified.
-H
--dereference-command-line If a command line argument specifies a symbolic link, show information for the file the link references rather than for the link itself.
--dereference-command-line-symlink-to-dir Do not dereference symbolic links Unless a command line argument specifies a symbolic link that refers to a directory, show information for that directory rather than for the link itself.
This is the default behavior when no other dereferencing-related option has been specified --classify -F, --directory -d, -l, --dereference -L, or --dereference-command-line -H).
-I pattern
--ignore=PATTERN		 Ignore files whose names match the shell pattern(not regular expression) unless they are on the command line.
A filename with initial dot . does not match a wildcard at the start of PATTERN. This option may be used several times. For example: 
          $ ls --ignore=.??* --ignore=.[^.] --ignore='#*'
The first option ignores names of 3 or more characters starting with .,
the second ignores all 2 character names that start with . except .. the third ignores names that start with #.
-L
--dereference		show information for the file a symbolic link references rather than the link itself.
The name of the link itself is output sic, not the target.
-R
--recursiveList directories recursively.

10.1.2 What information is listed,

These options affect the information that ls displays. By default, only file names are shown.

--author List each file's author (not owner) when producing long format directory listings.
In GNU/Hurd, file authors can differ from their owners,
-D
--dired		 With -l , output an additional line 
          //DIRED// nbeg1 nend1 BEG2 END2 ...
nbegn and mnendn are the position of the beginning and end of each file name in the output. Useful with Emacs to find the names

directories listed recursively output a line with offsets for each subdirectory name: 

 //SUBDIRED// nbeg1 nend1 …
Output a line of the form: 
 //DIRED-OPTIONS// --quoting-style=style
where style is the quoting style (*note Formatting the file names::).

Example: 

          $ mkdir -p a/sub/deeper a/sub2
          $ touch a/f1 a/f2
          $ touch a/sub/deeper/file
          $ ls -gloRF --dired a
            a:
            total 8
            -rw-r--r--  1    0 Dec  3 00:50 f1
            -rw-r--r--  1    0 Dec  3 00:50 f2
            drwxr-xr-x  3 4096 Dec  3 00:50 sub/
            drwxr-xr-x  2 4096 Dec  3 00:50 sub2/
12345678911234567892123456789312345678941234567895
            a/sub:
            total 4
            drwxr-xr-x  2 4096 Dec  3 00:50 deeper/

            a/sub/deeper:
            total 0
            -rw-r--r--  1 0 Dec  3 00:50 file

            a/sub2:
            total 0
                       1    2      3       4       5       6
          //DIRED// 49 51 86 88 123 126 162 166 222 228 288 292
          //SUBDIRED// 2 3 171 176 233 245 296 302
          //DIRED-OPTIONS// --quoting-style=literal
The pairs of offsets on //DIRED// delimit : f1, f2, sub, sub2, deeper, file.
The offsets on //SUBDIRED// delimit directories : a, a/sub, a/sub/deeper, a/sub2. To extract the fifth name, deeper, with the offsets, 222 and 228: 
 
          $ ls -gloRF --dired a > out
          $ dd bs=1 skip=222 count=6 < out 2>dd.err echo deeper
Offsets select the name without the trailing slash.
With an option like --escape (aka -b a file whose name contains special characters, the backslash is include. $ touch 'a b' $ ls -blog --dired 'a b' -rw-r--r-- 1 0 Dec 3 00:52 a\ b //DIRED// 31 35 //DIRED-OPTIONS// --quoting-style=escape Using a quoting style that adds quotes (e.g., --quoting-style=c, the offsets include the quotes .
The quoting style may be specified using $QUOTING_STYLE. Is overridden using --quoting-style=literal (aka -N or --literal on the command line,
--full-time Produce long format directory listings with times in full. Equivalent to --format=long with --time-style=full-iso (*Formatting file timestamps::).
-g Supress owner
-G
--no-group		 Supress group
-h
--human-readable		 Append a size letter to each size, such as M for mebibytes. Powers of 1024 are used, ; M stands for 1,048,576 bytes.
--si Uses powers of 1000.
-i
--inode		 Include the inode number .
-l
--format=long
--format=verbose include file type, permissions, number of hard links, owner , group , size, and modification time. (*note Formatting file timestamps::)
size is a byte count (*note Block size::).
For example, -h outputs an abbreviated, human-readable count.
--block-size="'1" outputs a byte count with the thousands separator

Directories are prefaced with a line total BLOCKS, where BLOCKS is the total disk allocation for all files in that directory. permissions listed are similar to symbolic mode specifications (*note Symbolic Modes::). multiple bits are combined into the third character of each set of permissions:

sStTx-
setuid or setgid bit and the corresponding executable bit are both set.
setuid or setgid bit is set but the corresponding executable bit is not set.
sticky bit and the other-executable bit are both set.
sticky bit is set but the other-executable bit is not set.
executable bit is set and none of the above apply.
executable bit is not set
the permissions a character that specifies if an alternate access method applies to the file.
a space: no alternate access method.
a printing character (e.g., +, there is an alternate method.
-n
--numeric-uid-gid		 display numeric UIDs and GIDs
-o suoress group
-s --size Include the disk allocation to the left of the name in units of 1024 bytes, NFS-mounted from an HP-UX system to a BSD system, reports half the correct size
On HP-UX systems, twice the size
--si Append an SI-style (Powers of 1000 ) abbreviation to each size, such as MB for megabytes. , ; MB for 1,000,000 bytes. Equivalent to --block-size=si.

10.1.3 Sorting the output

These options change the order in which ls sorts the information it outputs. default sorting is done by character code (e.g., ASCII order).

-t
--sort=time		 Sort by modification time (mtime ), newest first.
-c
--time=ctime
--time=status
--time=use With code>-o output the status change time (ctime ) With --sort=time or -t sort according to the status change time.
-u
--time=atime
--time=access
WIth long format, output the last access time (atime ).
When explicitly sorting by time --sort=time or -t sort according to the access time.
-U
--sort=none		 Do not sort; list the files in order they are stored in the directory. (Do not do other unrelated things that -f does.)
-f list the files in the order they are stored in the directory.
Enable -a (list all files) and disable -l, --color, and -s (if specified before the -f.
-S
--sort=size		 Sort by size, largest first.
-v
--sort=version Sort by version name and number, lowest first.
A sequence of digits is treated numerically as an index/version number. (*Note More details about version sort::.)
-X
--sort=extension		 file extension
-r
--reverse		 Reverse the sorting method

10.1.4 More details about version sort

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 addresses 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
This functionality is implemented using the strverscmp function. *Note String/Array Comparison: (libc)String/Array Comparison. One result of that implementation decision is that ls -v does not use the locale category, LC_COLLATE. As a result, non-numeric prefixes are sorted as if LC_COLLATE were set to C. 10.1.5 General output formatting 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. Piping a colorized listing through a pager like more or less usually produces unreadable results. However, using more -f does seem to work.
-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. Do not follow symbolic links listed on the command line unless the --dereference-command-line -H, --dereference -L, or --dereference-command-line-symlink-to-dir options are specified.
--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 Print file sizes in 1024-byte blocks, overriding the default block size (*note Block size::). This option is equivalent to --block-size=1K.
-m
--format=commas List files horizontally, with as many as will fit on each line, separated by , (a comma and a space).
-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.
10.1.6 Formatting file timestamps By default, file timestamps are listed in abbreviated form. Most locales use a timestamp like 2002-03-30 23:45. However, the default POSIX locale uses a date like Mar 30 2002 for non-recent timestamps, and a date-without-year and time like Mar 30 23:45 for recent timestamps. A timestamp is considered to be "recent" if it is less than six months old, and is not dated in the future. If a timestamp dated today is not listed in recent form, the timestamp is in the future, which means you probably have clock skew problems which may break programs like make that rely on file timestamps.

The following option changes how file timestamps are printed.

--time-style=STYLE List timestamps in style STYLE. The STYLE should be one of the following:
+FORMAT List timestamps using FORMAT, the format argument of date (*note date invocation::).
For example, --time-style="+%Y-%m-%d %H:%M:%S" causes ls to list timestamps like 2002-03-30 23:45:56. As with date,
FORMAT's interpretation is affected by the LC_TIME locale category.
If FORMAT contains two format strings separated by a newline, the former is used for non-recent files and the latter for recent files;
full-iso List timestamps in full using ISO 8601 date, time, and time zone format with nanosecond precision, e.g., 2002-03-30 23:45:56.477817180 -0700.
E quivalent to: +%Y-%m-%d %H:%M:%S.%N %z.
long-iso List ISO 8601 date and time in minutes, e.g., 2002-03-30 23:45. These timestamps are shorter than full-iso timestamps,
This style is equivalent to %Y-%m-%d %H:%M.
iso List ISO 8601 dates for non-recent timestamps (e.g., 2002-03-30 , and month, day, hour, and minute for recent timestamps (e.g., 03-30 23:45.
The following two are equivalent: 
 newline=
 ls -l --time-style="+%Y-%m-%d $newline%m-%d %H:%M"
 ls -l --time-style="iso"
locale List timestamps in a locale-dependent form. For example, a Finnish locale might list non-recent timestamps like maalis 30 2002 and recent timestamps like maalis 30 23:45.
$LC_TIME locale specifies the timestamp format. The default POSIX locale uses timestamps like Mar 30 2002 and Mar 30 23:45' in this locale, the following two are equivalent: newline= 
 ls -l --time-style="+%b %e  %Y$newline%b %e %H:%M"
 ls -l --time-style="locale"
Other locales behave differently. For example, in a German locale, --time-style="locale" might be equivalent to --time-style="+%e. %b %Y $newline%e. %b %H:%M" and might generate timestamps like 30. Ma"r 2002 and 30. Ma"r 23:45.
posix-STYLE List POSIX-locale timestamps if $LC_TIME category is POSIX, STYLE timestamps otherwise. For example, the default style, which is posix-long-iso, lists timestamps like Mar 30 2002 and Mar 30 23:45 when in the POSIX locale, and like 2002-03-30 23:45 otherwise.
Specify the default value of the --time-style with $TIME_STYLE';
Default style is posix-long-iso.

10.1.7 Formatting the file names

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
--quoting-style=literal Do not quote file names.
-q
--hide-control-chars output question marks for nongraphic characters .
default if the output is a terminal and the program is ls.
-Q
--quote-name
--quoting-style=c Enclose file names in quotes (") and nongraphic characters as in C.
--quoting-style=style Use style to quote file names and other strings that may contain arbitrary characters. one of
literal Output strings as-is; this is the same as the -N or --literal option.
shell Quote strings for the shell if they contain shell metacharacters or would cause ambiguous output. The quoting is suitable for POSIX-compatible shells like bash, but it does not always work for incompatible shells like csh.
shell-always Quote strings for the shell, even if they would normally not require quoting.
c Quote strings as for C character string literals, including the surrounding double-quote characters; this is the same as the -Q or --quote-name option.
escape Quote strings as for C character string literals, except omit the surrounding double-quote characters; this is the same as the -b or --escape option.
clocale Quote strings as for C character string literals, except use surrounding quotation marks appropriate for the locale.
locale Quote strings as for C character string literals, except use surrounding quotation marks appropriate for the locale, and quote like this instead of "like this" in the default C locale.
specify the default value of the --quoting-style option with $QUOTING_STYLE.
the default literal,
--show-control-chars output nongraphic characters as-is ,br> default unless the output is a terminal and the program is ls.

copyright 2006-2007 phpman.info | contact: admin at phpman.info

PHPMan.info