18.1 File Names

Many Emacs commands that operate on a file require you to specify the file name, using the minibuffer (see Minibuffer File).

While in the minibuffer, you can use the usual completion and history commands (see Minibuffer). Note that file name completion ignores file names whose extensions appear in the variable completion-ignored-extensions (see Completion Options). Note also that most commands use permissive completion with confirmation for reading file names: you are allowed to submit a nonexistent file name, but if you type RET immediately after completing up to a nonexistent file name, Emacs prints ‘[Confirm]’ and you must type a second RET to confirm. See Completion Exit, for details.

Minibuffer history commands offer some special features for reading file names, see Minibuffer History.

Each buffer has a default directory, stored in the buffer-local variable default-directory. Whenever Emacs reads a file name using the minibuffer, it usually inserts the default directory into the minibuffer as the initial contents. You can inhibit this insertion by changing the variable insert-default-directory to nil (see Minibuffer File). Regardless, Emacs always assumes that any relative file name is relative to the default directory, e.g., entering a file name without a directory specifies a file in the default directory.

When you visit a file, Emacs sets default-directory in the visiting buffer to the directory of its file. When you create a new buffer that is not visiting a file, via a command like C-x b, its default directory is usually copied from the buffer that was current at the time (see Select Buffer). You can use the command M-x pwd to see the value of default-directory in the current buffer. The command M-x cd prompts for a directory’s name, and sets the buffer’s default-directory to that directory (doing this does not change the buffer’s file name, if any).

As an example, when you visit the file /u/rms/gnu/gnu.tasks, the default directory is set to /u/rms/gnu/. If you invoke a command that reads a file name, entering just ‘foo’ in the minibuffer, with a directory omitted, specifies the file /u/rms/gnu/foo; entering ‘../.login’ specifies /u/rms/.login; and entering ‘new/foo’ specifies /u/rms/gnu/new/foo.

When typing a file name into the minibuffer, you can make use of a couple of shortcuts: a double slash ignores everything before the second slash in the pair, and ‘~/’ is your home directory. See Minibuffer File.

The character ‘$’ is used to substitute an environment variable into a file name. The name of the environment variable 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 both /u/$FOO/test.c and /u/${FOO}/test.c are abbreviations for /u/rms/hacks/test.c. If the environment variable is not defined, no substitution occurs, so that the character ‘$’ stands for itself. Note that environment variables set outside Emacs affect Emacs only if they are applied 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 that variable substitution is performed for a single ‘$’. Alternatively, quote the whole file name with ‘/:’ (see Quoted File Names). File names which begin with a literal ‘~’ should also be quoted with ‘/:’.

You can include non-ASCII characters in file names. See File Name Coding.