ls command: list files and directories

Syntax

ls [options] [file or directory]

Running ls with no arguments lists the current directory. Passing a directory name lists that directory instead.

Try it first

The terminal on this page starts inside a small project directory. Typing ls prints this:

$ ls
docs/  logs/  package.json  README.md  src/

The options worth knowing

Short options can be combined. ls -l -a and ls -la mean the same thing.

When you actually reach for it

ls is the command you type without thinking, but the option you add depends on what you are after.

ls -ltr earns its place. Sorting by time (-t) and reversing it (-r) puts the most recently changed file at the bottom, so in a busy directory the newest file is visible without scrolling.

Reading the output of ls -l

With -l, each entry gets a line of detail.

$ ls -l
total 20
drwxr-xr-x   2  user  user   4096  Sep  4 21:08  docs/
drwxr-xr-x   2  user  user   4096  Sep  4 21:08  logs/
-rw-r--r--   1  user  user     46  Sep  4 21:08  package.json
-rw-r--r--   1  user  user     36  Sep  4 21:08  README.md
drwxr-xr-x   2  user  user   4096  Sep  4 21:08  src/

Taking the package.json line from left to right:

That leading -rw-r--r-- splits into four parts:

-    rw-    r--    r--
type owner  group  others

The type is - for a regular file, d for a directory, and l for a symbolic link. Each of the three groups that follow shows read r, write w, and execute x when granted, and - when not. So -rw-r--r-- means a regular file that the owner can read and write, while the group and everyone else can only read.

The total 20 on the first line is the number of blocks the directory uses. It is not a count of files.

Showing hidden files

Entries beginning with a dot do not appear by default. Configuration files usually take that form, so reach for -a whenever a file you expect is missing.

$ ls
docs/  logs/  package.json  README.md  src/

$ ls -a
./  ../  .env  .gitignore  docs/  logs/  package.json  README.md  src/

Here ./ is the directory itself and ../ is the one above it.

Making sizes readable

On its own, -l reports bytes. Adding -h attaches a unit.

$ ls -lh logs
total 20
-rw-r--r--   1  user  user    19K  Sep  4 21:09  app.log

Finding the biggest files

-S sorts by size, largest first. Adding -l and -h turns that into a readable answer to "what is taking up the space".

$ ls -lhS logs
total 20
-rw-r--r--   1  user  user    19K  Sep  4 21:09  app.log

Listing everything underneath

-R walks down into each subdirectory.

$ ls -R
.:
docs/  logs/  package.json  README.md  src/

./docs:

./logs:
app.log

./src:
index.js  utils.js

Things that trip people up

An unknown name is an error, not an empty result.

$ ls nothing
ls: cannot access 'nothing': No such file or directory

Either the name is a typo, or the current directory is not the one you assumed. Run pwd to check where you are, then try again.

-d is not much use on its own. It exists to describe the directory rather than its contents, so it is normally paired with -l, as in ls -ld src.

The default order is by name. -t switches to modification time, and adding -r flips it to oldest first. ls -ltr therefore puts the most recently changed file at the bottom, which is why it is a common way to look at logs.