Elisp: Walk Directory, List Files

By Xah Lee. Date: . Last updated: .

List Directory (No Subdir)

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

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

Optional parameters:

  • FULLPATH → 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.
;; also include special dir dot and dotdot
(directory-files "~/Downloads/")

;; ("."
;; ".."
;; "New_folder"
;; "ShareX-17.1.0-portable.zip"
;; "Svalboard_Fitment_Guide.pdf"
;; "SysinternalsSuite.zip"
;; "plate078 - Copy.nb"
;; "povwin-3.7-agpl3-setup.exe")
;; list dir content, no subdir

;; get full paths
(directory-files "~/Downloads/" t)

;; ("c:/Users/xah/Downloads/."
;; "c:/Users/xah/Downloads/.."
;; "c:/Users/xah/Downloads/New_folder"
;; "c:/Users/xah/Downloads/ShareX-17.1.0-portable.zip"
;; "c:/Users/xah/Downloads/Svalboard_Fitment_Guide.pdf"
;; "c:/Users/xah/Downloads/SysinternalsSuite.zip"
;; "c:/Users/xah/Downloads/plate078 - Copy.nb"
;; "c:/Users/xah/Downloads/povwin-3.7-agpl3-setup.exe")
;; 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. (🛑 WARNING: 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, use empty string.
  • 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 no. The f is passed a dir fullpath, but without the ending slash.
  • 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

Elisp, File, Buffer