ls

list directory contents

BSD options.

linux options

ls [-ABCFGHLPRTWZabcdefghiklmnopqrstuwx1] [arg …]

-- terminates options, useful when filenames begin with a -

For a file: display its name and attributes.
For a directory: displays the files in that directory and attributes.
use -d to display attributes of the directory.

If no operands are given, the contents of the current directory are displayed.
If more than one operand is given (or implied with shell pattern match),

non-directory operands are displayed first;
directory and non-directory operands are sorted separately and in lexicographical order.

no options

 Alphabetically, all UPPER CASE before lowercase, down first column, then second column ( see -x)
> /bin/ls 
RptTable.html       fixRpt.sed   makeRpt.sh        rptRows.html
archive
birdRpt.080410.sed  freq.sql     rpt.0807001.sql   tableBot.html
birdRpt.sed         index.html   rpt.sql           tableTop.html

-a

all files (include normally hidden files begining with dot (.)(usually configuration files for applications that are uninteresting (?))

> /bin/ls -a
.              .bashrc             fixRpt.sed   makeRpt.sh        rptRows.html
..             birdRpt.080410.sed  freq.sql     rpt.0807001.sql   tableBot.html
RptTable.html  birdRpt.sed         index.html   rpt.sql           tableTop.html
archve         birdRptTable.html   index.shtml  rptFix.080410.sed tmp

-A

List all entries except for . and .. current and parent (set for the super-user.)

> /bin/ls -A
RptTable.html birdRpt.080410.sed fixRpt.sed index.shtml     rpt.sql           tableBot.html
archve        birdRpt.sed        freq.sql   makeRpt.sh      rptFix.080410.sed tableTop.html
.bashrc       birdRptTable.html  index.html rpt.0807001.sql rptRows.html      tmp

-C

multi-column output with entries sorted down, the columns.default when output is to a terminal.

> ls -C
RptTable.html birdRpt.080410.sed fixRpt.sed index.shtml     rpt.sql           tableBot.html
archve        birdRpt.sed        freq.sql   makeRpt.sh      rptFix.080410.sed tableTop.html
bcols.js      birdRptTable.html  index.html rpt.0807001.sql rptRows.html      tmp

-x

multi-column output with entries sorted across

> ls -x
RptTable.html      archve          bcols.js  birdRpt.080410.sed  birdRpt.sed
birdRptTable.html  fixRpt.sed      freq.sql  index.html          index.shtml
makeRpt.sh         rpt.0807001.sql rpt.sql   rptFix.080410.sed   rptRows.html
tableBot.html      tableTop.html   tmp

-1

one entry per line. default when output is not to a terminal.

     RptTable.html
     archve
     bcols.js
     birdRpt.080410.sed
     birdRpt.sed
     birdRptTable.html
     fixRpt.sed
     freq.sql
     index.html
     index.shtml
     makeRpt.sh
     rpt.0807001.sql
     rpt.sql
     rptFix.080410.sed
     rptRows.html
     tableBot.html
     tableTop.html
     tmp

-m

Stream output format; list files across the page, separated by commas.

RptTable.html, archve, bcols.js, birdRpt.080410.sed, birdRpt.sed, birdRptTable.html, fixRpt.sed, freq.sql, index.html, index.shtml, makeRpt.sh, rpt.0807001.sql, rpt.sql, rptFix.080410.sed, rptRows.html, tableBot.html, tableTop.html, tmp

-l

long format.
If the output is to a terminal, total bbbbbb sum of file blocks is output on a line before each directory

     total 108
     -rw-r--r-- 1 dennis staff 12608 Apr 29  2008 RptTable.html
     drwxr-xr-x 2 dennis staff  4096 Sep 21 11:31 archve
     -rw-r--r-- 1 dennis staff  1582 Jun  8  2008 bcols.js
     -rw-r--r-- 1 dennis staff  1030 Jun 20  2007 birdRpt.080410.sed
     -rw-r--r-- 1 dennis staff  3123 Apr 29  2008 birdRpt.sed
     -rw-r--r-- 1 dennis staff  8676 Nov 15  2007 birdRptTable.html
     -rw-r--r-- 1 dennis staff  1130 Jun 12  2008 fixRpt.sed
     -rw-r--r-- 1 dennis staff  1461 Sep 12 09:23 freq.sql
     -rw-r--r-- 1 dennis staff   167 Mar  1  2007 index.html
     -rw-r--r-- 1 dennis staff  3148 Jan 23  2008 index.shtml
     -rwxr-xr-x 1 dennis staff  2494 Sep 14 20:16 makeRpt.sh
     -rw-r--r-- 1 dennis staff  2369 Jun 26  2008 rpt.0807001.sql
     -rw-r--r-- 1 dennis staff  5212 Sep  3  2008 rpt.sql
     -rw-r--r-- 1 dennis staff  1211 Oct  9  2007 rptFix.080410.sed
     -rw-r--r-- 1 dennis staff 15335 Nov  2 10:24 rptRows.html
     -rw-r--r-- 1 dennis staff    21 Oct  9  2007 tableBot.html
     -rw-r--r-- 1 dennis staff   640 Jun 12  2008 tableTop.html
     drwxr-xr-x 2 dennis staff  4096 Apr 30  2008 tmp

-p display / after directories

-F

include suffixes

/ directories,
* executables,
+ extended security information
(Use -@ to display that information)
@ symbolic link
(Use -@ to display that information) = socket
% whiteout
| FIFO

-G

Enable colorized output of filename. $CLICOLOR

options effecting output sorting

-f not sorted.

-S size

-t time modified before sorting by lexicographical order.
-c time of last status change -or-
-u time of last access
If file system is mounted with noatime access times are not updated.

-r reverse the order of the sort to get reverse lexicographical order or
the oldest entries first or smallest files first

-T^⌘

with -l , time always includes hour, minute, second, and year.
Without -T recent files show Mon Day hh:mm; older than 6 months show Mon Day Year.

       
    drwx------+  59 2006 Dec  7 15:18:01 2008 Downloads
    drwxr-xr-x    2   68 Dec  7 12:06:31 2008 EasyFind
    -rwxr-----    1  262 Sep 17 01:00:00 2007 FTPtest.bat
    -rwxr-----    1   67 Sep 17 01:00:00 2007 FTPtest.cmd

-e extend the display to include the Access Control List (ACL) info.

-O the file's flags in a long output. dash is displayed if no "special" flags are set.(hidden, arch, compressed, uchg, schg, append, archived, nodump, opaque, uunlink (chflg)

-o display owner (supressing group)

-g group name (supressing owner) in the long format output.

-n numeric userID and groupID

-i file's file serial number (inode number).

-k size in kilobytes, not blocks,
overrides $BLOCKSIZE.

-h

human ? sizes. With -l , use unit suffixes: Kilobyte, Megabyte, Gigabyte, Terabyte and Petabyte reducing the number of digits to three (n.m) or less (causes size not to be like a bar graph, i.e. big files have many digits)

-rw-r-----    1 dgerman  staff   354B Jul 23  2013 crontab.130723
-rw-r--r--    1 dgerman  staff   3.1K Nov 11  2008 ct
-rw-r--r--    1 dgerman  staff   3.4K Sep 16  2010 cv-100908.csv
-rw-r--r--    1 dgerman  staff    15K Oct  2  2010 cv-100916.ods

-rw-r-----    1 dgerman  staff        354 Jul 23  2013 crontab.130723
-rw-r--r--    1 dgerman  staff       3201 Nov 11  2008 ct
-rw-r--r--    1 dgerman  staff       3526 Sep 16  2010 cv-100908.csv
-rw-r--r--    1 dgerman  staff      15016 Oct  2  2010 cv-100916.ods

-s

size in blocks, important for sparse files ( ex /var/log/lastlog for which ls -l reports incorrect count .

> stat /var/log/lastlog
  File: `/var/log/lastlog'
  Size: 292292      Blocks: 32         IO Block: 4096   regular file …
>  ls -ls  /var/log/lastlog
16 -rwxrwxr-- 1 root staff 292292 Jun  7 14:38 /var/log/lastlog
> export BLOCKSIZE=4096
> ls -sl /var/log/lastlog 
4 -rwxrwxr-- 1 root staff 292292 Jun  7 14:38 /var/log/lastlog

If the output is to a terminal, total bbbbbb sum of file blocks is output on a line before each directory
$BLOCKSIZE Default 512 bytes.

-R Recursively list subdirectories

-d Directories not searched recursively.

options affecting symbolic link display

-H Symbolic links on the command line are followed. Assumed if none of -F, -d, or -l are specified.

-L If argument is a symbolic link, list the references rather than the link itself. This option cancels -P .

-P

If argument is a symbolic link, list the link

-q display non-graphic characters in file names as ?. default when output is to a terminal.

-w raw displaying of non-printable characters. default when output is not to a terminal.

-v unedited displaying of non-graphic characters; this is the default when output is not to a terminal.

-B Binary filenames ; display non-displayable characters in file names as \xxx, where xxx is the numeric value of the character in octal.

-W Display whiteouts when scanning directories.

Column formats: -1^†, -C, -x, and -l override each other; the last one specified is used.
Sort time choices: -c(change) and -u(access) override each other; the last one specified isused.
Filename display : -b As -B, but use C escape codes whenever possible.
-B, -b, -w, and -q override each other; the last one specified determines the format used for non-displayable characters.
Symbolic Links: -H, -L and-P override each other (either partially or fully); they are applied in the order specified.

Default, one entry per line to standard output; to terminals or with -C or -x (multi column formats.)

File information is displayed with blanks separating the information associated with the -i, -s, and -l options.

The Long Format

-l displays :
type, mode, number of links, owner, group, number of bytes in the file, month, day-of-month, hour, minute file last modified, and the pathname.

If the modification time of the file is more than 6 months ago, the year is displayed instead of the hour and minutes (see -T).

If the owner or group names are not known (example they have been deleted), or with -n numeric ID's are displayed.

For character special or block special files the major and minor device numbers for the file are displayed in the size field.

For symbolic links a -> and the pathname of the linked-to file is displayed

The type character describes the type of file :

- Regular file.
d Directory.
l Symbolic link.
b Block special file.
c Character special file.
s Socket link.
p FIFO.

The mode, the permssion flags, are three fields of three characters each (ex: rwxrwxr-x ) :

fields: user whos owns the file , group members , and others.

Each field has three character positions:

r the file is readable; - not readable.
w the file is writable; - not writable.
The first of the following that applies:
- S the file is not executable
  - in the owner permissions set-user-ID mode is set.
  - in the group permissions set-group-ID mode is set.
- s the file is executable
  - in the owner permissions set-user-ID mode is set.
  - If in the group permissions set-group-ID mode is set.
- x file is executable or directory is searchable.
- - file is neither readable, writable, executable, nor set-user-ID nor set-group-ID mode, nor sticky.
  These next two apply only to the third character in the last field (other permissions).
- T sticky bit is set (mode 1000), but not execute or search permission.
- t sticky bit is set (mode 1000), and is searchable or executable. (See chmod or sticky for more details)
- + the file or directory has Access Control List attributes. (See chmod ACL
- @ the file or directory has extended attributes xattr.( on Apple Mac, Darwin BSD chmod) may have beed saved from an email attachment by Thunderbird.
  ls -l@
  drwxr-xr-x@ 12 dgerman staff 408 Oct 8 12:14 morse
  com.apple.quarantine 46
  
  This can be deleted using xattr
  xattr -d com.apple.quarantine morse

total nnnnnn number of 512-byte blocks used by the files in the directory is displayed on a line by itself before the files.
EXAMPLES
Sort by size (and shows why ls does not need a separate option for this):

ls -l | sort -n +4

-r reverse sort order.

exits 0 on success, and >0 if an error occurs.

ENVIRONMENT variables

$BLOCKSIZE

default is 512.

CLICOLOR Use ANSI color sequences to distinguish file types. See LSCOLORS.
In addition to the file types mentioned in -F^†, extra attributes (setuid etc.) are displayed.
See termcap(5). in an xterm, $TERM may be set to xterm‑color. Other terminal types may require similar adjustments.
Disabled if the output isn't directed to a terminal unless $CLICOLOR_FORCE is defined.

CLICOLOR_FORCE

if set, color sequences are output even if not directed to a terminal.

LSCOLORS

colors used when enabled with CLICOLOR.
String of pairs of the format fb, where f is the foreground color and b is the background.

`a` black	`b` red	`c` green	`d` brown
`e` blue	`f` magenta	`g` cyan	`h` light grey
`A` bold black	`B` bold red	`C` bold green	`D` bold brown, usually shows up as yellow
`E` bold blue	`F` bold magenta	`G` bold cyan	`H` bold light grey; looks like bright white
`x` default foreground or background

The order of the attributes :
dir, symlink, socket, pipe, executable, block serial, character special, executable+SUID, executable+GUID, executabl+sticky+w=others, directory+w=others

Default "exfxcxdxbxegedabagacad",
i.e. blue foreground and default background for regular directories, magenta for symLinks, green for sockets, …black on red for setuid executables, etc.

$TERM

$CLICOLOR

depends on a terminal type with color capabilities.

$COLUMNS

column width for displaying multiple-text-column output.

$LS_COLWIDTHS

colon-delimited list of minimum column widths.
inode, block count, links, uname, group, flags, size, name.

example: LS_COLWIDTHS='10:4:4:7:5:12:6:40'
For the particlar set of files, Unreasonable and insufficient widths are ignored, i.e. ls -l 0* may adhear to olumn widths but ls -l may use other widths!

 >LS_COLWIDTHS='10:4:4:7:5:12:6:40'
 >/bin/ls -l 0*
-rw-r--r--     1 dgerman  staff     721 May 22 17:01 0
-rw-r--r--@    1 dgerman  staff    4534 Apr 24 11:05 0.html
-rw-r--r--     1 dgerman  staff    5067 May 22 17:01 00
-rw-r--r--     1 dgerman  staff    1800 Apr 27 15:47 09
-rwxr-xr-x     1 dgerman  staff   29230 Aug 28  2017 0finderDefaults.txt
-rw-r--r--     1 dgerman  staff   18694 Mar 28 13:50 0fud
-rw-r--r--     1 dgerman  staff     721 May 22 17:02 0s
 > /bin/ls -l    # notice wider size column neeed by 7 digit size of jpg file
-rw-r--r--     1 dgerman  staff      721 May 22 17:01 0
-rw-r--r--@    1 dgerman  staff     4534 Apr 24 11:05 0.html
drwxrwxr-x    16 dgerman  staff      544 Oct  8  2016 Homebrew1
-rwxr-xr-x@    1 dgerman  staff  1185182 Feb 17 16:43 IMG_3550-X5.jpg



> LS_COLWIDTHS='10:4:4:7:5:12:6:30'
> ls
--stop_rm_star*             Birdlog.addrs*                  UPSs.html*                      phoneNumbers.txt
0                           DGGNJdl.jpg*                    biggiesOpenS.txt*               profilesave*
0.html                      DGG_USpp503-925-913.jpg*        bin@                            sayWords*

> LS_COLWIDTHS='10:4:4:7:5:12:6:35'
> ls
--stop_rm_star*                         Desktop/                                lib-functions*
0                                       Documents/                              livehosts*
0.html                                  Downloads/                              log/

> LS_COLWIDTHS='10:4:4:7:5:12:6:40'
> ls
0                                               UPSs.html*
0.html                                          biggiesOpenS.txt*
00                                              bin@
00.html*                                        bsa.log
00s                                             defaults.180525.txt

Zero signifies a dynamically sized ).

$LANG

The locale to use when determining the order of day and month in the long -l format output. See environ .

$TZ timezone to use when displaying dates. See environ(7) for more information.

SEE ALSO stat, chflags, chmod, sort, xterm, compat, termcap, symlink, sticky

May 19, 2002 BSD