Subject: bug#71171: closed (Re: bug#71171: ls -U, -f: document the other half of the story too)

From: [email-masked] (GNU bug Tracking System)
Date: Fri, 24 May 2024 15:50:02 +0000

Your bug report

#71171: ls -U, -f: document the other half of the story too

which was filed against the coreutils package, has been closed.

The explanation is attached below, along with your original report.
If you require more details, please reply to [email-masked].

-- 
71171: https://debbugs.gnu.org/cgi/bugreport.cgi?bug=71171
GNU Bug Tracking System
Contact [email-masked] with problems

Subject: Re: bug#71171: ls -U, -f: document the other half of the story too
From: Paul Eggert <[email-masked]>
To: Dan Jacobson <[email-masked]>
Cc: [email-masked]
Date: Fri, 24 May 2024 08:49:04 -0700
List-Id: <debbugs-submit.debbugs.gnu.org>

Thanks, I installed the attached. This doesn't exactly match your 
suggestion (as ls --help shouldn't be that chatty) but should address 
the issues you raised. Some of those issues had already been fixed in 
the development branch.

From 9290066de069ce5ffdc6e8ea531ba14a72d36e3f Mon Sep 17 00:00:00 2001
From: Paul Eggert <[email-masked]>
Date: Fri, 24 May 2024 08:42:14 -0700
Subject: [PATCH] ls: improve sorting doc

Problem reported by Dan Jaobson (Bug#71171).
* doc/coreutils.texi: Clarify that directory entries are sorted,
not command-line arguments.
* src/ls.c (usage): Be less chatty about -U and
about --group-directories-first.
---
 doc/coreutils.texi | 40 ++++++++++++++++++++++------------------
 src/ls.c           |  7 ++-----
 2 files changed, 24 insertions(+), 23 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 3762c6f96..1fa7f79ad 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -7640,7 +7640,8 @@ non-option argument is specified, @command{ls} operates on the current
 directory, acting as if it had been invoked with a single argument of @samp{.}.
 
 @vindex LC_ALL
-By default, the output is sorted alphabetically, according to the locale
+By default, @command{ls} lists each directory's contents alphabetically,
+according to the locale
 settings in effect.@footnote{If you use a non-POSIX
 locale (e.g., by setting @env{LC_ALL} to @samp{en_US}), then @command{ls} may
 produce output that is sorted differently than you're accustomed to.
@@ -7747,16 +7748,6 @@ or any of the following options is in effect:
 @option{--dereference} (@option{-L}), or
 @option{--dereference-command-line} (@option{-H})).
 
-@item --group-directories-first
-@opindex --group-directories-first
-Group all the directories before the files and then sort the
-directories and the files separately using the selected sort key
-(see @option{--sort} option).
-That is, this option specifies a primary sort key,
-and the @option{--sort} option specifies a secondary key.
-However, any use of @option{--sort=none}
-(@option{-U}) disables this option altogether.
-
 @item --hide=PATTERN
 @opindex --hide=@var{pattern}
 In directories, ignore files whose names match the shell pattern
@@ -8137,9 +8128,12 @@ In long format, print the security context to the left of the size column.
 @subsection Sorting the output
 
 @cindex sorting @command{ls} output
-These options change the order in which @command{ls} sorts the information
-it outputs.  By default, sorting is done by character code
-(e.g., ASCII order).
+@vindex LC_COLLATE
+These options change the order in which @command{ls} outputs
+information for the files in a directory.
+(Command-line operands are always processed left to right.)
+By default, files are sorted alphabetically by name, using the
+character collating sequence specified by the @env{LC_COLLATE} locale.
 
 @table @samp
 
@@ -8160,9 +8154,19 @@ sort according to the ctime.  @xref{File timestamps}.
 @opindex -f
 @cindex unsorted directory listing
 @cindex directory order, listing by
-Produce an unsorted listing of all directory entries.
-This is like @option{--all} (@option{-a}) combined
-with @option{--sort=none} (@option{-U}).
+Do not sort, and list all files.
+This is like @option{--sort=none} (@option{-U}) combined
+with @option{--all} (@option{-a}).
+
+@item --group-directories-first
+@opindex --group-directories-first
+When listing a directory's files,
+group all subdirectories before non-directories
+and then sort the subdirectories and the non-directories separately.
+That is, this option specifies a primary sort key,
+and the other sorting options specify a secondary key.
+However, any use of @option{--sort=none}
+(@option{-U}) disables this option altogether.
 
 @item -r
 @itemx --reverse
@@ -8401,7 +8405,7 @@ Specifying @option{--hyperlink} and no @var{when} is equivalent to
 
 @item --indicator-style=@var{word}
 @opindex --indicator-style
-Append a character indicator with style @var{word} to entry names,
+Append a character indicator with style @var{word} to file names,
 as follows:
 
 @table @samp
diff --git a/src/ls.c b/src/ls.c
index 916d7c050..5e2f7c3e7 100644
--- a/src/ls.c
+++ b/src/ls.c
@@ -5478,10 +5478,7 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
 "), stdout);
       fputs (_("\
       --group-directories-first\n\
-                             group directories before files;\n\
-                             can be augmented with a --sort option, but any\n\
-                             use of --sort=none (-U) disables grouping\n\
-\n\
+                             group directories before files\n\
 "), stdout);
       fputs (_("\
   -G, --no-group             in a long listing, don't print group names\n\
@@ -5605,7 +5602,7 @@ Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.\n\
 \n\
 "), stdout);
       fputs (_("\
-  -U                         do not sort; list entries in directory order\n\
+  -U                         do not sort directory entries\n\
 "), stdout);
       fputs (_("\
   -v                         natural sort of (version) numbers within text\n\
-- 
2.43.0

Subject: ls -U, -f: document the other half of the story too
From: Dan Jacobson <[email-masked]>
To: [email-masked]
Date: Fri, 24 May 2024 10:32:04 +0800
List-Id: <debbugs-submit.debbugs.gnu.org>

Man ls says:
       -U     do not sort; list entries in directory order
Please make it say:
       -U     do not sort; list entries in the order they were given on
       the command line, and files within directories using their
       directories' order

And on (info "(coreutils) Sorting the output") please change:

‘-U’
‘--sort=none’
     Do not sort; list the files in whatever order they are stored in
     the directory.  (Do not do any of the other unrelated things that
     ‘-f’ does.)  This can be useful when listing large directories,
     where sorting can take some time.

to instead say:

‘-U’
‘--sort=none’
     Do not sort; list the files in the order they were given on the
     command line, and files within directories in whatever order they
     are stored in the directory. (Do not do any of the other unrelated
     things that ‘-f’, above, does.) This can be useful when listing
     large directories, where sorting can take some time.

Proof:

$ echo $PATH | tr -s : \\n
/home/jidanni/bin
/usr/local/sbin
/usr/local/bin
/usr/local/games
/usr/sbin
/usr/bin
/usr/games
/sbin
/bin
$ echo $PATH | tr -s : \\n | xargs ls -Uogd
drwxr-xr-x 1   632 05-24 05:47 /home/jidanni/bin
drwxr-xr-x 1     0 04-17 12:34 /usr/local/sbin
drwxr-xr-x 1     0 04-17 12:34 /usr/local/bin
drwxr-xr-x 1     0 04-17 12:34 /usr/local/games
drwxr-xr-x 1  6028 05-23 07:42 /usr/sbin
drwxr-xr-x 1 19542 05-23 20:01 /usr/bin
drwxr-xr-x 1     0 01-29 05:20 /usr/games
lrwxrwxrwx 1     8 04-17 12:34 /sbin -> usr/sbin
lrwxrwxrwx 1     7 04-17 12:34 /bin -> usr/bin

Above, -U thankfully allows me to keep the output in the order I gave it!

Wait,
man ls:
     -f     list all entries in directory order

Same problems all over again with -f documentation.

So please also update the man ls and Info ls "-f" discussions to include
the command line order, as I did above for -U. Thanks.

ls (GNU coreutils) 9.4