Subject: bug#21218: ls -d

From: "Sneeh, Eddie" <[email-masked]>
Date: Mon, 10 Aug 2015 16:24:10 -0700

Hi Assaf, I appreciate the thought and effort that went into constructing
your reply.

If you agree that the man pages are intended for all users, not just sys
admins, then the definition of a directory would be a container of other
things (files, links, directories).   It does not mean a regular file.
 (Let's take devices/sockts/etc... out of the discussion.  The majority of
people don't deal with them.)

Based on this definition of "directory", and keeping things simple and
logical, if I wanted a listing of directories/files/links, what makes sense
to me is ls (the definition being *list directory contents*).  If I wanted
to look for specific patterns, then find may be a better choice.  Your
example: ls -d b* does list directories at the current level (and it
doesn't descend into subdirectories -- that's good), but it also lists
*files* and *links* starting with the letter b!
Try \ls -d d* f* l*
It's going to list directories, and files and links.  (in my example, d:
directory, f: file, l: slink)

I guess what it boils down to is "-d" is a confusing choice of option for
what it really does.  "ls --directory" has little to do with directories,
(and adding the word "themselves" to the definition doesn't really remove
much ambiguity), -d lists everything at one level, non-directories included!

Again, imho, what I suggested is more intuitive:
ls -d (list directories)
ls -f (list files)
ls -l (list links)
The current -d should have been something like: --1level or --dont_descend
or the like.
I understand it's very difficult and late for any changes to happen.
Thanks for listening!  Your detailed response was, again, very much
appreciated!

Eddie

On Mon, Aug 10, 2015 at 1:36 PM, Assaf Gordon <[email-masked]> wrote:

> Hello Eddie,
>
> (replying to your two last messages together)
>
> On Mon, Aug 10, 2015 at 12:09:21PM -0700, Sneeh, Eddie wrote:
>
>> Hi Eric, thanks for the quick response and clarification.  I wasn't
>> completely clear what -d was supposed to do exactly.  The man pages define
>> ls -d as:
>> *"list directory entries instead of contents".*
>>
>
> The wording above is perhaps not clear, and indeed, recent versions of GNU
> coreutils it have been re-worded to:
>
>     -d
>     --directory
>          List just the names of directories, as with other
>          types of files, rather than listing their contents.
>     (in
> http://www.gnu.org/software/coreutils/manual/html_node/Which-files-are-listed.html#Which-files-are-listed
> )
>
> And:
>     -d, --directory      list directories themselves, not their contents
>
     (from 'ls --help' or 'man ls')

>
> POSIX explains it as so:
>
>     -d
>     [...] Do not treat directories differently than other types of files.
>     (in http://pubs.opengroup.org/onlinepubs/9699919799/utilities/ls.html)
>
> And OpenBSD explains it as:
>
>     -d      Directories are listed as plain files
>     (from 'man ls' on OpenBSD - this is not GNU Coreutils' ls)
>
> The term "directory entries" refers to the technical item of a "file
> system entry", which represent the information about the directory itself
> (e.g. when was it created and who is the owner). This term was indeed
> confusing, and so it was changed in 2013 in this commit:
>
> http://git.savannah.gnu.org/cgit/coreutils.git/commit/?id=da398ae5dfa43efda48310899c24242da4764f44
>
> To give a concrete example:
>
>     # This means: list information about files INSIDE directory f1
>     ls -l f1
>
>     # This means: list information about directory f1 itself
>     # (such as who is the owner, access permissions,
>     # and when was it created)
>     ls -ld f1
>
> (replying to your second message):
>
> On 08/10/2015 03:40 PM, Sneeh, Eddie wrote:
>
>> Hi Bob, thanks for the info.
>> If ya'll don't want to consider this a bug, that's fine, but I suggest
>> updating the definition for -d to clarify the true behavior.
>>
>
> The wording has been already updated, so that's fixed.
>
> I'm yet to see the usefulness of this option (used alone), other than in
>> Eric's example, which is what I was after.
>> If someone has some examples of ls -d usage, _without adding other
>> switches_ , I'd appreciate it.
>>
>
> I can give a contrived example, but hopefully it will demonstrate that
> there are some uses cases.
>
> Imagine the following content of a directory:
>
>     touch a1 a2 a3 b1 b2 b3
>     mkdir b4
>     touch b4/foo
>
> To list everything, typing 'ls' would suffice:
>
>     $ ls
>     1  2  3  4  6  a1  a2  a3  b1  b2  b3  b4
>
> Now, I want to see only 'things' starting with 'b'.
> Note that by 'things' I mean both files and directories.
> From a purely technical POV, on many file-systems
> a 'directory' is just a file, but with a different file-system type,
> so sometimes technical purists will say 'files' and also mean directories
> (and similarly, special devices, named fifos, sockets - they are all
> 'files').
> back to listing things starting with 'b':
>
>     $ ls b*
>     b1  b2  b3
>
>     b4:
>     foo
>
> The above might be unexpected output. Because 'b4' is a directory, ls
> entered it and listed its content (foo).
> If I want to see only list of things (=files,directories,everything),
> that's where '-d' comes in handy:
>
>     $ ls -d b*
>     b1 b2 b3 b4
>
> For now, I like your solution: ls -d */   which I'll be using instead of
>> the find command.
>>
>
> If you use 'ls */' to view directories interactively, that's fine.
>
> If you use it for any kind of scripting (e.g. in a shell for/while loop or
> xargs), then it is highly recommended to use 'find' instead of 'ls' - a
> file containing any kind of funky characters (spaces, tabs, newlines, etc.)
> might confuse your script and cause unintended conseqeunces.
>
> To save some typing, you can create the following shell function
> (e.g. in your '~/.bashrc' file):
>
>     lsd(){ find ${1:-.} -mindepth 1 -maxdepth 1 -type d -printf "%f\n";}
>
> And then run 'lsd' or 'lsd DIR' to list the current or the specified
> directory.
>
> In scripting, it is recommended to use '-print0' to prevent issues
> with files that might contain whitespaces, e.g.:
>
>     find DIR -mindepth 1 -maxdepth 1 -type d -print0 \
>         | xargs -0 -I% echo "Processing directory %"
>
>
> Regards,
>  - assaf
>

-- 
Best Regards,
*Eddie Sneeh*