23.1 File Names

Most Emacs commands that operate on a file require you to specify the file name. (Saving and reverting are exceptions; the buffer knows which file name to use for them.) You enter the file name using the minibuffer (see section The Minibuffer). Completion is available (see section Completion) to make it easier to specify long file names. When completing file names, Emacs ignores those whose file-name extensions appear in the variable completion-ignored-extensions; see Completion Options.

For most operations, there is a default file name which is used if you type just <RET> to enter an empty argument. Normally the default file name is the name of the file visited in the current buffer; this makes it easy to operate on that file with any of the Emacs file commands.

Each buffer has a default directory which is normally the same as the directory of the file visited in that buffer. When you enter a file name without a directory, the default directory is used. If you specify a directory in a relative fashion, with a name that does not start with a slash, it is interpreted with respect to the default directory. The default directory is kept in the variable default-directory, which has a separate value in every buffer.

The command M-x pwd displays the current buffer's default directory, and the command M-x cd sets it (to a value read using the minibuffer). A buffer's default directory changes only when the cd command is used. A file-visiting buffer's default directory is initialized to the directory of the file it visits. If you create a buffer with C-x b, its default directory is copied from that of the buffer that was current at the time.

For example, if the default file name is ‘/u/rms/gnu/gnu.tasks’ then the default directory is normally ‘/u/rms/gnu/’. If you type just ‘foo’, which does not specify a directory, it is short for ‘/u/rms/gnu/foo’. ‘../.login’ would stand for ‘/u/rms/.login’. ‘new/foo’ would stand for the file name ‘/u/rms/gnu/new/foo’.

The default directory actually appears in the minibuffer when the minibuffer becomes active to read a file name. This serves two purposes: it shows you what the default is, so that you can type a relative file name and know with certainty what it will mean, and it allows you to edit the default to specify a different directory. This insertion of the default directory is inhibited if the variable insert-default-directory is set to nil.

Note that it is legitimate to type an absolute file name after you enter the minibuffer, ignoring the presence of the default directory name as part of the text. The final minibuffer contents may look invalid, but that is not so. For example, if the minibuffer starts out with ‘/usr/tmp/’ and you add ‘/x1/rms/foo’, you get ‘/usr/tmp//x1/rms/foo’; but Emacs ignores everything through the first slash in the double slash; the result is ‘/x1/rms/foo’. See section Minibuffers for File Names.

You can use ‘~/’ in a file name to mean your home directory, or ‘~user-id/’ to mean the home directory of a user whose login name is user-id(2).

‘$’ in a file name is used to substitute an environment variable. The environment variable name consists of all the alphanumeric characters after the ‘$’; alternatively, it can be enclosed in braces after the ‘$’. For example, if you have used the shell command export FOO=rms/hacks to set up an environment variable named FOO, then you can use ‘/u/$FOO/test.c’ or ‘/u/${FOO}/test.c’ as an abbreviation for ‘/u/rms/hacks/test.c’. If the environment variable is not defined, no substitution occurs: ‘/u/$notdefined’ stands for itself (assuming the environment variable notdefined is not defined).

Note that shell commands to set environment variables affect Emacs only when done before Emacs is started.

To access a file with ‘$’ in its name, if the ‘$’ causes expansion, type ‘$$’. This pair is converted to a single ‘$’ at the same time as variable substitution is performed for a single ‘$’. Alternatively, quote the whole file name with ‘/:’ (see section Quoted File Names). File names which begin with a literal ‘~’ should also be quoted with ‘/:’.

The Lisp function that performs the ‘$’-substitution is called substitute-in-file-name. The substitution is performed only on file names read as such using the minibuffer.

You can include non-ASCII characters in file names if you set the variable file-name-coding-system to a non-nil value. See section Coding Systems for File Names.