| Lesson 2 | More options for listing files |
| Objective | List files using the ls command. |
A directory listing can answer several different questions. You might want the names of the files in your current directory, the hidden configuration entries that an ordinary listing omits, or the contents of every subdirectory in a project. Sometimes you need information about the directory itself, such as its owner and permissions. The ls command can provide each view, but the options you choose determine which question it answers.
This lesson builds on -l, which selects long-format output, and -F, which adds classification marks. You will learn three additional options: -a to include hidden names, -R to list a hierarchy recursively, and -d to inspect directory operands themselves. The examples show how to combine these options without confusing the entries inside a directory with the directory that contains them.
Without a pathname argument, ls lists the current working directory. When you supply the name of a directory, it normally lists that directory's contents. These commands therefore inspect different starting locations:
ls
ls images
The relative path images is interpreted from your current directory. If you are unsure where you are, check with pwd before interpreting a result or an error message. An absolute pathname starts with / and identifies its location from the filesystem root instead.
The general command structure can be written as the following syntax template. The brackets indicate optional parts and the dots mean that more than one path may be supplied; they are not literal characters to type:
ls [options] [path...]
Use -l when you need details rather than names alone. Use -F when you want a quick indication of entry types. With -F, a trailing slash marks a directory, an asterisk marks an executable regular file, and an at sign can mark a symbolic link. These marks belong to the display, not to the stored filenames. For example, a directory shown as images/ is named images.
The historical terminal examples below include selectable transcriptions. The % character is the shell prompt and should not be typed. The old terminal window is context for the examples, not a requirement to use that terminal or connection method. Filenames, dates, sizes, and screen layout are illustrative; your system will not necessarily display the same values.
% ls -F
DeadLetters/ junk phone.new
docs/ list practice/
images/ Mail/ project/
%
In this listing, DeadLetters, docs, images, Mail, practice, and project have trailing slashes, identifying them as directories. The names junk, list, and phone.new have no classification suffix in this example. You can use this view to orient yourself before deciding which directory to inspect next.
Do not infer that a missing suffix proves everything about an entry. Classification is a convenient visual aid, while long-format output provides more information. Likewise, column placement is not part of a pathname. Terminal width and output formatting affect how names are arranged, so read the names themselves rather than treating a screen column as a separate directory.
A directory may contain subdirectories, which may themselves contain further directories. Together these form a hierarchy or directory tree. To inspect the nested contents without changing into each directory separately, request a recursive listing with uppercase -R [1].
% ls -RF images
images:
bullets/ icons/ lines/
images/bullets:
ballblue.gif ballred.gif ballyell.gif
images/icons:
down.gif logo1.jpg logo_big.jpg up.gif
images/lines:
rainbow.gif thick.gif thin.gif
%
The command starts at images. Its first section, headed images:, shows three immediate subdirectories: bullets, icons, and lines. Later headings identify each of those locations, followed by the filenames found there. For example, the heading images/icons: establishes the context for logo1.jpg and the other icon files.
Read a recursive listing as a sequence of directory listings. It reveals a tree's contents, but it does not necessarily draw connecting branches or indent every level as a graphical tree viewer would. Directory headings prevent ambiguity when two different directories contain files with the same name.
If you omit the path, the current directory is the starting location. These two commands express that choice implicitly and explicitly:
ls -R
ls -R .
Recursion and hidden-name visibility are separate choices. The -R option does not automatically enable -a. To combine recursive traversal, hidden-entry visibility, and classification suffixes, use:
ls -aRF images
Including . and .. in the displayed entries does not mean that recursive listing repeatedly follows them back into the same directories. The utility handles these special entries so that they do not create that simple loop. Details of symbolic-link handling are a separate subject; do not assume every link will be traversed merely because recursion was requested.
Start with a directory relevant to your task. Listing a small project is easier to interpret than requesting a very large tree. If the command reports that a directory cannot be read, the output may be incomplete even though other sections were printed successfully. Read diagnostics rather than interpreting partial output as a complete inventory.
Suppose you want to check the owner and permissions of images. A common first attempt is to add long format while naming that directory:
% ls -lF images
total 24
drwxr-xr-x 2 danielg doc 512 Aug 26 17:22 bullets/
drwxr-xr-x 2 danielg doc 512 Aug 26 17:23 icons/
drwxr-xr-x 2 danielg doc 512 Aug 26 17:21 lines/
%
The command is valid, but it answers a different question. Each output line describes an entry inside images: bullets, icons, or lines. None of these lines describes the parent images directory. Adding -l changes the amount of information shown; it does not change the default decision to list a directory's contents.
Use -d to list the directory operand itself instead. Keep -l because you still want metadata:
% ls -lF -d images
drwxr-xr-x 5 danielg doc 4096 Aug 26 17:22 images/
%
Clarification of the historical image caption: -d selects the directory itself, not its contents. It does not limit output to a bare name. Because this command also includes -l, the result contains permissions, ownership, size, and time information as well as the name.
Read the result from left to right. The initial d identifies a directory. The following characters show permission bits. The next fields give the link count, owner, group, displayed size, modification date and time, and name. In this example, the owner is danielg, the group is doc, and the named directory is images.
The displayed size 4096 describes the directory object in this historical listing. It is not the combined size of every image and subdirectory beneath it. Directory sizes and link counts depend on the filesystem and directory structure, so do not expect the same numbers simply because your directory has a similar name or purpose.
Likewise, total 24 in the previous listing is a block-allocation total for the listed entries. It does not mean 24 files or 24 bytes. The block units depend on the implementation and settings. These examples preserve the original values to show the output structure, not to provide a measurement of your machine.
One further distinction is essential: -d does not filter a directory's contents to show only its subdirectories. It changes how directory operands are treated. Thus ls -d images lists the operand, while ls -ld images lists that same operand with long-format details.
The short options introduced here can be combined after a single hyphen. These forms request the same view:
ls -l -F -d images
ls -lF -d images
ls -ldF images
Read each letter independently: long format, classification suffixes, and the directory operand itself. Combining flags is convenient, but understanding each one is more useful than memorizing a long string. When an output surprises you, simplify the command and add one option at a time.
Option letters are case-sensitive. Uppercase -R requests recursion. Lowercase -r reverses the sorting order and does not mean recursive listing. Likewise, lowercase -l is a letter, not the digit one. Small typing differences can produce valid commands with substantially different output.
Place options before paths in your examples so that the command is easy to read and works consistently across familiar UNIX-style interfaces. Quote a path that contains spaces, for example ls -ld "project images". The quotes keep the shell from treating the two words as separate pathname arguments.
| Question | Example command | Result |
|---|---|---|
| Which entries are visible here? | ls -F | A classified listing of the current directory. |
| Which hidden entries are also present? | ls -aF | Hidden names included, with classification marks. |
| What is beneath images? | ls -RF images | Listings for images and its accessible subdirectories. |
| What metadata describes its immediate contents? | ls -lF images | Long-format lines for entries inside images. |
| What metadata describes images itself? | ls -ldF images | A long-format line for the directory operand. |
Before running a command, state which row matches your intention. Afterward, check whether the output names the expected objects. A successful command can still answer the wrong question if you selected contents when you intended the containing directory. This distinction becomes important when checking permissions before copying or organizing a project.
For a simple practice comparison, choose an existing directory you can read. Run a basic listing, add -a, and identify which names became visible. Then compare ls -l directory-name with ls -ld directory-name, substituting the real path. These commands inspect information; they do not create, copy, or remove the entries.
Output appearance can vary with terminal width, locale, aliases, and the particular implementation. A redirected listing may also use a different layout from a terminal listing. Judge your understanding by the entries selected and the fields shown rather than by whether the screen looks identical to the old examples.
GNU Coreutils also provides dir, whose default behavior is equivalent to ls -C -b: column output with nongraphic characters represented using escapes. This is an implementation-specific alternative, not a replacement for learning ls and not a guarantee that every UNIX system has the same dir command. It should not be assumed identical to the Windows or DOS command of that name.
The GNU manual documents dir separately. For the tasks in this lesson, continue using ls and consult man ls for the options supported by your installed version.
You can now distinguish the contents of a directory from the directory itself, include hidden names, and examine nested directories recursively. In the next lesson, you will build on that ability to inspect a tree by learning how to copy directories and their contents with cp.