bug#7433: ls: [manual] description for --directory is insufficient

[Eric Blake]

On 11/18/2010 05:46 AM, Jari Aalto wrote:
> Package: coreutils
> Version: 8.5-1
> Severity: normal
> 
> [Forwarded from http://bugs.debian.org/603895 ]

Thanks for the report.

> 
> Manual page of ls(1) reads:
> 
>        -d, --directory
>               list directory entries instead of contents, and do not  derefer-
>               ence symbolic links

Which is generated from the 'ls --help' output.

> None of these is helpful in understanding how the option is supposed
> to work:
> 
>     ls -d

The wording for -d may not mention it, but the wording at the very
beginning of the --help and man page is clear that:

| Usage: ls [OPTION]... [FILE]...
| List information about the FILEs (the current directory by default).

That is, 'ls -d' is the same as 'ls -d .', as required by POSIX, at
which point you are listing the current directory as a file, and not the
contents of the current directory.

>     ls -dR

When listing directories as files (-d), no recursion (-R) takes place
because no directories are encountered, just files.  Again, this
behavior is required by POSIX.

What wording change, if any, can you propose for the --help output that
would not make things too verbose for what is supposed to be a quick
reference?

> After lot of Google, a miracle command syntax is found:
> 
>     ls -d */

Yes, that says list all directories (and symlinks to directories) in the
current directory, that don't start with leading ., as a file.

> Please improve the documentation and give examples. Btw, the command
> syntax "*/" is counterintuitive to rest of the ls(1) behavior:
> 
>        ls -a    vs.    ls -d

Yes, comparing these two in the info pages would be a useful addition
(although I'm not sure that we should bloat the already-long --help
output for this).  Could you propose a patch?

-- 
Eric Blake   address@hidden    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature