Function: dired-insert-directory
dired-insert-directory is a byte-compiled function defined in
dired.el.gz.
Signature
(dired-insert-directory DIR SWITCHES &optional FILE-LIST WILDCARD HDR)
Documentation
Insert a directory listing of DIR, Dired style.
Use SWITCHES to make the listings.
If FILE-LIST is non-nil, list only those files.
Otherwise, if WILDCARD is non-nil, expand wildcards;
in that case, DIR should be a file name that uses wildcards.
In other cases, DIR should be a directory name or a directory filename.
If HDR is non-nil, insert a header line with the directory name.
Probably introduced at or before Emacs version 29.1.
Source Code
;; Defined in /usr/src/emacs/lisp/dired.el.gz
(defun dired-insert-directory (dir switches &optional file-list wildcard hdr)
"Insert a directory listing of DIR, Dired style.
Use SWITCHES to make the listings.
If FILE-LIST is non-nil, list only those files.
Otherwise, if WILDCARD is non-nil, expand wildcards;
in that case, DIR should be a file name that uses wildcards.
In other cases, DIR should be a directory name or a directory filename.
If HDR is non-nil, insert a header line with the directory name."
(let ((opoint (point))
(process-environment (copy-sequence process-environment))
end)
(if (and
;; Don't try to invoke `ls' if we are on DOS/Windows where
;; ls-lisp emulation is used, except if they want to use `ls'
;; as indicated by `ls-lisp-use-insert-directory-program'.
(not (and (featurep 'ls-lisp)
(null ls-lisp-use-insert-directory-program)))
;; FIXME: Big ugly hack for Eshell's eshell-ls-use-in-dired.
(not (bound-and-true-p eshell-ls-use-in-dired))
(or (file-remote-p dir)
(if (eq dired-use-ls-dired 'unspecified)
;; Check whether "ls --dired" gives exit code 0, and
;; save the answer in `dired-use-ls-dired'.
(or (setq dired-use-ls-dired
(eq 0 (call-process insert-directory-program
nil nil nil "--dired")))
(progn
(message "ls does not support --dired; \
see `dired-use-ls-dired' for more details.")
nil))
dired-use-ls-dired)))
(setq switches (concat "--dired " switches)))
;; Expand directory wildcards and fill file-list.
(let ((dir-wildcard (insert-directory-wildcard-in-dir-p dir)))
(cond (dir-wildcard
(setq switches (concat "-d " switches))
;; We don't know whether the remote ls supports
;; "--dired", so we cannot add it to the `process-file'
;; call for wildcards.
(when (file-remote-p dir)
(setq switches (string-replace "--dired" "" switches)))
(let* ((default-directory (car dir-wildcard))
(script (format "%s %s %s"
insert-directory-program
switches (cdr dir-wildcard)))
(remotep (file-remote-p dir))
(sh (or (and remotep "/bin/sh")
(executable-find shell-file-name)
(executable-find "sh")))
(switch (if remotep "-c" shell-command-switch)))
;; Enable globstar
(when-let ((globstar dired-maybe-use-globstar)
(enable-it
(assoc-default
(file-truename sh) dired-enable-globstar-in-shell
(lambda (reg shell) (string-match reg shell)))))
(setq script (format "%s; %s" enable-it script)))
(unless
(zerop
(process-file sh nil (current-buffer) nil switch script))
(user-error
"%s: No files matching wildcard" (cdr dir-wildcard)))
(insert-directory-clean (point) switches)))
(t
;; We used to specify the C locale here, to force English
;; month names; but this should not be necessary any
;; more, with the new value of
;; `directory-listing-before-filename-regexp'.
(if file-list
(dolist (f file-list)
(let ((beg (point)))
(insert-directory f switches nil nil)
;; Re-align fields, if necessary.
(dired-align-file beg (point))))
(insert-directory dir switches wildcard (not wildcard))))))
;; Quote certain characters, unless ls quoted them for us.
(if (not (dired-switches-escape-p dired-actual-switches))
(save-excursion
(setq end (point-marker))
(goto-char opoint)
(while (search-forward "\\" end t)
(replace-match (apply #'propertize
"\\\\"
(text-properties-at (match-beginning 0)))
nil t))
(goto-char opoint)
(while (search-forward "\^m" end t)
(replace-match (apply #'propertize
"\\015"
(text-properties-at (match-beginning 0)))
nil t))
(set-marker end nil))
;; Replace any newlines in DIR with literal "\n"s, for the sake
;; of the header line. To disambiguate a literal "\n" in the
;; actual dirname, we also replace "\" with "\\".
;; Personally, I think this should always be done, irrespective
;; of the value of dired-actual-switches, because:
;; i) Dired simply does not work with an unescaped newline in
;; the directory name used in the header (bug=10469#28), and
;; ii) "\" is always replaced with "\\" in the listing, so doing
;; it in the header as well makes things consistent.
;; But at present it is only done if "-b" is in ls-switches,
;; because newlines in dirnames are uncommon, and people may
;; have gotten used to seeing unescaped "\" in the headers.
;; Note: adjust dired-build-subdir-alist if you change this.
(setq dir (string-replace "\\" "\\\\" dir)
dir (string-replace "\n" "\\n" dir)))
;; If we used --dired and it worked, the lines are already indented.
;; Otherwise, indent them.
(unless (save-excursion
(goto-char opoint)
(looking-at-p " "))
(let ((indent-tabs-mode nil))
(indent-rigidly opoint (point) 2)))
;; Insert text at the beginning to standardize things.
(let ((content-point opoint))
(save-excursion
(goto-char opoint)
(when (and (or hdr wildcard)
(not (and (looking-at "^ \\(.*\\):$")
(file-name-absolute-p (match-string 1)))))
;; Note that dired-build-subdir-alist will replace the name
;; by its expansion, so it does not matter whether what we insert
;; here is fully expanded, but it should be absolute.
(insert " " (or (car-safe (insert-directory-wildcard-in-dir-p dir))
(directory-file-name (file-name-directory dir)))
":\n")
(setq content-point (point)))
(when wildcard
;; Insert "wildcard" line where "total" line would be for a full dir.
(insert " wildcard " (or (cdr-safe (insert-directory-wildcard-in-dir-p dir))
(file-name-nondirectory dir))
"\n"))
(setq content-point (dired--insert-disk-space opoint dir)))
(dired-insert-set-properties content-point (point)))))