Using ls command with symbolic links

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@

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.