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.

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

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

     RptTable.html
     archve
     bcols.js
     birdRpt.080410.sed
     tableBot.html
     tableTop.html
     tmp

-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, makeRpt.sh, 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
| FIFO

-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, directory+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

-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

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

-Z
 --context

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

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:

r the object is readable; - not readable.
w the object is writable; - not writable.
x file is executable or directory is searchable; - Inaccessable

+ 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 extended attribute can be deleted using xattr.
```
xattr -d com.apple.quarantine  morse  
OR
xattr -c file # clear all
```
The first of the following that applies:
- S the object is not executable
  - in the owner field (uuSgggooo) set-user-ID is set.
  - in the group field set-group-ID 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.
- T sticky bit is set on a directory. Files in a sticky directory may only be removed or renamed if the user has write permission for the directory and the user is the owner of the file, the owner of the directory, or the superuser.
  This is useful for directories such as /tmp which must be publicly writable but users are prohibited from removing or rename other's files.
  Any user may create a sticky directory using chmod.
- t sticky bit is set (mode 1000). A sticky file was originally intended to indicate to the memory managment routines that this file had a preference for being retained in memory even if no process was connected to it. It was expectd to be used again soon and frequently. Advances in memory caching has lead to this usually being ignored.

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! >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 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 .
`$TERM`
`$TZ`	timezone to use when displaying dates. See environ

See

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

May 19, 2002 BSD