why does ls -d also list files, and where is it documented?

Question

• when specifying ls --directory a* it should list only directories starting with a*
• BUT it lists files AND directories starting with a

Questions:

• where might I find some documentation on this, other than man and info where I think I thoroughly looked?
• does this work in BASH only?

Answer 1

The a* and *a* syntax is implemented by the shell, not by the ls command.

When you type

ls a*

at your shell prompt, the shell expands a* to a list of existing all files in the current directory whose names start with a. For example, it might expand a* to the sequence a1 a2 a3, and pass those as arguments to ls. The ls command itself never sees the * character; it only sees the three arguments a1, a2, and a3.

For purposes of wildcard expansion, "files" refers to all entities in the current directory. For example, a1 might be a normal file, a2 might be a directory, and a3 might be a symlink. They all have directory entries, and the shell's wildcard expansion doesn't care what kind of entity those entries refer to.

Practically all shells you're likely to run across (bash, sh, ksh, zsh, csh, tcsh, ...) implement wildcards. The details may vary, but the basic syntax of * matching zero or more characters and ? matching any single character is reasonably consistent.

For bash in particular, this is documented in the "Filename expansion" section of the bash manual; run info bash and search for "Filename expansion", or see here.

The fact that this is done by the shell, and not by individual commands, has some interesting (and sometimes surprising) consequences. The best thing about it is that wildcard handling is consistent for (very nearly) all commands; if the shell didn't do this, inevitably some commands wouldn't bother, and others would do it in subtly different ways that the author thought was "better". (I think the Windows command shell has this problem, but I'm not familiar enough with it to comment further.)

On the other hand, it's difficult to write a command to rename multiple files. If you write:

mv *.log *.log.bak

it will probably fail, since*.log.bak is expanded based on the files that already exist in the current directory. There are commands that do this kind of thing, but they have to use their own syntax to specify how the files are to be renamed. Some commands (such as find) can do their own wildcard expansion; you have to quote the arguments to suppress the shell's expansion:

find . -name '*.txt' -print

The shell's wildcard expansion is based entirely on the syntax of the command-line argument and the set of existing files. It can't be affected by the meaning of the command. For example, if you want to move all .log files up to the parent directory, you can type:

mv *.log ..

If you forget the .. :

mv *.log

and there happen to be exactly two .log files in the current directory, it will expand to:

mv one.log two.log

which will rename one.log and clobber two.log.

EDIT: And after 52 upvotes, an accept, and a Guru badge, maybe I should actually answer the question in the title.

The -d or --directory option to ls doesn't tell it to list only directories. It tells it to list directories just as themselves, not their contents. If you give a directory name as an argument to ls, by default it will list the contents of the directory, since that's usually what you're interested in. The -d option tells it to list just the directory itself. This can be particularly useful when combined with wildcards. If you type:

ls -l a*

ls will give you a long listing of each file whose name starts with a, and of the contents of each directory whose name starts with a. If you just want a list of the files and directories, one line for each, you can use:

ls -ld a*

which is equivalent to:

ls -l -d a*

Remember again that the ls command never sees the * character.

As for where this is documented, man ls will show you the documentation for the ls command on just about any Unix-like system. On most Linux-based systems, the ls command is part of the GNU coreutils package; if you have the info command, either info ls or info coreutils ls should give you more definitive and comprehensive documentation. Other systems, such as MacOS, may use different versions of the ls command, and may not have the info command; for those systems, use man ls. And ls --help will show a relatively short usage message (117 lines on my system) if you're using the GNU coreutils implementation.

And yes, even experts need to consult the documentation now and then. See also this classic joke.

Answer 2

See Keith Thompson’s answer; but to explain why ls --directory a* shows files and directories: The --directory option does not suppress non-directory files. Instead, it lists the directories as such, while it would otherwise list their content. Example:

$ mkdir foo
$ touch foo/bar
$ ls foo
bar
$ ls --directory foo
foo

Answer 3

To be very explicit, it is documented in the ls(1) manual page:

-d, --directory list directory entries instead of contents, and do not dereference symbolic links

to be fair, "entries instead of contents" could probably be more explanatory:

If FILE is a directory, show the directory entry itself instead of listing the contents of that directory. If FILE is a symbolic link, show the link entry itself instead of the file pointed to by the link.

Answer 4

Globbing

As has been explained, the expansion of * (and similar expansions) is called globbing in Unix jargon, and is usually a feature of the command processor (known as the "shell" in Unix parlance). So globbing can be used in many other places too; type man 7 glob at the shell of a classic Linux distribution (or see this) for more about globbing.

In early Unix, glob was actually implemented by a separate program called /etc/glob (see page 10 of this old UNIX manual for documentation for that). Nowadays, it is a code routine supplied by code libraries, and is commonly used by shells. Source: Wikipedia.

Directories

As to why ls -d lists files as well as directories...

The ls man page explains why this happens, but with a very terse explanation. So here is an attempt at an expanded explanation:

By default ls lists the contents of directories when given their names, and will do the same thing for symlinks to directories. The -d option means, "when given name(s) of directory(ies)" (which can also be given implicitly by globbing), only show the _name_s of the directory(ies), but not their contents. Similarly, when provided with (explicitly or implicitly) name(s) of symlinks to directories, show the file name of the symlink, not the contents of the directory which it references.

The -d option has nothing to do, as far as I can tell, with which items are listed; this can be done (source: here) with find, like so: find . -maxdepth 1 -type d. I am not sure if there is a good way to do so only with GNU ls. Here are some examples of how to use the find command.

So to sum up: By default ls shows the contents of directories when given their path name. -d changes this behavior, only showing the directory name itself, as would be done for a standard file.

Answer 5

Documentation doesn't say it lists only directory entries bur rather when ls receives directory name it lists dir entry instead of it's content. Best way to understand is by example:

> {ice} ~ :10:47 % ls -l / 
total 97
drwxr-xr-x   2 root root  4096 May  3 00:27 bin
drwxr-xr-x   4 root root  1024 May  3 14:17 boot
drwxr-xr-x   2 root root  4096 Apr 29 13:44 cdrom
drwxr-xr-x  18 root root  4420 May  9 09:58 dev
...
lrwxrwxrwx   1 root root    33 May  3 14:16 vmlinuz -> boot/vmlinuz-3.9.0-030900-generic
lrwxrwxrwx   1 root root    29 May  3 11:07 vmlinuz.old -> boot/vmlinuz-3.8.0-19-generic
> {ice} ~ :10:47 % ls -ld /
drwxr-xr-x 25 root root 4096 May  3 14:16 /

Answer 6

The documentation is part of the shell. In particular the shell performs various expansions and substitutions in a particular order before executing a command.

The sequence of word expansions for a Bourne compatible shell is

1. Tilde Expansion
2. Parameter Expansion
3. Command Substitution
4. Arithmetic Expansion
5. Field Splitting
6. Pathname Expansion
7. Quote Removal

So, the ls command doesn't even see the * characters, the arguments are already expanded with all files matching the a* glob pattern. This is unlike on Windows, where each command needing file name globbing has to implement this feature itself.

Answer 7

The key word you need (man bash) is "Pathname Expansion".