14.2 Visiting Files

C-x C-f

Visit a file (find-file).

C-x C-v

Visit a different file instead of the one visited last (find-alternate-file).

C-x 4 C-f

Visit a file, in another window (find-file-other-window). Don’t change this window.

C-x 5 C-f

Visit a file, in another frame (find-file-other-frame). Don’t change this window or frame.

Visiting a file means copying its contents into an Emacs buffer so you can edit it. Emacs creates a new buffer for each file you visit. We say that the buffer is visiting the file that it was created to hold. Emacs constructs the buffer name from the file name by throwing away the directory and keeping just the file name. For example, a file named /usr/rms/emacs.tex is displayed in a buffer named ‘emacs.tex’. If a buffer with that name exists, a unique name is constructed by appending ‘<2>’, ‘<3>’,and so on, using the lowest number that makes a name that is not already in use.

Each window’s mode line shows the name of the buffer that is being displayed in that window, so you can always tell what buffer you are editing.

The changes you make with Emacs are made in the Emacs buffer. They do not take effect in the file that you visit, or any other permanent place, until you save the buffer. Saving the buffer means that Emacs writes the current contents of the buffer into its visited file. See Saving.

If a buffer contains changes that have not been saved, the buffer is said to be modified. This is important because it implies that some changes will be lost if the buffer is not saved. The mode line displays two stars near the left margin if the buffer is modified.

To visit a file, use the command C-x C-f (find-file). Follow the command with the name of the file you wish to visit, terminated by a RET. If you are using SXEmacs under X, you can also use the Open... command from the File menu bar item.

The file name is read using the minibuffer (see Minibuffer), with defaulting and completion in the standard manner (see File Names). While in the minibuffer, you can abort C-x C-f by typing C-g.

C-x C-f has completed successfully when text appears on the screen and a new buffer name appears in the mode line. If the specified file does not exist and could not be created or cannot be read, an error results. The error message is printed in the echo area, and includes the name of the file that Emacs was trying to visit.

If you visit a file that is already in Emacs, C-x C-f does not make another copy. It selects the existing buffer containing that file. However, before doing so, it checks that the file itself has not changed since you visited or saved it last. If the file has changed, Emacs prints a warning message. See Simultaneous Editing.

You can switch to a specific file called out in the current buffer by calling the function find-this-file. By providing a prefix argument, this function calls filename-at-point and switches to a buffer visiting the file filename. It creates one if none already exists. You can use this function to edit the file mentioned in the buffer you are working in or to test if the file exists. You can do that by using the minibuffer completion after snatching the all or part of the filename.

If the variable find-file-use-truenames’s value is non-nil, a buffer’s visited filename will always be traced back to the real file. The filename will never be a symbolic link, and there will never be a symbolic link anywhere in its directory path. In other words, the buffer-file-name and buffer-file-truename will be equal.

If the variable find-file-compare-truenames value is non-nil, the find-file command will check the buffer-file-truename of all visited files when deciding whether a given file is already in a buffer, instead of just buffer-file-name. If you attempt to visit another file which is a symbolic link to a file that is already in a buffer, the existing buffer will be found instead of a newly created one. This works if any component of the pathname (including a non-terminal component) is a symbolic link as well, but doesn’t work with hard links (nothing does).

If you want to create a file, just visit it. Emacs prints ‘(New File)’ in the echo area, but in other respects behaves as if you had visited an existing empty file. If you make any changes and save them, the file is created.

If you visit a nonexistent file unintentionally (because you typed the wrong file name), use the C-x C-v (find-alternate-file) command to visit the file you wanted. C-x C-v is similar to C-x C-f, but it kills the current buffer (after first offering to save it if it is modified). C-x C-v is allowed even if the current buffer is not visiting a file.

If the file you specify is actually a directory, Dired is called on that directory (see Dired). To inhibit this, set the variable find-file-run-dired to nil; then it is an error to try to visit a directory.

C-x 4 f (find-file-other-window) is like C-x C-f except that the buffer containing the specified file is selected in another window. The window that was selected before C-x 4 f continues to show the same buffer it was already showing. If you use this command when only one window is being displayed, that window is split in two, with one window showing the same buffer as before, and the other one showing the newly requested file. See Windows.

C-x 5 C-f (find-file-other-frame) is like C-x C-f except that it creates a new frame in which the file is displayed.

Use the function find-this-file-other-window to edit a file mentioned in the buffer you are editing or to test if that file exists. To do this, use the minibuffer completion after snatching the part or all of the filename. By providing a prefix argument, the function calls filename-at-point and switches you to a buffer visiting the file filename in another window. The function creates a buffer if none already exists. This function is similar to find-file-other-window.

There are two hook variables that allow extensions to modify the operation of visiting files. Visiting a file that does not exist runs the functions in the list find-file-not-found-hooks; the value of this variable is expected to be a list of functions which are called one by one until one of them returns non-nil. Any visiting of a file, whether extant or not, expects find-file-hooks to contain list of functions and calls them all, one by one. In both cases the functions receive no arguments. Visiting a nonexistent file runs the find-file-not-found-hooks first.