GNU bug report logs - #7433
doc: ls: improve -d/--directory description

Previous Next

Full log

View this message in rfc822 format

From: Eric Blake <eblake <at> redhat.com>
To: Jari Aalto <jari.aalto <at> cante.net>
Cc: 7433 <at> debbugs.gnu.org, 603895 <at> bugs.debian.org
Subject: bug#7433: ls: [manual] description for --directory is insufficient
Date: Thu, 18 Nov 2010 08:16:56 -0700

[Message part 1 (text/plain, inline)]

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   eblake <at> redhat.com    +1-801-349-2682
Libvirt virtualization library http://libvirt.org

[signature.asc (application/pgp-signature, attachment)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.