CLI: Introduction to the "ls" Command

Michael Bartholomew

Sep. 28, 2022

Are you on a UNIX or UNIX-like system (i.e., BSD, Linux, and macOS) and looking to list out the contents of a directory? Maybe you’re interested in viewing the attributes of a file or directory, like its size or owner. If so, then the ls command is what you’re looking for.

In its most basic form, ls displays what files and directories are available at your current location, listed in alphabetical order.

~ $ ls
Desktop		Library		Pictures
Documents	Movies		Public
Downloads	Music		test.txt

In the example above, the output of the ls command is a list of items in the current directory, which happens to be my home (~) directory.

Customization

The ls command can be customized in many different ways, both through arguments and filters. Below is the synopsis of the ls command, and how you format the parameters it supports:

ls [OPTION]... [FILE]...

We’ll first dive into arguments, which replace the [OPTION]... portion of the synopsis. Then, we’ll explore the world of filters, which replace the [FILE]... portion.

Note: When viewing synopsizes like the one above, parameters that are encased in brackets [] are optional.

Arguments

The beauty of command line tools like the ls command are the many arguments which can enhance its functionality. These arguments can be used on their own, or in combination with other arguments to give you an incredible amount of control over its output.

Note: As of February 2022, there are 57 arguments that can be passed to the ls command. In this article we are only going to focus on a subset of these arguments. If you would like to see a more complete list, please run man ls on your command line to view the manual.

Include Hidden Items

Arguments: -A or --almost-all

By default, ls hides files and directories that begin with a period character. By adding the -A argument, any files or directories that begin with a period character will be included in the output.

~ $ ls -A
.ssh		Documents	Music
.zsh_history	Downloads	Pictures
.zsh_sessions	Library		Public
Desktop		Movies		test.txt

I have circled the newly listed items that are now displayed thanks to the -A argument.

Append Indicators

Arguments: -F or --classify

If you don’t have a color terminal emulator, it can be hard to determine if an item is a file or directory. The -F argument solves this problem by appending a forward slash / onto the ends of the directory items.

~ $ ls -F
Desktop/	Library/	Pictures/
Documents/	Movies/		Public/
Downloads/	Music/		test.txt

As you can see, with the exception of test.txt (which I have circled above), all other items are easily identifiable as directories now that they have the forward slash / appended on the end.

In addition to appending the forward slash / to items that are directories, it also appends the following suffixes to other items:

* Executable
@ Symbolic link
% Whiteout
= Socket
| FIFO

Long Listing Format

Argument: -l

The -l argument replaces the way that files and directories are listed with a single long listing format instead of the item names displayed in a series of columns.

~ $ ls -l
total 8
drwx------  37 admin  admin  1184 Sep 25 11:54 Desktop
drwx------  11 admin  admin   352 May 10  2021 Documents
drwx------  30 admin  admin   960 Sep 22 13:12 Downloads
drwx------ 102 admin  admin  3264 May 29 00:34 Library
drwx------  17 admin  admin   544 Aug 29 12:45 Movies
drwx------   7 admin  admin   224 Jan  7  2022 Music
drwx------   6 admin  admin   192 Nov  5  2021 Pictures
drwxr-xr-x   4 admin  admin   128 Mar  5  2020 Public
-rw-r--r--   1 admin  admin     0 Sep 25 12:14 test.txt

In addition to the file/directory name, the list view displays additional attributes. The first line in the output displays the total number of allocated blocks (8 in the example above) for the files in the current directory. Each line that follows contains the following information for each file/directory:

Type (first character):
- d Directory
- - File
- l Linked file
- c Character device
- b Block device
Permissions (characters 2-10)
Number of file hard links
Owner username
Primary group name
Size (in bytes)
Last modified
File or directory name

Human Readable Sizes

Arguments: -h or --human-readable

When used in combination with the -l argument, the size column displays sizes in a more human readable format (i.e., 12K, 83M, and 16G.)

~ $ ls -lh
total 8
drwx------  37 admin  admin   1.2K Sep 25 11:54 Desktop
drwx------  11 admin  admin   352B May 10  2021 Documents
drwx------  30 admin  admin   960B Sep 22 13:12 Downloads
drwx------ 102 admin  admin   3.2K May 29 00:34 Library
drwx------  17 admin  admin   544B Aug 29 12:45 Movies
drwx------   7 admin  admin   224B Jan  7  2022 Music
drwx------   6 admin  admin   192B Nov  5  2021 Pictures
drwxr-xr-x   4 admin  admin   128B Mar  5  2020 Public
-rw-r--r--   1 admin  admin     0B Sep 25 12:14 test.txt

This can make it much easier to determine the sizes of files, removing the need for you to quickly convert sizes from bytes to the more appropriate unit.

Reverse Listing Order

Arguments: -r or --reverse

By default, ls displays items in alphabetical order. Passing the -r argument will display the items in reverse alphabetical order.

~ $ ls -r
test.txt	Music		Downloads
Public		Movies		Documents
Pictures	Library		Desktop

This can also be used in combination with the -l argument.

~ $ ls -lr
total 8
-rw-r--r--   1 admin  admin     0 Sep 25 12:14 test.txt
drwxr-xr-x   4 admin  admin   128 Mar  5  2020 Public
drwx------   6 admin  admin   192 Nov  5  2021 Pictures
drwx------   7 admin  admin   224 Jan  7  2022 Music
drwx------  17 admin  admin   544 Aug 29 12:45 Movies
drwx------ 102 admin  admin  3264 May 29 00:34 Library
drwx------  30 admin  admin   960 Sep 22 13:12 Downloads
drwx------  11 admin  admin   352 May 10  2021 Documents
drwx------  37 admin  admin  1184 Sep 25 11:54 Desktop

Order By Size

Argument: -S

It’s also possible to sort the output by size. Passing the -S argument lists the items by size, with the largest item first.

~ $ ls -S
Library		Movies		Pictures
Desktop		Documents	Public
Downloads	Music		test.txt

This can also be used in combination with the -l argument.

~ $ ls -lS
total 8
drwx------ 102 admin  admin  3264 May 29 00:34 Library
drwx------  37 admin  admin  1184 Sep 25 11:54 Desktop
drwx------  30 admin  admin   960 Sep 22 13:12 Downloads
drwx------  17 admin  admin   544 Aug 29 12:45 Movies
drwx------  11 admin  admin   352 May 10  2021 Documents
drwx------   7 admin  admin   224 Jan  7  2022 Music
drwx------   6 admin  admin   192 Nov  5  2021 Pictures
drwxr-xr-x   4 admin  admin   128 Mar  5  2020 Public
-rw-r--r--   1 admin  admin     0 Sep 25 12:14 test.txt

When paired with the -r argument, it lists by size with the smallest item first.

~ $ ls -lSr
total 8
-rw-r--r--   1 admin  admin     0 Sep 25 12:14 test.txt
drwxr-xr-x   4 admin  admin   128 Mar  5  2020 Public
drwx------   6 admin  admin   192 Nov  5  2021 Pictures
drwx------   7 admin  admin   224 Jan  7  2022 Music
drwx------  11 admin  admin   352 May 10  2021 Documents
drwx------  17 admin  admin   544 Aug 29 12:45 Movies
drwx------  30 admin  admin   960 Sep 22 13:12 Downloads
drwx------  37 admin  admin  1184 Sep 25 11:54 Desktop
drwx------ 102 admin  admin  3264 May 29 00:34 Library

Order By Time

Argument: -t

It’s also possible to sort the output by time. Passing the -t argument lists the items by time, with the newest item first.

~ $ ls -t
test.txt	Movies		Pictures
Desktop		Library		Documents
Downloads	Music		Public

This can also be used in combination with the -l argument.

~ $ ls -lt
total 8
-rw-r--r--   1 admin  admin     0 Sep 25 12:14 test.txt
drwx------  37 admin  admin  1184 Sep 25 11:54 Desktop
drwx------  30 admin  admin   960 Sep 22 13:12 Downloads
drwx------  17 admin  admin   544 Aug 29 12:45 Movies
drwx------ 102 admin  admin  3264 May 29 00:34 Library
drwx------   7 admin  admin   224 Jan  7  2022 Music
drwx------   6 admin  admin   192 Nov  5  2021 Pictures
drwx------  11 admin  admin   352 May 10  2021 Documents
drwxr-xr-x   4 admin  admin   128 Mar  5  2020 Public

When paired with the -r argument, it lists by time with the oldest item first.

~ $ ls -ltr
total 8
drwxr-xr-x   4 admin  admin   128 Mar  5  2020 Public
drwx------  11 admin  admin   352 May 10  2021 Documents
drwx------   6 admin  admin   192 Nov  5  2021 Pictures
drwx------   7 admin  admin   224 Jan  7  2022 Music
drwx------ 102 admin  admin  3264 May 29 00:34 Library
drwx------  17 admin  admin   544 Aug 29 12:45 Movies
drwx------  30 admin  admin   960 Sep 22 13:12 Downloads
drwx------  37 admin  admin  1184 Sep 25 11:54 Desktop
-rw-r--r--   1 admin  admin     0 Sep 25 12:14 test.txt

Filtering Output

In addition to viewing the contents of the current directory, it is also possible to apply filters to change the target of the listing. For example, if you were interested in the contents of the root directory, you could add the location / at the end of the command:

~ $ ls /
bin   dev  home  lib32  libx32      media  opt   root  sbin  srv  tmp  var
boot  etc  lib   lib64  lost+found  mnt    proc  run   snap  sys  usr

Filters can also be used in combination with arguments. In the next example, we simply added the -l argument.

~ $ ls -l
/total 64
lrwxrwxrwx   1 root root     7 Jul 17 22:09 bin -> usr/bin
drwxr-xr-x   4 root root  4096 Sep 24 20:36 boot
drwxr-xr-x  19 root root  3880 Sep 24 20:36 dev
drwxr-xr-x  97 root root  4096 Sep 24 20:37 etc
drwxr-xr-x   3 root root  4096 Sep 24 20:30 home
lrwxrwxrwx   1 root root     7 Jul 17 22:09 lib -> usr/lib
lrwxrwxrwx   1 root root     9 Jul 17 22:09 lib32 -> usr/lib32
lrwxrwxrwx   1 root root     9 Jul 17 22:09 lib64 -> usr/lib64
lrwxrwxrwx   1 root root    10 Jul 17 22:09 libx32 -> usr/libx32
drwx------   2 root root 16384 Jul 17 22:11 lost+found
drwxr-xr-x   2 root root  4096 Jul 17 22:09 media
drwxr-xr-x   2 root root  4096 Jul 17 22:09 mnt
drwxr-xr-x   2 root root  4096 Jul 17 22:09 opt
dr-xr-xr-x 151 root root     0 Sep 24 20:36 proc
drwx------   4 root root  4096 Aug  1 02:23 root
drwxr-xr-x  29 root root   900 Sep 26 06:39 run
lrwxrwxrwx   1 root root     8 Jul 17 22:09 sbin -> usr/sbin
drwxr-xr-x   6 root root  4096 Jul 17 22:11 snap
drwxr-xr-x   2 root root  4096 Jul 17 22:09 srv
dr-xr-xr-x  13 root root     0 Sep 24 20:36 sys
drwxrwxrwt  12 root root  4096 Sep 26 10:12 tmp
drwxr-xr-x  14 root root  4096 Jul 17 22:09 usr
drwxr-xr-x  13 root root  4096 Jul 17 22:11 var

Another option is to pass a file path as the filter, to focus on the details of that single item. Here, we are interested in the details of the test.txt file.

~ $ ls -l test.txt
-rw-r--r--   1 admin  admin     0 Sep 25 12:14 test.txt

Wildcards

It is also possible to perform pattern matching via filter strings. This allows you to list out files that meet certain criteria, like those that start with a certain letter, or are only 3 characters in length.

File globbing is the process of pattern matching via the use of wildcards like ? and *. There are are multiple wildcards available (we cover a few below), and the filter strings can contain any number of them in any combination.

Question Mark

The question mark ? is used to replace a single character in the filter string.

Example: Only display files that are three-characters in length, and start with the letter a

~ $ ls a??
api		app		aps

Asterisk

The asterisk * goes beyond the quesion mark ?, representing any number of characters in a filter string.

Example 1: Only display file(s) that have the .txt file extension

~ $ ls *.txt
resume.txt	text.txt	zebra.txt

Example 2: Only display file(s) that begin with the letter t and end with .txt

~ $ ls t*.txt
text.txt

Example 3: Only display file(s) that start with the letter z and have a three-digit file extension

~ $ ls z*.???
zebra.txt

Brackets

Brackets [] allow you to define what characters are acceptable for a single character position.

~ $ ls f[aiu]ll.txt
fall.txt	fill.txt	full.txt

In this previous example, the filter string is looking for files that:

Start with f
Have a second character of a, i, or u
End with ll.txt

Brackets also support ranges of characters, like [b-g], which would match any character from b thru g.

Exclamation Mark

The exclamation mark ! defines what should not be allowed in a single character position.

~ $ ls f[!i]ll.txt
fall.txt	full.txt

In the previous example, the filter string is looking for files that:

Start with f
Have a second character that is not i
End with ll.txt

Character Classes

Character classes can be used inside brackets [] in place of manually defining acceptable characters. They are encased in brackets [] and like brackets can be combined with question marks ?, asterisks * and exclamation marks !.

[:alnum:] Alphanumeric (upper and lowercase alphabet characters and numeric digits)
[:alpha:] Upper and lowercase alphabet characters
[:digit:] Numeric digits
[:lower:] Lowercase alphabet characters
[:punct:] Punctuation characters ! " # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ` { | } ~
[:space:] Space character
[:upper:] Uppercase alphabet characters

Example 1: Instead of using [a-z] to define all lowercase alphabetical characters, you could instead use [[:lower:]].

Example 2: Instead of using [0-9] to define all numerical digits, you could instead use [[:digit:]].

Example 3: Instead of using [a-zA-Z0-9] to define all lowercase alphabetical characters, uppercase alphabetical characters, and numerical digits, you could instead use [[:alnum:]].

Conclusion

As this is an introductory article, we have only covered the tip of the iceberg. If you would like to learn more about the ls command, please run man ls on your command line to view the manual.