The high-level completion functions
read-shell-command are designed
to read file names, directory names, and shell commands, respectively.
They provide special features, including automatic insertion of the
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
nil. See Dialog Boxes.
- The directory argument, described below, does not specify a remote file. See Remote Files.
The exact behavior when using a graphical file dialog is platform-dependent. Here, we simply document the behavior when using the minibuffer.
read-file-namedoes not automatically expand the returned file name. You must call
expand-file-nameyourself 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
nil, directory is also inserted in the minibuffer as initial input. It defaults to the current buffer's value of
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-nameinserted initially. The initial minibuffer contents are always non-empty if
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-nameattempts completion if the user exits without any editing, and does not return default. default is also available through the history commands.
If default is
read-file-nametries 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
niland the buffer is visiting a file,
read-file-nameuses 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-namesimply 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-
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-namereturns the file name as the string
nil, this should be a function that accepts the same arguments as
read-file-nameis called, it calls this function with the supplied arguments instead of doing its usual work.
If this variable is non-
read-file-nameignores case when performing completion.
This function is like
read-file-namebut allows only directory names as completion alternatives.
If default is
niland initial is non-
read-directory-nameconstructs 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
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-namestarts 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
read-file-namedoes 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
niland 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 ----------
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-mapas 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).