← All commands
THE COMMAND REFERENCE

ls

List files and directories.

Last updated

BusyBox

Implementation-level reference; examples are not certified for every installed version.

Overview

ls lists the names in a directory, or the files you name. Names are sorted, and when the output goes to a pipe or file each name is on its own line.

Background

An ls command appeared in Version 1 Unix, according to the FreeBSD and macOS manuals. Today the name covers GNU ls, the ls that macOS ships, and the ls applet in BusyBox. They agree on -a, -d, -l, -R, and -r, and differ on colour, sorting options, and the header that ls -R prints for a single directory.

Examples

List the current directory:

ls

List the contents of one directory:

ls logs

List only the files that match a pattern; the shell expands *.log before ls runs:

ls *.log

Show a directory itself instead of its contents. The trailing slash in the pattern matches only directories:

ls -d */

Include entries that start with a dot, including . and ..:

ls -a logs

List directories and everything below them. Naming two directories keeps the output the same on every implementation, with a header line for each:

ls -R logs projects

Reverse the sort order:

ls -r

Show the permission string of a file; -l is the long format and cut keeps its first ten characters:

ls -l notes.txt | cut -c1-10

Options

-a
Include hidden entries, those whose names begin with a dot.

-d
List directories themselves rather than their contents.

-l
Use the long format: permissions, link count, owner, group, size, modification time and name. The
columns are padded differently between implementations, so scripts should not parse them.

-R
List subdirectories recursively.

-r
Reverse the sort order.

Common mistakes

Do not parse ls output in scripts. Names can contain spaces or newlines, and the long format varies by implementation; use a glob or find instead. ls with no operands lists the current directory, but an unmatched pattern such as ls *.log passes the literal text and fails if nothing matches.

Portability

The Common examples use only -a, -d, -l, -R and -r, which all three implementations accept. With a single directory, BSD ls -R leaves out the header line that GNU prints. Colour and sorting options such as --color and -t differ between GNU and BSD. The Common examples were executed on GNU coreutils 9.11, macOS system tools, and BusyBox 1.37.0 (see the development guide for the exact check).

About BusyBox ls

BusyBox bundles ls as an applet, and anything beyond the common options depends on how it was built. This page's examples ran on BusyBox 1.37.0.

BusyBox notes

BusyBox ls supports the options in the common examples; GNU long options and colour depend on the build.

References

Original explanations, with upstream documentation for further reading. FreeBSD references are comparison material, not a claim of Apple version equivalence.