Reading File Names

The high-level completion functions read-file-name, read-directory-name, and read-shell-command are designed to read file names, directory names, and shell commands, respectively. They provide special features, including automatic insertion of the default directory.

Function: read-file-name prompt &optional directory default require-match initial predicate

This function reads a file name, prompting with prompt and providing completion.

As an exception, this function reads a file name using a graphical file dialog instead of the minibuffer, if all of the following are true:

It is invoked via a mouse command.
The selected frame is on a graphical display supporting such dialogs.
The variable use-dialog-box is non-nil. See Dialog Boxes in The GNU Emacs Manual.
The directory argument, described below, does not specify a remote file. See Remote Files in The GNU Emacs Manual.

The exact behavior when using a graphical file dialog is platform-dependent. Here, we simply document the behavior when using the minibuffer.

read-file-name does not automatically expand the returned file name. You can call expand-file-name yourself if an absolute file name is required.

The optional argument require-match has the same meaning as in completing-read. See Minibuffer Completion.

The argument directory specifies the directory to use for completing relative file names. It should be an absolute directory name. If the variable 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 in a buffer visiting a file. Please note: we recommend using default rather than initial in most cases.

If default is non-nil, then the function returns default if the user exits the minibuffer with the same non-empty contents that read-file-name inserted initially. The initial minibuffer contents are always non-empty if insert-default-directory is non-nil, as it is by default. default is not checked for validity, regardless of the value of require-match. However, if require-match is non-nil, the initial minibuffer contents should be a valid file (or directory) name. Otherwise read-file-name attempts completion if the user exits without any editing, and does not return default. default is also available through the history commands.

If default is nil, read-file-name tries to find a substitute default to use in its place, which it treats in exactly the same way as if it had been specified explicitly. If default is nil, but initial is non-nil, then the default is the absolute file name obtained from directory and initial. If both default and initial are nil and the buffer is visiting a file, read-file-name uses the absolute file name of that file as default. If the buffer is not visiting a file, then there is no default. In that case, if the user types RET without any editing, read-file-name simply returns the pre-inserted contents of the minibuffer.

If the user types RET in an empty minibuffer, this function returns an empty string, regardless of the value of require-match. This is, for instance, how the user can make the current buffer visit no file using M-x set-visited-file-name.

If predicate is non-nil, it specifies a function of one argument that decides which file names are acceptable completion alternatives. A file name is an acceptable value if predicate returns non-nil for it.

Here is an example of using read-file-name:

(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".

Variable: read-file-name-function: If non-nil, this should be a function that accepts the same arguments as read-file-name. When read-file-name is called, it calls this function with the supplied arguments instead of doing its usual work.

User Option: read-file-name-completion-ignore-case: If this variable is non-nil, read-file-name ignores case when performing completion.

Function: read-directory-name prompt &optional directory default require-match initial

This function is like read-file-name but allows only directory names as completion alternatives.

If default is nil and initial is non-nil, read-directory-name constructs a substitute default by combining directory (or the current buffer’s default directory if directory is nil) and initial. If both default and initial are nil, this function uses directory as substitute default, or the current buffer’s default directory if directory is nil.

User Option: insert-default-directory

This variable is used by read-file-name, and thus, indirectly, by most commands reading file names. (This includes all commands that use the code letters ‘f’ or ‘F’ in their interactive form. See Code Characters for interactive.) 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.

If this variable is nil and the initial minibuffer contents are empty, the user may have to explicitly fetch the next history element to access a default value. If the variable is non-nil, the initial minibuffer contents are always non-empty and the user can always request a default value by immediately typing RET in an unedited minibuffer. (See above.)

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 ----------

Function: read-shell-command prompt &optional initial history &rest args

This function reads a shell command from the minibuffer, prompting with prompt and providing intelligent completion. It completes the first word of the command using candidates that are appropriate for command names, and the rest of the command words as file names.

This function uses minibuffer-local-shell-command-map as the keymap for minibuffer input. The history argument specifies the history list to use; if is omitted or nil, it defaults to shell-command-history (see shell-command-history). The optional argument initial specifies the initial content of the minibuffer (see Initial Input). The rest of args, if present, are used as the default and inherit-input-method arguments in read-from-minibuffer (see Text from Minibuffer).

Variable: minibuffer-local-shell-command-map: This keymap is used by read-shell-command for completing command and file names that are part of a shell command. It uses minibuffer-local-map as its parent keymap, and binds TAB to completion-at-point.