Using ls command with symbolic links

Question

I currently do not understand what is going on when I try to find the contents of or information for a symbolic link to a directory when using the ls command. I understand there is an option -H for the ls command that will follow symbolic links listed on the command line. What the manual page for ls does not state is that this is only necessary when using the -l option. If I simply do something like ls symLinkToDir it will list the linked directories contents with no additional options. But if I do ls -l symLinkToDir it will only display information about the link UNLESS I include the -H option as well. This example is what I am talking about:

brian@LinuxBox:~$ ls playground/linkedDir
file4  file5
brian@LinuxBox:~$ ls -l playground/linkedDir
lrwxrwxrwx 1 brian brian 4 Feb 18 16:42 playground/linkedDir -> dir2
brian@LinuxBox:~$ ls -lH playground/linkedDir
total 0
-rw-rw-r-- 1 brian brian 0 Feb 18 16:41 file4
-rw-rw-r-- 1 brian brian 0 Feb 18 16:41 file5

Am I not understanding something here? Is this just a weird way of how it works? If this is indeed how it works, shouldn't the manual page say the symbolic link will be followed under certain conditions without the need for the -H option? Thanks in advance for your input.

Solution 1

The behavior of ls on symbolic links to directories depends on many options, not just -l and -H. In the absence of symlink behavior options (-L, -H), ls symlinkToDir displays the contents of the directory, but ls -l symlinkToDir, ls -d symlinkToDir and ls -F symlinkToDir all display information about the symbolic link.

If you're reading the man page of the GNU implementation of ls, it doesn't give the full story. GNU man pages are just summaries. The full documentation is in the Info manual (info ls), usually available in HTML these days. I can't find the default behavior on symlinks to directories in the Info manual either, though, this may be a bug in the documentation.

The FreeBSD man page, for example, is more precise, but you have to read the description of the -H option to find the default behavior.

-H Symbolic links on the command line are followed. This option is assumed if none of the -F, -d, or -l options are specified.

If you want a more formal description (but less easy to read), read the POSIX specification. This won't have the extensions of your implementation.

If one or more of the -d, -F, or -l options are specified, and neither the -H nor the -L option is specified, for each operand that names a file of type symbolic link to a directory, ls shall write the name of the file as well as any requested, associated information. If none of the -d, -F, or -l options are specified, or the -H or -L options are specified, for each operand that names a file of type symbolic link to a directory, ls shall write the names of files contained within the directory as well as any requested, associated information.

Solution 2

Apparently that's required by POSIX:

If none of the -d, -F, or -l options are specified, or the -H or -L options are specified, for each operand that names a file of type symbolic link to a directory, ls shall write the names of files contained within the directory as well as any requested, associated information.

I can only assume it's there because without -F or -l, a link to a directory looks just like an actual directory, and so ls $link_to_dir might as well act the same as ls $dir.

With link pointing to dir, the dir and the link look the same side-to-side in a listing, and they act the same when used on the command line:

$ ls
dir  link
$ ls dir
bar  foo
$ ls link
bar  foo

but -F reveals the difference:

$ ls -F 
dir/  link@
$ ls -F dir
bar  foo
$ ls -F link
link@