13

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.

Gilles 'SO- stop being evil'
  • 807,993
  • 194
  • 1,674
  • 2,175
bmcentee148
  • 233
  • 1
  • 2
  • 5
  • With GNU 8.26 `ls` unaliased, I see the same behavior the OP sees. – John1024 Feb 18 '18 at 22:57
  • FWIW I see the same with 8.29. – Sparhawk Feb 18 '18 at 23:07
  • 1
    Possible duplicate of [How to ls using the long format (-l) while still following directory symlinks?](https://unix.stackexchange.com/questions/56197/how-to-ls-using-the-long-format-l-while-still-following-directory-symlinks) – Sparhawk Feb 18 '18 at 23:12
  • dear me, you seem quite correct. Apparently adding `-F` makes it act differently, as well as `-l` does. – ilkkachu Feb 18 '18 at 23:13
  • 1
    @Sparhawk I disagree with the duplicate. Our questions are different. I understood how to follow directory symlinks when using the `-l` option as shown in my example code. I wanted to know why other options were necessary to achieve this following when other instances of `ls` followed it automatically. To me the description of the `-H` option in `ls`'s man page makes it sound like the option is always necessary to follow the links when it is not, as noted in the answers below. – bmcentee148 Feb 19 '18 at 02:22
  • @bmcentee148 Understood. I've retracted my close vote. – Sparhawk Feb 19 '18 at 03:52

2 Answers2

9

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.

Gilles 'SO- stop being evil'
  • 807,993
  • 194
  • 1,674
  • 2,175
4

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@
ilkkachu
  • 133,243
  • 15
  • 236
  • 397
  • Many thanks for this answer! Incidentally, there's an https version of the POSIX URL that the post links to, if you'd be willing to edit/update it? (Also: that is a very cool avatar picture.) – AJM Apr 05 '23 at 09:06