Function: directory-files-recursively

directory-files-recursively is a byte-compiled function defined in files.el.gz.

Signature

(directory-files-recursively DIR REGEXP &optional INCLUDE-DIRECTORIES PREDICATE FOLLOW-SYMLINKS LESSP)

Documentation

Return list of all files under directory DIR whose names match REGEXP.

This function works recursively, with files returned in "depth first" (bottom-up) order. Each file name whose non-directory part matches REGEXP appears in the returned list in its absolute form.

By default, the returned list excludes directories, but if optional argument INCLUDE-DIRECTORIES is non-nil, it means consider them for inclusion.

PREDICATE can be either nil (which means that all subdirectories of DIR are descended into), t (which means that subdirectories that can't be read are ignored), or a function (which is called with the absolute name of each subdirectory, and should return non-nil if the subdirectory is to be descended into).

If FOLLOW-SYMLINKS is non-nil, symbolic links that point to directories are followed. Note that this can lead to infinite recursion.

LESSP determines the relative order of file names per directory in the returned list. When nil, it defaults to lexicographic order as per string-lessp. When t, files in each directory are not sorted, and their order is arbitrary. Otherwise, it is a function suitable as the
:lessp argument of sort, that takes two arguments (the non-directory
part of two file names) and returns non-nil if the first should precede the second. For example, string-collate-lessp gives the locale-specific collation order one might see in Dired.

Other relevant functions are documented in the file group.

View in manual

Probably introduced at or before Emacs version 25.1.

Shortdoc

;; file
(directory-files-recursively "/tmp/" "\\.png\\'")
    e.g. => ("/tmp/foo.png" "/tmp/zot.png" "/tmp/bar/foobar.png")

Source Code

;; Defined in /usr/src/emacs/lisp/files.el.gz
(defun directory-files-recursively (dir regexp
                                        &optional include-directories predicate
                                        follow-symlinks lessp)
  "Return list of all files under directory DIR whose names match REGEXP.
This function works recursively, with files returned in \"depth
first\" (bottom-up) order.  Each file name whose non-directory part
matches REGEXP appears in the returned list in its absolute form.

By default, the returned list excludes directories, but if
optional argument INCLUDE-DIRECTORIES is non-nil, it means
consider them for inclusion.

PREDICATE can be either nil (which means that all subdirectories
of DIR are descended into), t (which means that subdirectories that
can't be read are ignored), or a function (which is called with
the absolute name of each subdirectory, and should return non-nil
if the subdirectory is to be descended into).

If FOLLOW-SYMLINKS is non-nil, symbolic links that point to
directories are followed.  Note that this can lead to infinite
recursion.

LESSP determines the relative order of file names per directory in the
returned list.  When nil, it defaults to lexicographic order as per
`string-lessp'.  When t, files in each directory are not sorted, and
their order is arbitrary.  Otherwise, it is a function suitable as the
`:lessp' argument of `sort', that takes two arguments (the non-directory
part of two file names) and returns non-nil if the first should precede
the second.  For example, `string-collate-lessp' gives the
locale-specific collation order one might see in Dired."
  ;; Set up some (potentially expensive) invariants before recursing.
  (let* (;; As requested by `files--recursively'.
         (dir (if (directory-name-p dir) dir (file-name-as-directory dir)))
         ;; Must be absolute for the `file-remote-p' that follows, and
         ;; so that the final result comprises absolute names even when
         ;; the input is relative.  But skip `expand-file-name' if
         ;; possible, for speed and symmetry with the input.
         (dir (if (file-name-absolute-p dir) dir (expand-file-name dir)))
         ;; When DIR is "/", remote file names like "/method:" could
         ;; also be offered.  We shall suppress them.
         (tramp-mode (and tramp-mode (file-remote-p dir)))
         ;; Avoid its influence on `file-name-all-completions',
         ;; which we use in place of `directory-files' for speed.
         (completion-regexp-list ()))
    (files--recursively dir regexp include-directories
                        predicate follow-symlinks lessp)))