bug#21218: ls -d

[Sneeh, Eddie]

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 <address@hidden> 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