What is the meaning of ls -d?

Question

I entered the man page of ls, the entry for the -d option is as follows:

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

So, I thought the ls -d command will display all directories within a given directory. However I entered one directory and tried two different commands:

1. obtaining directories with: ls -l | grep ^d: this one worked, all 7 directories being displayed

2. obtaining directories with ls -d: this does not display the 7 directories, only a point .

I do not understand if I am using the option wrongly or if I am misunderstanding its meaning, what is the actual meaning and usage for the -d option ?

Answer 1

ls -d shows information about a directory or symbolic link - with this information being (in simple terms) its respective path. The logical assumption is that the d stands for directory, since it's most basic definition in UNIX terminology I've come across is 'lists directories'.

This can seem on the surface to not be that useful; say you currently reside within a directory with 2 subdirectories:

documents music

Using ls documents with no options would give you a listing of the contents of documents as you correctly state above. Using ls -d documents will merely print the name - since the path to that folder, relative to where you currently reside - is the same as it's name - documents! This can be expanded on (though somewhat redundant in it's basic usage) to ls -d $PWD/* which will display all files and folders, but with their working directories (hence the PWD - previous working directories).

It does have a useful function when combined with the * operator - ls -d */ will display ONLY the directories from within your current working directory.

Turning the focus to the symbolic link part of the definition, if you were to use ls -d ~- a tilde expansion - it would print the path of the current HOME directory. This could then be used with varying applications (dependent on the OS) and does have some practical use; you could modify your statement further to ls -d ~your-username, ls -d ~another-username or ls -d ~root and be provided with the HOME path for those users. A further example of this can be seen in the apache server environment, with the use of a username here similarly displaying the path to their hosting space (their HOME directory, relatively speaking).

There are various functions that can be used in combination with this, but the above covers the core function behind the operator - in short, -d is an operator to display specifically directory/path information. There's a nice code generator to play with the ls function (including some -d functionality) if you want to investigate further: ls code generator.

Answer 2

ls by itself, with no options or anything, will "list the current directory." By default, "listing a directory" refers to the files that are contained in it.

The -d flag changes ls not to list the files within the specified directory, but to list the information about the directory itself. It is not, as you mistakenly thought, referring to "directories in the current directory." It is only referring to "the current directory."

This is why ls -d only returns . .

Answer 3

Not sure about the terminology but ls -d just lists info about the thing that follows and nothing more, ie it does NOT expand directory lists, so:

ls -ld /usr/bin

will just give you one line of output about /usr/bin itself.

And

ls -ld *

will just give you info about each file or directory in the pwd but won't also expand any of the directories to list their contents.

As already mentioned you can use find to list directories, and still use ls -d if you like:

find /usr/bin -type d -exec ls -ld {} \;

that's to find all directories under /usr/bin in case it's not clear.

Answer 4

ls -d is same as ls -d . Before executing the ls command, bash shell will expand any wild cards. The -d option instructs ls to just list the information about the passed argument and not its contents regardless of the argument is a directory or file.

To explain further, take the example of ls .*; the expectation is that it will list all files and directories that have . as the prefix. But, when bash expands the wildcard * it includes . and .. as well. You can verify the output of bash expansion by checking output of echo .* command. For each argument ls .* received after bash expanded the * (which includes . and ..) , it will list the contents if the argument is a directory. The result is some output that is not what you expected.

If you use ls -d .* instead, the '-d' option instructs to list details of only the argument and not its contents even if it is a directory. Now this gives you the output you expected.