20.5.5 Reading File Names

Here is another high-level completion function, designed for reading a file name. It provides special features including automatic insertion of the default directory.

Function: read-file-name prompt &optional directory default existing initial

This function reads a file name in the minibuffer, prompting with prompt and providing completion. If default is non-nil, then the function returns default if the user just types RET. default is not checked for validity; it is returned, whatever it is, if the user exits with the minibuffer empty.

If existing is non-nil, then the user must specify the name of an existing file; RET performs completion to make the name valid if possible, and then refuses to exit if it is not valid. If the value of existing is neither nil nor t, then RET also requires confirmation after completion. If existing is nil, then the name of a nonexistent file is acceptable.

The argument directory specifies the directory to use for completion of relative file names. If insert-default-directory is non-nil, directory is also inserted in the minibuffer as initial input. It defaults to the current buffer's value of default-directory.

If you specify initial, that is an initial file name to insert in the buffer (after directory, if that is inserted). In this case, point goes at the beginning of initial. The default for initial is nil---don't insert any file name. To see what initial does, try the command C-x C-v. Note: we recommend using default rather than initial in most cases.

Here is an example:

(read-file-name "The file is ") ;; After evaluation of the preceding expression, ;; the following appears in the minibuffer: ---------- Buffer: Minibuffer ---------- The file is /gp/gnu/elisp/-!- ---------- Buffer: Minibuffer ----------

Typing manual TAB results in the following:

---------- Buffer: Minibuffer ---------- The file is /gp/gnu/elisp/manual.texi-!- ---------- Buffer: Minibuffer ----------

If the user types RET, read-file-name returns the file name as the string "/gp/gnu/elisp/manual.texi".

User Option: insert-default-directory

This variable is used by read-file-name. Its value controls whether read-file-name starts by placing the name of the default directory in the minibuffer, plus the initial file name if any. If the value of this variable is nil, then read-file-name does not place any initial input in the minibuffer (unless you specify initial input with the initial argument). In that case, the default directory is still used for completion of relative file names, but is not displayed.

For example:

;; Here the minibuffer starts out with the default directory. (let ((insert-default-directory t)) (read-file-name "The file is ")) ---------- Buffer: Minibuffer ---------- The file is ~lewis/manual/-!- ---------- Buffer: Minibuffer ---------- ;; Here the minibuffer is empty and only the prompt ;; appears on its line. (let ((insert-default-directory nil)) (read-file-name "The file is ")) ---------- Buffer: Minibuffer ---------- The file is -!- ---------- Buffer: Minibuffer ----------