Elisp: Walk Directory, List Files

By Xah Lee. Date: . Last updated: .

List Directory (No Subdir)

directory-files
(directory-files DIRECTORY &optional FULL MATCH NOSORT COUNT)

Return a list of paths of file or dir in DIRECTORY. (No Subdir)

Optional parameters:

  • FULL → If true, return full path.
  • MATCH → Is a Regular Expression. If given, only return file or subdir names that contain the pattern. Match is done on the name part only, not the full path.
  • NOSORT → if true, result is not sorted.
  • COUNT → return max of n items.

🛑 WARNING: the returned path may include the unix dot "." (means current dir) and dot dot ".." (means parent dir). To exclude them, use a MATCH regex that does not match dot or dotdot e.g. \\.jpg$ or use directory-files-no-dot-files-regexp 

;; list dir content, no subdir

;; result include dir names,
;; and also include special dir dot and dotdot
(directory-files "~/Downloads/")
;; use directory-files-no-dot-files-regexp
;; to exclude . and ..
(directory-files "~/Downloads/" nil directory-files-no-dot-files-regexp t 5)
;; show jpg files only
(directory-files "~/Downloads/" nil "\\.jpg$" t 5)

List Directory and All Subdir

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

Return list of all file fullpaths under directory DIR whose names contain the pattern REGEXP.

By default, directory paths are excluded in result unless INCLUDE-DIRECTORIES is true.

  • REGEXP → Is a Regular Expression. Only return names that contain the pattern. Match is done on the name part only, not the full path. This filter is applied first, before any other option. To not filter by name, "." for REGEXP
  • Unix dot and dotdot dirs are excluded.
  • All nested subdirectories's children are included, by default.
  • Items are returned in depth first order.
  • Returned paths are full paths.
  • Dir path in result does not end in slash.
  • Items from each directory are sorted in alphabetical order.

Optional parameters:

  • INCLUDE-DIRECTORIES → true means, in the result, include paths that are directories.
  • DIR-PREDICATE → is a filter on which subdirectory to dive into. REGEXP is applied first before DIR-PREDICATE sees it.
    • nil → dive into all subdirectories.
    • t → ignore subdirectories that can't be read.
    • Function f → if f return true, dive into that dir, else not. The f is passed a subdirectory fullpath.
  • FOLLOW-SYMLINKS → if true, follow sym links. (may result infinite loop)
;; 2024-09-18
;; list dir and and all subdirectory
;; of file extension .el
;; ignore dirs whose name start with dot, e.g. .git

(directory-files-recursively
"c:/Users/xah/git/xah-fly-keys/"
"\\.el$" nil (lambda (x) (not (string-match-p "/\\." x))))

Filter by Dir Depth Level

Other Functions

Reference

Emacs Lisp, File, Buffer