GNU bug report logs - #79042
29.4; dired-get-marked-files docstring is incorrect

Previous Next

To reply to this bug, email your comments to 79042 AT debbugs.gnu.org.

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

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

From: Sean McAfee <eefacm <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 29.4; dired-get-marked-files docstring is incorrect
Date: Thu, 17 Jul 2025 13:47:01 -0700

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

Visit a directory with Dired, move to any file, and execute
the following code with eval-expression:

  (dired-get-marked-files nil 'marked)

It returns nil, even though the docstring for dired-get-marked-files
says "If ARG is any other [ie, not an integer] non-nil value, return
the current file name."  This is because the ARG argument is
passed to dired-map-over-marks, which interprets the symbol
"marked" in this way.

For context, I was looking for a way to get a list of marked files, or
nil if no files are explicitly marked.  The docstring for
dired-get-marked-files does not admit such a usage, but it actually is
possible, as described above.


In GNU Emacs 29.4 (build 1, x86_64-pc-linux-gnu, GTK+ Version 3.24.41,
 cairo version 1.18.0) of 2025-01-29 built on system76-pc Windowing
 system distributor 'The X.Org Foundation', version 11.0.12302006 System
 Description: Ubuntu 24.04.1 LTS

Configured using:
 'configure --with-json --with-tree-sitter'

Configured features:
CAIRO DBUS FREETYPE GIF GLIB GMP GNUTLS GSETTINGS HARFBUZZ JPEG JSON
LIBSELINUX LIBXML2 MODULES NOTIFY INOTIFY PDUMPER PNG RSVG SECCOMP SOUND
SQLITE3 THREADS TIFF TOOLKIT_SCROLL_BARS TREE_SITTER WEBP X11 XDBE XIM
XINPUT2 XPM GTK3 ZLIB

Important settings:
  value of $LC_MONETARY: en_US.UTF-8
  value of $LC_NUMERIC: en_US.UTF-8
  value of $LC_TIME: en_US.UTF-8
  value of $LANG: en_US.UTF-8
  value of $XMODIFIERS: @im=ibus
  locale-coding-system: utf-8-unix

Major mode: ELisp/l

Minor modes in effect:
  recentf-mode: t
  emms-mode-line-mode: t
  emms-playing-time-display-mode: t
  emms-playing-time-mode: t
  volatile-highlights-mode: t
  projectile-mode: t
  elisp-slime-nav-mode: t
  global-git-commit-mode: t
  magit-auto-revert-mode: t
  shell-dirtrack-mode: t
  global-flycheck-mode: t
  flycheck-mode: t
  minibuffer-depth-indicate-mode: t
  ido-vertical-mode: t
  global-undo-tree-mode: t
  undo-tree-mode: t
  paredit-mode: t
  override-global-mode: t
  desktop-save-mode: t
  winner-mode: t
  electric-pair-mode: t
  savehist-mode: t
  ido-everywhere: t
  tooltip-mode: t
  global-eldoc-mode: t
  eldoc-mode: t
  show-paren-mode: t
  electric-indent-mode: t
  mouse-wheel-mode: t
  global-prettify-symbols-mode: t
  prettify-symbols-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  buffer-read-only: t
  line-number-mode: t
  transient-mark-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t

Load-path shadows:
~/emacs/ack hides /home/mcafee/.emacs.d/elpa/ack-1.11/ack
/home/mcafee/.emacs.d/elpa/git-commit-20240123.1358/git-commit hides
/home/mcafee/.emacs.d/elpa/magit-20241223.2133/git-commit
/home/mcafee/.emacs.d/elpa/transient-20241224.2234/transient hides
/usr/local/share/emacs/29.4/lisp/transient
/home/mcafee/.emacs.d/elpa/bind-key-20230203.2004/bind-key hides
/usr/local/share/emacs/29.4/lisp/use-package/bind-key
/home/mcafee/.emacs.d/elpa/use-package-20230426.2324/use-package-ensure
hides /usr/local/share/emacs/29.4/lisp/use-package/use-package-ensure
/home/mcafee/.emacs.d/elpa/use-package-20230426.2324/use-package-lint hides
/usr/local/share/emacs/29.4/lisp/use-package/use-package-lint
/home/mcafee/.emacs.d/elpa/use-package-20230426.2324/use-package-core hides
/usr/local/share/emacs/29.4/lisp/use-package/use-package-core
/home/mcafee/.emacs.d/elpa/use-package-20230426.2324/use-package hides
/usr/local/share/emacs/29.4/lisp/use-package/use-package
/home/mcafee/.emacs.d/elpa/use-package-20230426.2324/use-package-bind-key
hides /usr/local/share/emacs/29.4/lisp/use-package/use-package-bind-key
/home/mcafee/.emacs.d/elpa/use-package-20230426.2324/use-package-jump hides
/usr/local/share/emacs/29.4/lisp/use-package/use-package-jump
/home/mcafee/.emacs.d/elpa/use-package-20230426.2324/use-package-diminish
hides /usr/local/share/emacs/29.4/lisp/use-package/use-package-diminish
/home/mcafee/.emacs.d/elpa/use-package-20230426.2324/use-package-delight
hides /usr/local/share/emacs/29.4/lisp/use-package/use-package-delight
~/emacs/japanese hides /usr/local/share/emacs/29.4/lisp/language/japanese
~/emacs/chinese hides /usr/local/share/emacs/29.4/lisp/language/chinese

Features:
(shadow mail-extr emacsbug pulse misearch multi-isearch shortdoc
help-fns radix-tree executable recentf tree-widget conf-mode view vc-git
org-bullets org-element org-persist org-id org-refile avl-tree oc-basic
ol-eww eww xdg url-queue mm-url ol-rmail ol-mhe ol-irc ol-info ol-gnus
nnselect gnus-art mm-uu mml2015 mm-view mml-smime smime gnutls dig
gnus-sum shr pixel-fill kinsoku url-file svg gnus-group gnus-undo
gnus-start gnus-dbus gnus-cloud nnimap nnmail mail-source utf7 nnoo
parse-time gnus-spec gnus-int gnus-range gnus-win ol-docview doc-view
jka-compr image-mode exif ol-bibtex bibtex iso8601 ol-bbdb ol-w3m ol-doi
org-link-doi raku-detect org ob ob-tangle ob-ref ob-lob ob-table ob-exp
org-macro org-src ob-comint org-pcomplete org-list org-footnote
org-faces org-entities noutline outline ob-emacs-lisp ob-core ob-eval
org-cycle org-table ol org-fold org-fold-core org-keys oc org-loaddefs
cal-menu calendar cal-loaddefs org-version org-compat org-macs
gnus-dired dired-launch emms-idapi-browser emms-idapi
emms-idapi-musicbrainz emms-mpris dbus emms-librefm-stream xml
emms-librefm-scrobbler emms-playlist-limit emms-i18n emms-history
emms-score emms-stream-info emms-metaplaylist-mode emms-bookmarks
emms-cue emms-mode-line-icon emms-browser sort emms-volume
emms-volume-sndioctl emms-volume-mixerctl emms-volume-pulse
emms-volume-amixer emms-playlist-sort emms-last-played emms-player-xine
emms-player-mpd tq emms-lyrics emms-url emms-streams emms-show-all
emms-tag-editor emms-tag-tracktag emms-mark emms-mode-line emms-cache
emms-info-native emms-info-native-spc emms-info-native-mp3
emms-info-native-ogg emms-info-native-opus emms-info-native-flac
emms-info-native-vorbis bindat emms-info-exiftool emms-info-tinytag
emms-info-metaflac emms-info-opusinfo emms-info-ogginfo
emms-info-mp3info emms-playlist-mode emms-player-vlc emms-player-mpv
emms-playing-time emms-info emms-later-do emms-player-mplayer
emms-player-simple emms-source-playlist emms-source-file locate
emms-setup emms emms-compat treesit-auto xref-js2 vc vc-dispatcher
js2-mode js c-ts-common treesit cc-mode cc-fonts cc-guess cc-menus
cc-cmds cc-styles cc-align cc-engine cc-vars cc-defs dired-filter f
dired-hacks-utils dired-aux dired-x shell-pop term disp-table ehelp
beginend volatile-highlights iedit iedit-lib
mc-hide-unmatched-lines-mode mc-mark-more tagedit s sgml-mode facemenu
dom mc-cycle-cursors multiple-cursors-core rect dtrt-indent advice
projectile lisp-mnt grep ibuf-ext ibuffer ibuffer-loaddefs
elisp-slime-nav etags fileloop generator xref project magit-submodule
magit-blame magit-stash magit-reflog magit-bisect magit-push magit-pull
magit-fetch magit-clone magit-remote magit-commit magit-sequence
magit-notes magit-worktree magit-tag magit-merge magit-branch
magit-reset magit-files magit-refs magit-status magit magit-repos
magit-apply magit-wip magit-log which-func imenu magit-diff smerge-mode
diff-mode git-commit log-edit message sendmail yank-media puny dired
dired-loaddefs rfc822 mml mml-sec epa epg rfc6068 epg-config mm-decode
mm-bodies mm-encode mail-parse rfc2231 rfc2047 rfc2045 ietf-drums
mailabbrev gmm-utils mailheader pcvs-util add-log magit-core
magit-autorevert autorevert filenotify magit-margin magit-transient
magit-process with-editor shell pcomplete server magit-mode transient
benchmark magit-git magit-base magit-section format-spec cursor-sensor
crm compat compat-30 ido-completing-read+ memoize cus-edit pp cus-load
icons minibuf-eldef flycheck find-func diminish gnus nnheader gnus-util
time-date mail-utils range mm-util mail-prsvr wid-edit autoinsert misc
sanityinc-tomorrow-blue-theme color-theme-sanityinc-tomorrow color
mb-depth files-x ido-vertical-mode undo-tree diff queue ack derived
compile text-property-search paredit edmacro kmacro dash cl-extra
help-mode use-package use-package-ensure use-package-delight
use-package-diminish use-package-bind-key bind-key easy-mmode
use-package-core desktop frameset finder-inf winner elec-pair savehist
hippie-exp comint ansi-osc ansi-color ring thingatpt ido cl
color-theme-sanityinc-tomorrow-autoloads dired-filter-autoloads
dired-launch-autoloads dired-ranger-autoloads
dired-hacks-utils-autoloads dtrt-indent-autoloads emms-autoloads
expand-region-autoloads f-autoloads fix-word flycheck-autoloads
git-link-autoloads git-timemachine-autoloads haskell-mode-autoloads
helm-autoloads helm-core-autoloads async-autoloads magit-autoloads pcase
magit-section-autoloads markdown-mode-autoloads
multiple-cursors-autoloads nov-autoloads paredit-autoloads
projectile-autoloads rx shell-pop-autoloads transient-autoloads
treesit-auto-autoloads volatile-highlights-autoloads wfnames-autoloads
with-editor-autoloads info compat-autoloads js2-mode-autoloads
yasnippet-autoloads package browse-url url url-proxy url-privacy
url-expand url-methods url-history url-cookie generate-lisp-file
url-domsuf url-util mailcap url-handlers url-parse auth-source cl-seq
eieio eieio-core cl-macs password-cache json subr-x map byte-opt gv
bytecomp byte-compile url-vars cl-loaddefs cl-lib rmc iso-transl tooltip
cconv eldoc paren electric uniquify ediff-hook vc-hooks lisp-float-type
elisp-mode mwheel term/x-win x-win term/common-win x-dnd tool-bar dnd
fontset image regexp-opt fringe tabulated-list replace newcomment
text-mode lisp-mode prog-mode register page tab-bar menu-bar rfn-eshadow
isearch easymenu timer select scroll-bar mouse jit-lock font-lock syntax
font-core term/tty-colors frame minibuffer nadvice seq simple cl-generic
indonesian philippine cham georgian utf-8-lang misc-lang vietnamese
tibetan thai tai-viet lao korean japanese eucjp-ms cp51932 hebrew greek
romanian slovak czech european ethiopic indian cyrillic chinese
composite emoji-zwj charscript charprop case-table epa-hook
jka-cmpr-hook help abbrev obarray oclosure cl-preloaded button loaddefs
theme-loaddefs faces cus-face macroexp files window text-properties
overlay sha1 md5 base64 format env code-pages mule custom widget keymap
hashtable-print-readable backquote threads dbusbind inotify
dynamic-setting system-font-setting font-render-setting cairo
move-toolbar gtk x-toolkit xinput2 x multi-tty make-network-process
emacs)

Memory information:
((conses 16 1036589 83243)
 (symbols 48 50195 11)
 (strings 32 279255 11680)
 (string-bytes 1 7740814)
 (vectors 16 101791)
 (vector-slots 8 1879206 240753)
 (floats 8 572 113)
 (intervals 56 52623 352)
 (buffers 984 71))

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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Sean McAfee <eefacm <at> gmail.com>, "79042 <at> debbugs.gnu.org"
 <79042 <at> debbugs.gnu.org>
Subject: RE: [External] : bug#79042: 29.4; dired-get-marked-files docstring is
 incorrect
Date: Thu, 17 Jul 2025 22:42:42 +0000

Good find!

It's not a doc bug, it's a product bug - a regression
introduced in Emacs 29.  In prior versions it works
as the doc says: (dired-get-marked-files nil 'marked)
returns the file name on the current line.

The bug occurs only with symbol `marked' passed as
the second arg.

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

From: Sean McAfee <eefacm <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>, 79042 <at> debbugs.gnu.org
Subject: Re: [External] : bug#79042: 29.4;
 dired-get-marked-files docstring is incorrect
Date: Thu, 17 Jul 2025 20:39:52 -0700

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

On Thu, Jul 17, 2025 at 3:42 PM Drew Adams <drew.adams <at> oracle.com> wrote:

> Good find!
>
> It's not a doc bug, it's a product bug - a regression
> introduced in Emacs 29.  In prior versions it works
> as the doc says: (dired-get-marked-files nil 'marked)
> returns the file name on the current line.
>

Wait, so dired-get-marked-files isn't *supposed* to be able to distinguish
between
a single explicitly marked file and no files being marked?  But that's
information
that I need.  How do I get it, if not with dired-get-marked-files?

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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Sean McAfee <eefacm <at> gmail.com>, "79042 <at> debbugs.gnu.org"
 <79042 <at> debbugs.gnu.org>
Subject: RE: [External] : bug#79042: 29.4; dired-get-marked-files docstring is
 incorrect
Date: Fri, 18 Jul 2025 16:27:36 +0000

>> It's not a doc bug, it's a product bug - a regression
>> introduced in Emacs 29.  In prior versions it works
>> as the doc says: (dired-get-marked-files nil 'marked)
>> returns the file name on the current line.
>
> Wait, so dired-get-marked-files isn't supposed to be able to 
> distinguish between a single explicitly marked file and no files 
> being marked?  But that's information that I need.
> How do I get it, if not with dired-get-marked-files?

Mea culpa.  I shouldn't have said the Emacs 29+ behavior
of recognizing a special `marked' value for ARG is a bug.
(It's maybe not the best way to allow that behavior, but
it's OK.)

And I guess you're right, that that code change made the
`dired-get-marked-files' doc incorrect.  So your report
is a good one.  Sorry for the noise.

`dired-get-marked-files' is pretty much a utility function
for defining commands, i.e., for interactive use, which is
why it returns the file name of the current line if there
are no explicit marks.

You can use macro `dired-map-over-marks' (in Emacs 29+) to
do what you want:

(defun my-marked-files-list (&optional localp distinguish-one-marked)
  "..."
  (delq nil (save-excursion
              (dired-map-over-marks (dired-get-filename localp 'NO-ERROR)
				              'marked
				              nil
				              distinguish-one-marked))))

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

From: Sean McAfee <eefacm <at> gmail.com>
To: Drew Adams <drew.adams <at> oracle.com>
Cc: "79042 <at> debbugs.gnu.org" <79042 <at> debbugs.gnu.org>
Subject: Re: [External] : bug#79042: 29.4;
 dired-get-marked-files docstring is incorrect
Date: Fri, 18 Jul 2025 12:01:20 -0700

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

On Fri, Jul 18, 2025 at 9:27 AM Drew Adams <drew.adams <at> oracle.com> wrote:

> >> It's not a doc bug, it's a product bug - a regression
> >> introduced in Emacs 29.  In prior versions it works
> >> as the doc says: (dired-get-marked-files nil 'marked)
> >> returns the file name on the current line.
> >
> > Wait, so dired-get-marked-files isn't supposed to be able to
> > distinguish between a single explicitly marked file and no files
> > being marked?  But that's information that I need.
> > How do I get it, if not with dired-get-marked-files?
>
> Mea culpa.  I shouldn't have said the Emacs 29+ behavior
> of recognizing a special `marked' value for ARG is a bug.
> (It's maybe not the best way to allow that behavior, but
> it's OK.)
>

I understood, I'm just astonished that the current behavior is
considered a bug, since it seems so useful.  Is there a
compelling reason not to allow dired-get-marked-files to
return nil when no files are explicitly marked, when it's
given a special distinguished value for ARG?  It's a
pattern that's used in many other places.

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

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

From: Drew Adams <drew.adams <at> oracle.com>
To: Sean McAfee <eefacm <at> gmail.com>
Cc: "79042 <at> debbugs.gnu.org" <79042 <at> debbugs.gnu.org>
Subject: RE: [External] : bug#79042: 29.4; dired-get-marked-files docstring is
 incorrect
Date: Fri, 18 Jul 2025 21:08:12 +0000

> I understood, I'm just astonished that the current behavior
> is considered a bug, since it seems so useful.

As I said, I mistakenly said this new (>= Emacs 29)
behavior is a bug.  As you said at the outset, the
`dired-get-marked-files' doc could/should be updated
to reflect this new behavior.  Other functions that
use `dired-map-over-marks' might also need to have
their doc updated for the ARG description.

> Is there a compelling reason not to allow
> dired-get-marked-files to return nil when no files
> are explicitly marked, when it's given a special
> distinguished value for ARG?  It's a pattern that's
> used in many other places.

I gave a reason why I think it hasn't bothered to
allow that: existing uses of `dired-get-marked-files'
are for _commands_ where it's a _feature_ to pick up
the file name on the current line if ARG isn't an
integer and no lines are explicitly marked.  (And of
course those existing commands haven't provided an
interactive way to get an ARG value of `marked'.)

In sum, I think the doc of `dired-get-marked-files'
was based on its behavior, which was based on the
existing uses of it, which was by commands that had
no particular use for the ARG=`marked' behavior and
provided no way to get such a value interactively.

It's _possible_ that `dired-map-over-marks' was
changed without a lot of thought about all of its
existing or possible new uses.  I don't know.

With Emacs 29 changing `dired-map-over-marks' to
recognize ARG = `marked', the behavior of functions
that use that macro also changes (unless they get
changed to call `dired-map-over-marks' differently).
One such function is `dired-get-marked-files'.

Other functions also use `dired-map-over-marks', in 
`dired.el', `dired-aux.el', `dired-x.el', `ediff.el',
`message.el', and `image-dired-dired.el.  Someone
fixing the doc of `dired-get-marked-files' for this
bug could check their doc strings as well.  (And
similarly for functions that use such functions, if
their own doc describes the same ARG.)

___

FWIW (only related as another change to ARG behavior):

In my own code (Dired+), if argument ARG of 
`dired-get-marked-files' is a cons (e.g. from using
`C-u' with a command that calls it) then it returns
_all_ files, ignoring any marks, as follows:

 If ARG is a cons with element 16, 64, or 256, corresponding to
  `C-u C-u', `C-u C-u C-u', or `C-u C-u C-u C-u', then use all files
  in the Dired buffer, where:
    16 includes NO directories (including `.' and `..')
    64 includes directories EXCEPT `.' and `..'
   256 includes ALL directories (including `.' and `..')

(This is implemented by the Dired+ version of
`dired-map-over-marks'.)

IMO, being able to _keep a set of markings_ and act
on all files is an important, and common, use case.

And now, because of the Emacs 29 `dired-map-over-marks'
change, it has a new possibility: passing it an ARG of
`marked' from Lisp.  (I haven't given users a way to do
that interactively, and probably won't.)

Previous Next

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