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),

-l long format. If the output is to a terminal, total bbbbbb sum of file blocks is output on a line before each directory.
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 file is on a network drive) the numeric ID is shown, or
for MS Windows (which does not support owner and group)

     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
     -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 
-C multi-Column output with entries sorted down the columns.
Sorted: Numeric then UPPER CASE before lowercase, down first column, then second column ( see -x)
Width of columns based on longest filename (not per column).
Default when output is to a terminal but not if piped (| ) for example to more, head ….
> ls -C
↓ 0test.txt     RptTable.html      birdRpt.080410.sed         fixRpt.sed index.shtml     rpt.sql           
↓ archve        birdRpt.sed        freq.sql                          rptFix.080410.sed
↓ bcols.js      birdRptTable.html  index.html                 rpt.0807001.sql            rptRows.html      
-x multi-column output with entries sorted across the rows →
> ls -x       →              →           →
RptTable.html      archve          bcols.js  birdRpt.080410.sed  birdRpt.sed
birdRptTable.html  fixRpt.sed      freq.sql  index.html          index.shtml         rpt.0807001.sql rpt.sql   rptFix.080410.sed   rptRows.html
tableBot.html      tableTop.html   tmp 
-a all files (include normally hidden files begining with dot (.)(usually configuration files for applications that are uninteresting (?))
> /bin/ls -a
.              .bashrc             fixRpt.sed        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 Almost 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      rptFix.080410.sed tableTop.html
.bashrc       birdRptTable.html  index.html rpt.0807001.sql rptRows.html      tmp
-1 one entry per line. default when output is not to a terminal.
-m Stream output format; list files across the page, separated by comma and space .

RptTable.html, archve, bcols.js, birdRpt.080410.sed, birdRpt.sed, birdRptTable.html, fixRpt.sed, 
freq.sql, index.html, index.shtml,, rpt.0807001.sql, rpt.sql, rptFix.080410.sed, rptRows.html, 
tableBot.html, tableTop.html, tmp
-p display / after directories
-F include suffix character based on type.
/ directories,
* executables,
+ extended security information
     (Use -@ to display that information)
@ symbolic link
     (Use -@ to display that information)

= socket
% whiteout
-G colorize filename dependent on type.
Environment Variables effecting colors:
$CLICOLOR Use ANSI color sequences to distinguish file types. .
dir, symlink, socket, pipe, block serial, character special,
executable, executable+SUID, executable+GUID, executable+sticky+w=others,

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 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.

options effecting output sorting
-r reverse the order of the sort or the oldest entries first or smallest files first
-S Size decending. -Sr ascending.
-t time modified before sorting by lexicographical order.
-c time of last status change
-u time of last access
If file system is mounted with noatime access times are not updated.
-v natural sort of version numbers within text i.e. 1,2,7,10 not 1,10,2,7.
> ls -log x*
-rw-r--r-- 1 0 Dec 30 12:24 x.1
-rw-r--r-- 1 0 Dec 30 12:24 x.10
-rw-r--r-- 1 0 Dec 30 12:24 x.2
> ls -logv x*
-rw-r--r-- 1 0 Dec 30 12:24 x.1
-rw-r--r-- 1 0 Dec 30 12:24 x.2
-rw-r--r-- 1 0 Dec 30 12:24 x.10
-X eXtension.
-f not sorted.
--time=which with -l, time as which default modification time: which atime | access | use ctime | status
atime or access or use (-u); ctime or status (-c);
and use time as sort key if --sort=time (newest first)
--time-style=time_style time/date format with -l; see TIME_STYLE

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
--tabsize=cols tab stops at each cols default 8.
-e include Access Control List (ACL)
ls -logde ~/L* 
drwx------@ 98   3136 Dec 25 22:30 /Users/dgerman/Library/
 0: group:everyone deny delete
output security context of each file. (not )
dr-xr-xr-x  root     root     ?                                lib
dr-xr-xr-x  root     root     ?                                lib64
drwxr-xr-x. root     root     system_u:object_r:usr_t:s0       opt
dr-xr-xr-x  root     root     ?                                proc
selinux: unconfined_u,
-O with -l
 only
Other flags not normally shown. hidden from finder , arch, compressed, uchg, schg, append, archived, nodump, opaque, uunlink chflg.
Dash is displayed if no "special" flags are set.
-rw-r--r--   1  -        527 Dec 31  2020 AndroidPhone.txt
drwx------  11  -        352 Jul  3 12:14 Applications/
-rwx------   1  uchg   26054 May 11  2007 HALmsg4u.wav*
-rw-r--r--   1  -      12682 Jun 21 13:30 LG43UP8000PUA.txt

ls -logdO ~/L*
drwx------@ 98   hidden 3136 Dec 25 22:30 /Users/dgerman/Library/
-o display owner (supressing group)
-g display group name (supressing owner) in the long format output.
-n numeric userID and groupID
-i inode number
-k size in kilobytes, not blocks,
overrides $BLOCKSIZE. Many profiles set $BLOCKSIZE = 1k
-h human ? sizes. With -l , use suffixes: Kilobyte, Megabyte, Gigabyte, Terabyte and Petabyte and
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

without -h -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 for which ls -l reports incorrect count
If the output is to a terminal,
total bbbbbb sum of file blocks is output on a line before each directory
-R Recursively list subdirectories
-d Directories not searched recursively.

options affecting symbolic link display
-H Symbolic links on 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
-H, -L and-P override each other (either partially or fully); they are applied in the order specified.

-q display non-graphic characters in file names as ?. default when output is to a terminal.
-w raw display of non-printable characters. default when output is not to a terminal.
-v unedited displaying of non-graphic characters; default when output is not to a terminal.
-B Binary filenames ; display non-displayable characters in file names as \ooo 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.

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 -i, -s, and -l .

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.

The mode, aka permssion flags, are three fields of three characters each (ex: rwxrwxrwx ) :

  • fields: user whos owns the object , group members , and others.
  • Each field has three character positions:
    1. r the object is readable; - not readable.
    2. w the object is writable; - not writable.
    3. x file is executable or directory is searchable; - Inaccessable

    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 total nnnnnn number of blocks used by the files in the directory is displayed on a line by itself before the files. Each file on a takes up at least 4 blocks.

    ENVIRONMENT variables

    $BLOCKSIZE default is 512 although frequently set to 1K in .profile.

    $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!

     >/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
    1                           DGGNJdl.jpg*                    biggiesOpenS.txt*               profilesave*
    1.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*
    1                                       Documents/                              livehosts*
    1.html                                  Downloads/                              log/
    > LS_COLWIDTHS='10:4:4:7:5:12:6:40'
    > ls
    1                                               UPSs.html*
    1.html                                          biggiesOpenS.txt*
    11                                              bin@
    11.html*                                        bsa.log
    11s                                             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


    stat, xattr, chflags, chmod, sort, xterm, compat, termcap, symlink, sticky

    May 19, 2002 BSD