bug#21218: ls -d

[Assaf Gordon]

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