GNU bug report logs - #14189
ls -d bug ??

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 14189 in the body.
You can then email your comments to 14189 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: "ray <at> electronicstheory.com" <ray <at> electronicstheory.com>
To: bug-coreutils <at> gnu.org
Subject: ls -d bug ??
Date: Thu, 11 Apr 2013 13:17:05 -0500 (CDT)

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

To: The most gracious and brilliant authors of the ever useful ls command.
(The title is quite heartfelt - no sarcasm intended).

I have to wonder.  I've been using *nix of various kinds for nigh unto 15 years.
 I ran into an issue today that I've seen many times, and it still irks me.
 I've simply never taken the time to write to anyone about it.  I assumed
someone would report it and it would be magically fixed in the next version, but
it never seems to.

I've also seen several people elude to the same problem in forums, etc.

Once in a blue moon, a person would like to view the subdirectories of the
directory you are in, without seeing all the various files.

Since you can use the ls command to view the files and directories that are
contained in your pwd, one would THINK the intuitive method would be to type ls
-d.

Interestingly, the MAN page seems to indicate that this is the way to go,
however, regardless of what directory you are in, if you type

ls -d

you don't get the expected result, but rather you get:

.

Which is like ls is telling you, "Yup, you are in a directory!"

Wull DUH, like I couldn't figure out that I was in a directory.  If I wanted to
get more info on that I'd type pwd !

tree -dx ALMOST gives you the desired outcome, except it includes all the
subdirectories of the subdirectories.

ls -d, I would think, would tell you the same data that ls would tell you, minus
the individual files.
(In  other words - show all the data with a "d" in the permissions, but not show
the ones that don't have a "d" in the permissions).

I'm not afraid to admit I may be missing the whole point (pardon the pun).  Is
it me, or am I just not understanding the importance of the " . ", and how that
. might change from one directory to another?

WHY does ls -d just give me a dot?  Is  that dot supremely important?  Is there
some reason it can't give me what (it appears) the manual says (and what makes
sense) it should?


Ray Dall
Radio Frequency Engineer
Author: Electronics for Sound Engineers

This email sent via a virus free Linux computer.

[Message part 2 (text/html, inline)]

Message #8 received at 14189 <at> debbugs.gnu.org (full text, mbox):

From: Assaf Gordon <assafgordon <at> gmail.com>
To: "ray <at> electronicstheory.com" <ray <at> electronicstheory.com>
Cc: 14189 <at> debbugs.gnu.org
Subject: Re: bug#14189: ls -d bug ??
Date: Thu, 11 Apr 2013 16:56:16 -0400

Hello Ray,

Others can provide more detailed information about the rational of the "dot" file,
but regarding your questions:

ray <at> electronicstheory.com wrote, On 04/11/2013 02:17 PM:
> Once in a blue moon, a person would like to view the subdirectories of the
> directory you are in, without seeing all the various files.

"find -type d" will list all directories (but will do so recursively).
"find -maxdepth 1 -type d" will list only directories immediately under your current directory.

Since it's "once in a blue moon" (as you've said), I guess there's no "short form" for that.

If you need the extended information that "ls" provides:
  find -maxdepth 1 -type d -print0 | xargs -0 ls -ld

<...>

> 
> Interestingly, the MAN page seems to indicate that this is the way to go,
> however, regardless of what directory you are in, if you type
> 
> ls -d
> 

One use-case for "-d" is to show the information about the directory, instead of the *content* of the directory.

Compare:
  ls -l /etc
vs.:
  ls -ld /etc

HTH, 
 -gordon

Message #11 received at 14189 <at> debbugs.gnu.org (full text, mbox):

From: Bob Proulx <bob <at> proulx.com>
To: "ray <at> electronicstheory.com" <ray <at> electronicstheory.com>
Cc: 14189 <at> debbugs.gnu.org
Subject: Re: bug#14189: ls -d bug ??
Date: Thu, 11 Apr 2013 15:13:19 -0600

tags 14189 + notabug
close 14189
thanks

http://www.gnu.org/software/coreutils/faq/#ls-_002dd-does-not-list-directories_0021

ray <at> electronicstheory.com wrote:
> Once in a blue moon, a person would like to view the subdirectories of the
> directory you are in, without seeing all the various files.

Thank you for your report.  However what you are reporting is due to a
misunderstanding of the usage of the command.

> Since you can use the ls command to view the files and directories that are
> contained in your pwd, one would THINK the intuitive method would be to type ls
> -d.

But that is not correct.  And it isn't as documented.

> Interestingly, the MAN page seems to indicate that this is the way to go,

You have fallen into a trap.  The computer is executing a program and
does *exactly* what it was programmed to do.  The documentation is
written to say exactly what the program does.  But you are thinking
like a human and making an interpretation and an extrapolation based
upon what you *want* it to do.  Those are different things.

The GNU ls documentation says this:

  `-d'
  `--directory'
     List just the names of directories, as with other types of files,
     rather than listing their contents.  Do not follow symbolic links
     listed on the command line unless the `--dereference-command-line'
     (`-H'), `--dereference' (`-L'), or
     `--dereference-command-line-symlink-to-dir' options are specified.

The GNU ls man page says:

   -d, --directory
     list directory entries instead of contents, and do not
     dereference symbolic links

The online standards documents say:

  http://pubs.opengroup.org/onlinepubs/009695399/utilities/ls.html
  -d
    Do not follow symbolic links named as operands unless the -H or -L
    options are specified.  Do not treat directories differently than
    other types of files.  The use of -d with -R produces unspecified
    results.

Each and every one of those applies the -d option to the arguments of
the ls command.  But what are the arguments to ls?  If you type in ls
with an argument then there is no doubt.

  $ mkdir foodir
  $ touch foodir/foofile1
  $ ls foodir
  foofile1

At that point there is no doubt.  You are asking it to list foodir.
Let's apply the -d option.

  $ ls -d foodir
  foodir

The -d option clearly applies to foodir.  Therefore it prevents it
from listing the contents.  It lists only the name of the directory.
This is as documented for -d that it lists only names and using -d
prevents it from listing the directory argument contents.

But what happens if you don't give ls an option?  What is the default
argument to ls?  The GNU ls documentation says:

  10.1 `ls': List directory contents
  ==================================

  The `ls' program lists information about files (of any type, including
  directories).  Options and file arguments can be intermixed
  arbitrarily, as usual.

     For non-option command-line arguments that are directories, by
  default `ls' lists the contents of directories, not recursively, and
  omitting files with names beginning with `.'.  For other non-option
  arguments, by default `ls' lists just the file name.  If no non-option
  argument is specified, `ls' operates on the current directory, acting
  as if it had been invoked with a single argument of `.'.

That last line says it.  Let me repeat it for emphasis.

  If no non-option argument is specified, `ls' operates on the current
  directory, acting as if it had been invoked with a single argument
  of `.'.

If no arguments are specified then ls lists '.' as if it had been
invoked "ls .".

> however, regardless of what directory you are in, if you type
> 
> ls -d

If you run "ls -d" then we know from the documentation that it is the
same as saying "ls -d ." and that will simply list the name of it
because the -d option says only list the names of directories.
Therefore the expected behavior is that it must only list the name of
the '.' directory.

> you don't get the expected result, but rather you get:
> .

Unfortunately you had incorrect expectations! :-)

Any other result would be a bug.  I hope I have convinced you that
that ls is doing the right thing here and behaving as documented even
if it isn't doing what you want it to do.

This is a common misunderstanding and is one of the FAQ entries.
Please read the FAQ entry here:

  17 ls -d does not list directories!
  http://www.gnu.org/software/coreutils/faq/#ls-_002dd-does-not-list-directories_0021

> Wull DUH, like I couldn't figure out that I was in a directory.  If I wanted to
> get more info on that I'd type pwd !

If you didn't want it to list only the name of the directory and not
the contents then why did you use the -d option?  Since -d
specifically prevents it from listing the contents.

> ls -d, I would think, would tell you the same data that ls would tell you, minus
> the individual files.
> (In  other words - show all the data with a "d" in the permissions, but not show
> the ones that don't have a "d" in the permissions).

Perhaps you want this?

  $ ls -log | grep ^d
  $ ls -log | grep -v ^d

Or one of these:

  $ find . -maxdepth 1 -type d -ls
  $ find . -maxdepth 1 -type d -exec ls -logd {} +

I definitely recommend reading about "find".  It is an extremely
useful command.  Knowledge of it will apply to all of the utilities
uniformly.

I have gone ahead and closed this since it isn't a bug.  But please
feel free to continue the discussion.  It will all go into the bug log
and perhaps help the next person who searches for the information.

Bob

Message #18 received at 14189 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: "ray <at> electronicstheory.com" <ray <at> electronicstheory.com>
Cc: 14189 <at> debbugs.gnu.org
Subject: Re: bug#14189: ls -d bug ??
Date: Thu, 11 Apr 2013 14:20:03 -0700

On 04/11/13 11:17, ray <at> electronicstheory.com wrote:
> Is there
> some reason it can't give me what (it appears) the manual says (and what makes
> sense) it should?

Sounds like there's a bug in the manual; it shouldn't say that
"ls -d" outputs only directories.  Can you please mention
the wording you're talking about?

To get something like what you want, you can use this command:

ls -d */

or maybe:

ls -d */ .*/

Message #21 received at 14189 <at> debbugs.gnu.org (full text, mbox):

From: Eric Blake <eblake <at> redhat.com>
To: Bob Proulx <bob <at> proulx.com>
Cc: "ray <at> electronicstheory.com" <ray <at> electronicstheory.com>,
	14189 <at> debbugs.gnu.org
Subject: Re: bug#14189: ls -d bug ??
Date: Thu, 11 Apr 2013 15:31:15 -0600

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

On 04/11/2013 03:13 PM, Bob Proulx wrote:
> 
> If you didn't want it to list only the name of the directory and not
> the contents then why did you use the -d option?  Since -d
> specifically prevents it from listing the contents.
> 
>> ls -d, I would think, would tell you the same data that ls would tell you, minus
>> the individual files.
>> (In  other words - show all the data with a "d" in the permissions, but not show
>> the ones that don't have a "d" in the permissions).
> 
> Perhaps you want this?
> 
>   $ ls -log | grep ^d
>   $ ls -log | grep -v ^d
> 
> Or one of these:
> 
>   $ find . -maxdepth 1 -type d -ls
>   $ find . -maxdepth 1 -type d -exec ls -logd {} +

Or you could use this to approximate things:

$ ls -d */

the trailing slash forces the shell to filter out non-directories as
part of expanding the glob, and then list just the names instead of the
contents of all remaining directories.  But as written that only lists
non-hidden directories.  If you don't mind listing '.', you can get
closer with:

$ ls -d */ .*/

But for a full list of all subdirectory names excluding '.' and '..',
you need three globs; and either a shell option that suppresses a glob
that has no match, or ignoring the errors when ls tries to warn you when
a glob doesn't match:

Portable (but risks hiding errors):
$ ls -d */ .[!.]/ .??*/ 2>/dev/null

bash-specific:
$ (shopt -s nullglob; ls -d */ .[!.]/ .??*/)

All the sudden, the 'find' alternative suddenly seems nicer :)

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

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

Message #24 received at 14189 <at> debbugs.gnu.org (full text, mbox):

From: Eric Blake <eblake <at> redhat.com>
Cc: "ray <at> electronicstheory.com" <ray <at> electronicstheory.com>,
	14189 <at> debbugs.gnu.org, Bob Proulx <bob <at> proulx.com>
Subject: Re: bug#14189: ls -d bug ??
Date: Thu, 11 Apr 2013 15:41:31 -0600

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

On 04/11/2013 03:31 PM, Eric Blake wrote:
> But for a full list of all subdirectory names excluding '.' and '..',
> you need three globs; and either a shell option that suppresses a glob
> that has no match, or ignoring the errors when ls tries to warn you when
> a glob doesn't match:
> 
> Portable (but risks hiding errors):
> $ ls -d */ .[!.]/ .??*/ 2>/dev/null

Be aware that this also runs the risk of generating too long of a
command line if the globs expand to a lot of names; while find
specifically avoids exceeding command line length limits.  On the other
hand, while ls defaults to sorting its output, find does not; so if you
need sorted output, you have to start considering the use of non-POSIX
extensions such as GNU find's -print0 and sort's -z to generate and sort
the list with unambiguous terminators, if you are worried that any of
the names found might contain a newline in the name.

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

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

Message #27 received at 14189 <at> debbugs.gnu.org (full text, mbox):

From: Bob Proulx <bob <at> proulx.com>
To: 14189 <at> debbugs.gnu.org
Cc: "ray <at> electronicstheory.com" <ray <at> electronicstheory.com>
Subject: Re: bug#14189: ls -d bug ??
Date: Thu, 11 Apr 2013 23:42:37 -0600

Bob Proulx wrote:
>   10.1 `ls': List directory contents
>   ==================================
> 
>   The `ls' program lists information about files (of any type, including
>   directories).  Options and file arguments can be intermixed
>   arbitrarily, as usual.
> 
>      For non-option command-line arguments that are directories, by
>   default `ls' lists the contents of directories, not recursively, and
>   omitting files with names beginning with `.'.  For other non-option
>   arguments, by default `ls' lists just the file name.  If no non-option
>   argument is specified, `ls' operates on the current directory, acting
>   as if it had been invoked with a single argument of `.'.

That does seem like it could use some improvement.  It makes the
mistake of "burying the lead" by putting that last sentence so far
down.  I like the BSD man page version much better.  Is there a way we
can simplify this but still keep it descriptive?  The FreeBSD man page
is much better for this description.

How about this?  (I will work it up into a texinfo patch afterward.)

  The `ls' program lists information about files.  If the file being
  listed is a directory then the contents of the directory is listed.

  If no non-option command-line arguments are specified then 'ls'
  operates on the current directory, acting as if it had been invoked
  with a single argument of `.'.  `ls' is the same as `ls .'.

  For each non-option command-line argument that is not a directory
  `ls' lists the file name.  For each non-option command-line argument
  that is a directory `ls' lists the names of files in the directory.
  Files starting with a '.' are ignored and hidden.

WDYT?

> `-d'
> `--directory'
>      List just the names of directories, as with other types of files,
>      rather than listing their contents.  Do not follow symbolic links
>      listed on the command line unless the `--dereference-command-line'
>      (`-H'), `--dereference' (`-L'), or
>      `--dereference-command-line-symlink-to-dir' options are specified.

And then perhaps this following.  Also the above does not describe the
interaction with -R.

Option 1:

  `-d'
  `--directory'
     Do not list the contents of directories.  List only the name.  Do
     not follow symbolic links unless the `--dereference-command-line'
     (`-H'), `--dereference' (`-L'), or
     `--dereference-command-line-symlink-to-dir' options are
     specified.  Overrides `--recursive', (`-R').

Option 2 with much more description:

  `-d'
  `--directory'
     Do not list the contents of directories.  List only the name.
     Without this option any non-option command-line arguments that
     are directories are treated specially and instead of the name the
     contents are listed.  This option turns that behavior off and
     directories are only listed by name, the same as any
     non-directory file.  This is most typically used with `-l' to
     list the information for the directory itself instead of its
     contents.  Do not follow symbolic links unless the
     `--dereference-command-line' (`-H'), `--dereference' (`-L'), or
     `--dereference-command-line-symlink-to-dir' options are
     specified.  Overrides `--recursive', (`-R').

I like the conciseness of the first.  But the extra description in the
second seems useful.

WDYT?

Bob

Message #30 received at 14189 <at> debbugs.gnu.org (full text, mbox):

From: Bob Proulx <bob <at> proulx.com>
To: 14189 <at> debbugs.gnu.org
Cc: "ray <at> electronicstheory.com" <ray <at> electronicstheory.com>
Subject: Re: bug#14189: ls -d bug ??
Date: Fri, 12 Apr 2013 00:06:16 -0600

Bob Proulx wrote:
> Option 2 with much more description:
> 
>   `-d'
>   `--directory'
>      Do not list the contents of directories.  List only the name.
>      Without this option any non-option command-line arguments that
>      are directories are treated specially and instead of the name the
>      contents are listed.  This option turns that behavior off and
>      directories are only listed by name, the same as any
>      non-directory file.  This is most typically used with `-l' to
>      list the information for the directory itself instead of its
>      contents.  Do not follow symbolic links unless the
>      `--dereference-command-line' (`-H'), `--dereference' (`-L'), or
>      `--dereference-command-line-symlink-to-dir' options are
>      specified.  Overrides `--recursive', (`-R').

Some local wordsmithing turned out the following as a better
improvement.  It lists what it does in the positive first.  And
removes the negative which was seen as being too confusing.

  `-d'
  `--directory'
     List only the name of directories, not the contents.  This is
     most typically used with `-l' to list the information for the
     directory itself instead of its contents.  Do not follow symbolic
     links unless the `--dereference-command-line' (`-H'),
     `--dereference' (`-L'), or
     `--dereference-command-line-symlink-to-dir' options are
     specified.  Overrides `--recursive', (`-R').

Bob

Message #33 received at 14189 <at> debbugs.gnu.org (full text, mbox):

From: Bernhard Voelker <mail <at> bernhard-voelker.de>
To: Bob Proulx <bob <at> proulx.com>
Cc: 14189 <at> debbugs.gnu.org,
	"ray <at> electronicstheory.com" <ray <at> electronicstheory.com>
Subject: Re: bug#14189: ls -d bug ??
Date: Fri, 12 Apr 2013 09:37:16 +0200

On 04/12/2013 08:06 AM, Bob Proulx wrote:
> Some local wordsmithing turned out the following as a better
> improvement.  It lists what it does in the positive first.  And
> removes the negative which was seen as being too confusing.
> 
>   `-d'
>   `--directory'
>      List only the name of directories, not the contents.  This is
>      most typically used with `-l' to list the information for the
>      directory itself instead of its contents.  Do not follow symbolic
>      links unless the `--dereference-command-line' (`-H'),
>      `--dereference' (`-L'), or
>      `--dereference-command-line-symlink-to-dir' options are
>      specified.  Overrides `--recursive', (`-R').

Not bad, but I'm still missing the point that `-d' changes ls's behavior
for *directory arguments* only.

Furthermore, I don't think mentioning `-l' is of much relevance here.
So this would melt down the first two sentences as follows:

  `-d'
  `--directory'
     For directory arguments, list only the information for the
     directory itself instead of its contents.  Do not follow symbolic
     links unless the `--dereference-command-line' (`-H'),
     `--dereference' (`-L'), or
     `--dereference-command-line-symlink-to-dir' options are
     specified.  Overrides `--recursive', (`-R').

And what about the usage() string?  I'd bet this is still 95% where
users are looking for. Something like the following perhaps?

-  -d, --directory            list directory entries instead of contents,
-                               and do not dereference symbolic links
+  -d, --directory            for directory arguments, list the entry itself
+                               instead of contents, and do not dereference
+                               symbolic links

Have a nice day,
Berny

Message #36 received at 14189 <at> debbugs.gnu.org (full text, mbox):

From: Andreas Schwab <schwab <at> linux-m68k.org>
To: Eric Blake <eblake <at> redhat.com>
Cc: "ray <at> electronicstheory.com" <ray <at> electronicstheory.com>,
	14189 <at> debbugs.gnu.org, Bob Proulx <bob <at> proulx.com>
Subject: Re: bug#14189: ls -d bug ??
Date: Fri, 12 Apr 2013 10:58:15 +0200

Eric Blake <eblake <at> redhat.com> writes:

> bash-specific:
> $ (shopt -s nullglob; ls -d */ .[!.]/ .??*/)

$ (shopt -s dotglob; ls -d */)

Andreas.

-- 
Andreas Schwab, schwab <at> linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Message #39 received at 14189 <at> debbugs.gnu.org (full text, mbox):

From: Bob Proulx <bob <at> proulx.com>
To: 14189 <at> debbugs.gnu.org
Cc: "ray <at> electronicstheory.com" <ray <at> electronicstheory.com>
Subject: Re: bug#14189: ls -d bug ??
Date: Thu, 18 Apr 2013 13:21:30 -0600

Bernhard Voelker wrote:
> Bob Proulx wrote:
> >   `-d'
> >   `--directory'
> >      List only the name of directories, not the contents.  This is
> >      most typically used with `-l' to list the information for the
> >      directory itself instead of its contents.  Do not follow symbolic
> >      links unless the `--dereference-command-line' (`-H'),
> >      `--dereference' (`-L'), or
> >      `--dereference-command-line-symlink-to-dir' options are
> >      specified.  Overrides `--recursive', (`-R').
> 
> Not bad, but I'm still missing the point that `-d' changes ls's behavior
> for *directory arguments* only.

Hmm...  "If an argument is a directory then list only the name of the
directory not the contents.  Otherwise list the name of the file
normally."

Showing this around I had one person who was shocked to learn that
directories were files.  They really wanted this written so that it
acted as if directories and files were completely different things.
I countered that since directores were files, special files, that we
shouldn't make the documentation lead people astray just to make it
fit a wrong model of the machine.

> Furthermore, I don't think mentioning `-l' is of much relevance here.
> So this would melt down the first two sentences as follows:
> 
>   `-d'
>   `--directory'
>      For directory arguments, list only the information for the
>      directory itself instead of its contents.  Do not follow symbolic
>      links unless the `--dereference-command-line' (`-H'),
>      `--dereference' (`-L'), or
>      `--dereference-command-line-symlink-to-dir' options are
>      specified.  Overrides `--recursive', (`-R').
> 

That comment made the person who I worked with wordsmithing that line
very sad.  She was adamant that that tidbit about -l was the only
useful part of the option description.  And I think I agree that for
someone reading the documentation and learning about it that the
connection between -d and -l is important to point out explicitly.
Maybe not this way but in some way I think we need to tie those two
concepts together.

> And what about the usage() string?  I'd bet this is still 95% where
> users are looking for. Something like the following perhaps?
> 
> -  -d, --directory            list directory entries instead of contents,
> -                               and do not dereference symbolic links
> +  -d, --directory            for directory arguments, list the entry itself
> +                               instead of contents, and do not dereference
> +                               symbolic links

I think that is definitely an improvement.  Because "entries" in the
original I think isn't descriptive enough and makes people think
contents instead of just the argument name.  But frankly I still don't
think it flows very well.

If we are already pushed into three lines then let's make use of them.

 -d, --directory              for directory arguments, list the name
			        instead of contents, and do not
			        dereference symbolic links

Or perhaps better is:

 -d, --directory              for directory arguments, list the directory
			        name instead of directory contents,
			        and do not dereference symbolic links

Looking through other options for style I see:

  -L, --dereference          when showing file information for a symbolic
                               link, show information for the file the link
                               references rather than for the link itself

That entry has the same challenge.  It is much wordier.  The "when
showing file information for a symbolic link" is the same task as our
"when showing file information for a directory".  I like the shorter
version "for symbolic link arguments" form.  Perhaps as a separate
improvement we could change it to:

  -L, --dereference          for symbolic link arguments, show information
                               for the target instead of for the link itself

And then perhaps while gaining consistency of description without
decreasing the usefulness of either entry we would gain back the line
that we used above.

Bob

Previous Next

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