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

     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

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

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

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

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






--tabsize=cols

     -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

tab stops at each cols default 8.

-e

extend to include Access Control List (ACL) info.

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

-O

longer output. dash is displayed if no "special" flags are set.(hidden, arch, compressed, uchg, schg, append, archived, nodump, opaque, uunlink (chflg)

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

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: rwxrwxr-x ) :

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.
The first of the following that applies:
- S the object is not executable
  - in the owner permissions set-user-ID is set.
  - in the group permissions 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.
- x file is executable or directory is searchable.
- - object 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 one extended attribute be deleted using xattr
```
xattr -d com.apple.quarantine  morse  
OR
xattr -c file # clear all
```

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 total nnnnnn number of 512-byte blocks used by the files in the directory is displayed on a line by itself before the files.

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

ENVIRONMENT variables

$BLOCKSIZE

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

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

See

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

May 19, 2002 BSD