"Fossies" - the Fresh Open Source Software Archive

Member "emacs-25.3/doc/emacs/files.texi" (14 Apr 2017, 92299 Bytes) of package /linux/misc/emacs-25.3.tar.xz:

Caution: As a special service "Fossies" has tried to format the requested Texinfo source page into HTML format but that may be not always succeeeded perfectly. Alternatively you can here view or download the uninterpreted Texinfo source code. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the last Fossies "Diffs" side-by-side code changes report for "files.texi": 25.1_vs_25.2.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 File Handling

The operating system stores data permanently in named files, so most of the text you edit with Emacs comes from a file and is ultimately stored in a file.

To edit a file, you must tell Emacs to read the file and prepare a buffer containing a copy of the file’s text. This is called visiting the file. Editing commands apply directly to text in the buffer; that is, to the copy inside Emacs. Your changes appear in the file itself only when you save the buffer back into the file.

In addition to visiting and saving files, Emacs can delete, copy, rename, and append to files, keep multiple versions of them, and operate on file directories.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 File Names

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

While in the minibuffer, you can use the usual completion and history commands (@pxref{Minibuffer}). Note that file name completion ignores file names whose extensions appear in the variable completion-ignored-extensions (@pxref{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. @xref{Completion Exit}, for details.

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 (@pxref{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 (@pxref{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 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. @xref{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 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 section Quoted File Names). File names which begin with a literal ‘~’ should also be quoted with ‘/:’.

You can include non-ASCII characters in file names. @xref{File Name Coding}.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Visiting Files

C-x C-f

Visit a file (find-file).

C-x C-r

Visit a file for viewing, without allowing changes to it (find-file-read-only).

C-x C-v

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

C-x 4 f

Visit a file, in another window (find-file-other-window). Don’t alter what is displayed in the selected window.

C-x 5 f

Visit a file, in a new frame (find-file-other-frame). Don’t alter what is displayed in the selected frame.

M-x find-file-literally

Visit a file with no conversion of the contents.

Visiting a file means reading its contents into an Emacs buffer so you can edit them. Emacs makes a new buffer for each file that you visit.

To visit a file, type C-x C-f (find-file) and use the minibuffer to enter the name of the desired file. While in the minibuffer, you can abort the command by typing C-g. See section File Names, for details about entering file names into minibuffers.

If the specified file exists but the system does not allow you to read it, an error message is displayed in the echo area. Otherwise, you can tell that C-x C-f has completed successfully by the appearance of new text on the screen, and by the buffer name shown in the mode line (@pxref{Mode Line}). Emacs normally constructs the buffer name from the file name, omitting the directory name. For example, a file named ‘/usr/rms/emacs.tex’ is visited in a buffer named ‘emacs.tex’. If there is already a buffer with that name, Emacs constructs a unique name; the normal method is to add a suffix based on the directory name (e.g., ‘<rms>’, ‘<tmp>’, and so on), but you can select other methods. @xref{Uniquify}.

To create a new file, just visit it using the same command, C-x C-f. Emacs displays ‘(New file)’ in the echo area, but in other respects behaves as if you had visited an existing empty file.

After visiting a file, the changes you make with editing commands are made in the Emacs buffer. They do not take effect in the visited file, until you save the buffer (see section Saving Files). If a buffer contains changes that have not been saved, we say the buffer is modified. This implies that some changes will be lost if the buffer is not saved. The mode line displays two stars near the left margin to indicate that the buffer is modified.

If you visit a file that is already in Emacs, C-x C-f switches to the existing buffer instead of making another copy. Before doing so, it checks whether the file has changed since you last visited or saved it. If the file has changed, Emacs offers to reread it.

If you try to visit a file larger than large-file-warning-threshold (the default is 10000000, which is about 10 megabytes), Emacs asks you for confirmation first. You can answer y to proceed with visiting the file. Note, however, that Emacs cannot visit files that are larger than the maximum Emacs buffer size, which is limited by the amount of memory Emacs can allocate and by the integers that Emacs can represent (@pxref{Buffers}). If you try, Emacs displays an error message saying that the maximum buffer size has been exceeded.

If the file name you specify contains shell-style wildcard characters, Emacs visits all the files that match it. (On case-insensitive filesystems, Emacs matches the wildcards disregarding the letter case.) Wildcards include ‘?’, ‘*’, and ‘[…]’ sequences. To enter the wild card ‘?’ in a file name in the minibuffer, you need to type C-q ?. See section Quoted File Names, for information on how to visit a file whose name actually contains wildcard characters. You can disable the wildcard feature by customizing find-file-wildcards.

If you visit the wrong file unintentionally by typing its name incorrectly, type C-x C-v (find-alternate-file) to visit the file you really 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). When C-x C-v reads the file name to visit, it inserts the entire default file name in the buffer, with point just after the directory part; this is convenient if you made a slight error in typing the name.

If you visit a file that is actually a directory, Emacs invokes Dired, the Emacs directory browser. @xref{Dired}. You can disable this behavior by setting the variable find-file-run-dired to nil; in that case, it is an error to try to visit a directory.

Files which are actually collections of other files, or file archives, are visited in special modes which invoke a Dired-like environment to allow operations on archive members. See section File Archives, for more about these features.

If you visit a file that the operating system won’t let you modify, or that is marked read-only, Emacs makes the buffer read-only too, so that you won’t go ahead and make changes that you’ll have trouble saving afterward. You can make the buffer writable with C-x C-q (read-only-mode). @xref{Misc Buffer}.

If you want to visit a file as read-only in order to protect yourself from entering changes accidentally, visit it with the command C-x C-r (find-file-read-only) instead of C-x C-f.

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 this command is used 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. @xref{Windows}.

C-x 5 f (find-file-other-frame) is similar, but opens a new frame, or selects any existing frame showing the specified file. @xref{Frames}.

On graphical displays, there are two additional methods for visiting files. Firstly, when Emacs is built with a suitable GUI toolkit, commands invoked with the mouse (by clicking on the menu bar or tool bar) use the toolkit’s standard file selection dialog instead of prompting for the file name in the minibuffer. On GNU/Linux and Unix platforms, Emacs does this when built with GTK, LessTif, and Motif toolkits; on MS-Windows and Mac, the GUI version does that by default. For information on how to customize this, see @ref{Dialog Boxes}.

Secondly, Emacs supports drag and drop: dropping a file into an ordinary Emacs window visits the file using that window. As an exception, dropping a file into a window displaying a Dired buffer moves or copies the file into the displayed directory. For details, see @ref{Drag and Drop}, and @ref{Misc Dired Features}.

On text-mode terminals and on graphical displays when Emacs was built without a GUI toolkit, you can visit files via the menu-bar ‘File’ menu, which has a ‘Visit New File’ item.

Each time you visit a file, Emacs automatically scans its contents to detect what character encoding and end-of-line convention it uses, and converts these to Emacs’s internal encoding and end-of-line convention within the buffer. When you save the buffer, Emacs performs the inverse conversion, writing the file to disk with its original encoding and end-of-line convention. @xref{Coding Systems}.

If you wish to edit a file as a sequence of ASCII characters with no special encoding or conversion, use the M-x find-file-literally command. This visits a file, like C-x C-f, but does not do format conversion (see Format Conversion in the Emacs Lisp Reference Manual), character code conversion (@pxref{Coding Systems}), or automatic uncompression (see section Accessing Compressed Files), and does not add a final newline because of require-final-newline (see section Customizing Saving of Files). If you have already visited the same file in the usual (non-literal) manner, this command asks you whether to visit it literally instead.

Two special hook variables allow extensions to modify the operation of visiting files. Visiting a file that does not exist runs the functions in find-file-not-found-functions; this variable holds a list of functions, which are called one by one (with no arguments) until one of them returns non-nil. This is not a normal hook, and the name ends in ‘-functions’ rather than ‘-hook’ to indicate that fact.

Successful visiting of any file, whether existing or not, calls the functions in find-file-hook, with no arguments. This variable is a normal hook. In the case of a nonexistent file, the find-file-not-found-functions are run first. @xref{Hooks}.

There are several ways to specify automatically the major mode for editing the file (@pxref{Choosing Modes}), and to specify local variables defined for that file (@pxref{File Variables}).

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Saving Files

Saving a buffer in Emacs means writing its contents back into the file that was visited in the buffer.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3.1 Commands for Saving Files

These are the commands that relate to saving and writing files.

C-x C-s

Save the current buffer to its file (save-buffer).

C-x s

Save any or all buffers to their files (save-some-buffers).


Forget that the current buffer has been changed (not-modified). With prefix argument (C-u), mark the current buffer as changed.

C-x C-w

Save the current buffer with a specified file name (write-file).

M-x set-visited-file-name

Change the file name under which the current buffer will be saved.

When you wish to save the file and make your changes permanent, type C-x C-s (save-buffer). After saving is finished, C-x C-s displays a message like this:

Wrote /u/rms/gnu/gnu.tasks

If the current buffer is not modified (no changes have been made in it since the buffer was created or last saved), saving is not really done, because it would have no effect. Instead, C-x C-s displays a message like this in the echo area:

(No changes need to be saved)

With a prefix argument, C-u C-x C-s, Emacs also marks the buffer to be backed up when the next save is done. See section Backup Files.

The command C-x s (save-some-buffers) offers to save any or all modified buffers. It asks you what to do with each buffer. The possible responses are analogous to those of query-replace:


Save this buffer and ask about the rest of the buffers.


Don’t save this buffer, but ask about the rest of the buffers.


Save this buffer and all the rest with no more questions.


Terminate save-some-buffers without any more saving.


Save this buffer, then exit save-some-buffers without even asking about other buffers.


View the buffer that you are currently being asked about. When you exit View mode, you get back to save-some-buffers, which asks the question again.


Diff the buffer against its corresponding file, so you can see what changes you would be saving. This calls the command diff-buffer-with-file (see section Comparing Files).


Display a help message about these options.

C-x C-c, the key sequence to exit Emacs, invokes save-some-buffers and therefore asks the same questions.

If you have changed a buffer but do not wish to save the changes, you should take some action to prevent it. Otherwise, each time you use C-x s or C-x C-c, you are liable to save this buffer by mistake. One thing you can do is type M-~ (not-modified), which clears out the indication that the buffer is modified. If you do this, none of the save commands will believe that the buffer needs to be saved. (‘~’ is often used as a mathematical symbol for “not”; thus M-~ is “not”, metafied.) Alternatively, you can cancel all the changes made since the file was visited or saved, by reading the text from the file again. This is called reverting. See section Reverting a Buffer. (You could also undo all the changes by repeating the undo command C-x u until you have undone all the changes; but reverting is easier.)

M-x set-visited-file-name alters the name of the file that the current buffer is visiting. It reads the new file name using the minibuffer. Then it marks the buffer as visiting that file name, and changes the buffer name correspondingly. set-visited-file-name does not save the buffer in the newly visited file; it just alters the records inside Emacs in case you do save later. It also marks the buffer as modified so that C-x C-s in that buffer will save.

If you wish to mark the buffer as visiting a different file and save it right away, use C-x C-w (write-file). This is equivalent to set-visited-file-name followed by C-x C-s, except that C-x C-w asks for confirmation if the file exists. C-x C-s used on a buffer that is not visiting a file has the same effect as C-x C-w; that is, it reads a file name, marks the buffer as visiting that file, and saves it there. The default file name in a buffer that is not visiting a file is made by combining the buffer name with the buffer’s default directory (see section File Names).

If the new file name implies a major mode, then C-x C-w switches to that major mode, in most cases. The command set-visited-file-name also does this. @xref{Choosing Modes}.

If Emacs is about to save a file and sees that the date of the latest version on disk does not match what Emacs last read or wrote, Emacs notifies you of this fact, because it probably indicates a problem caused by simultaneous editing and requires your immediate attention. See section Simultaneous Editing.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3.2 Backup Files

On most operating systems, rewriting a file automatically destroys all record of what the file used to contain. Thus, saving a file from Emacs throws away the old contents of the file—or it would, except that Emacs carefully copies the old contents to another file, called the backup file, before actually saving.

Emacs makes a backup for a file only the first time the file is saved from a buffer. No matter how many times you subsequently save the file, its backup remains unchanged. However, if you kill the buffer and then visit the file again, a new backup file will be made.

For most files, the variable make-backup-files determines whether to make backup files. On most operating systems, its default value is t, so that Emacs does write backup files.

For files managed by a version control system (@pxref{Version Control}), the variable vc-make-backup-files determines whether to make backup files. By default it is nil, since backup files are redundant when you store all the previous versions in a version control system. @xref{General VC Options}.

At your option, Emacs can keep either a single backup for each file, or make a series of numbered backup files for each file that you edit. See section Single or Numbered Backups.

The default value of the backup-enable-predicate variable prevents backup files being written for files in the directories used for temporary files, specified by temporary-file-directory or small-temporary-file-directory.

You can explicitly tell Emacs to make another backup file from a buffer, even though that buffer has been saved before. If you save the buffer with C-u C-x C-s, the version thus saved will be made into a backup file if you save the buffer again. C-u C-u C-x C-s saves the buffer, but first makes the previous file contents into a new backup file. C-u C-u C-u C-x C-s does both things: it makes a backup from the previous contents, and arranges to make another from the newly saved contents if you save again.

You can customize the variable backup-directory-alist to specify that files matching certain patterns should be backed up in specific directories. A typical use is to add an element ("." . dir) to make all backups in the directory with absolute name dir. Emacs modifies the backup file names to avoid clashes between files with the same names originating in different directories. Alternatively, adding, ("." . ".~") would make backups in the invisible subdirectory ‘.~’ of the original file’s directory. Emacs creates the directory, if necessary, to make the backup.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ] Single or Numbered Backups

When Emacs makes a backup file, its name is normally constructed by appending ‘~’ to the file name being edited; thus, the backup file for ‘eval.c’ would be ‘eval.c~’.

If access control stops Emacs from writing backup files under the usual names, it writes the backup file as ‘~/.emacs.d/%backup%~’. Only one such file can exist, so only the most recently made such backup is available.

Emacs can also make numbered backup files. Numbered backup file names contain ‘.~’, the number, and another ‘~’ after the original file name. Thus, the backup files of ‘eval.c’ would be called ‘eval.c.~1~’, ‘eval.c.~2~’, and so on, all the way through names like ‘eval.c.~259~’ and beyond.

The variable version-control determines whether to make single backup files or multiple numbered backup files. Its possible values are:


Make numbered backups for files that have numbered backups already. Otherwise, make single backups. This is the default.


Make numbered backups.


Never make numbered backups; always make single backups.

The usual way to set this variable is globally, through your init file or the customization buffer. However, you can set version-control locally in an individual buffer to control the making of backups for that buffer’s file (@pxref{Locals}). You can have Emacs set version-control locally whenever you visit a given file (@pxref{File Variables}). Some modes, such as Rmail mode, set this variable.

If you set the environment variable VERSION_CONTROL, to tell various GNU utilities what to do with backup files, Emacs also obeys the environment variable by setting the Lisp variable version-control accordingly at startup. If the environment variable’s value is ‘t’ or ‘numbered’, then version-control becomes t; if the value is ‘nil’ or ‘existing’, then version-control becomes nil; if it is ‘never’ or ‘simple’, then version-control becomes never.

If you set the variable make-backup-file-name-function to a suitable Lisp function, you can override the usual way Emacs constructs backup file names.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ] Automatic Deletion of Backups

To prevent excessive consumption of disk space, Emacs can delete numbered backup versions automatically. Generally Emacs keeps the first few backups and the latest few backups, deleting any in between. This happens every time a new backup is made.

The two variables kept-old-versions and kept-new-versions control this deletion. Their values are, respectively, the number of oldest (lowest-numbered) backups to keep and the number of newest (highest-numbered) ones to keep, each time a new backup is made. The backups in the middle (excluding those oldest and newest) are the excess middle versions—those backups are deleted. These variables’ values are used when it is time to delete excess versions, just after a new backup version is made; the newly made backup is included in the count in kept-new-versions. By default, both variables are 2.

If delete-old-versions is t, Emacs deletes the excess backup files silently. If it is nil, the default, Emacs asks you whether it should delete the excess backup versions. If it has any other value, then Emacs never automatically deletes backups.

Dired’s . (Period) command can also be used to delete old versions. @xref{Dired Deletion}.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ] Copying vs. Renaming

Backup files can be made by copying the old file or by renaming it. This makes a difference when the old file has multiple names (hard links). If the old file is renamed into the backup file, then the alternate names become names for the backup file. If the old file is copied instead, then the alternate names remain names for the file that you are editing, and the contents accessed by those names will be the new contents.

The method of making a backup file may also affect the file’s owner and group. If copying is used, these do not change. If renaming is used, you become the file’s owner, and the file’s group becomes the default (different operating systems have different defaults for the group).

The choice of renaming or copying is made as follows:

When a file is managed with a version control system (@pxref{Version Control}), Emacs does not normally make backups in the usual way for that file. But check-in and check-out are similar in some ways to making backups. One unfortunate similarity is that these operations typically break hard links, disconnecting the file name you visited from any alternate names for the same file. This has nothing to do with Emacs—the version control system does it.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3.3 Customizing Saving of Files

If the value of the variable require-final-newline is t, saving or writing a file silently puts a newline at the end if there isn’t already one there. If the value is visit, Emacs adds a newline at the end of any file that doesn’t have one, just after it visits the file. (This marks the buffer as modified, and you can undo it.) If the value is visit-save, Emacs adds such newlines both on visiting and on saving. If the value is nil, Emacs leaves the end of the file unchanged; any other non-nil value means Emacs asks you whether to add a newline. The default is nil.

Some major modes are designed for specific kinds of files that are always supposed to end in newlines. Such major modes set the variable require-final-newline to the value of mode-require-final-newline, which defaults to t. By setting the latter variable, you can control how these modes handle final newlines.

Normally, when a program writes a file, the operating system briefly caches the file’s data in main memory before committing the data to disk. This can greatly improve performance; for example, when running on laptops, it can avoid a disk spin-up each time a file is written. However, it risks data loss if the operating system crashes before committing the cache to disk.

To lessen this risk, Emacs can invoke the fsync system call after saving a file. Using fsync does not eliminate the risk of data loss, partly because many systems do not implement fsync properly, and partly because Emacs’s file-saving procedure typically relies also on directory updates that might not survive a crash even if fsync works properly.

The write-region-inhibit-fsync variable controls whether Emacs invokes fsync after saving a file. The variable’s default value is nil when Emacs is interactive, and t when Emacs runs in batch mode.

Emacs never uses fsync when writing auto-save files, as these files might lose data anyway.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3.4 Protection against Simultaneous Editing

Simultaneous editing occurs when two users visit the same file, both make changes, and then both save them. If nobody is informed that this is happening, whichever user saves first would later find that his changes were lost.

On some systems, Emacs notices immediately when the second user starts to change the file, and issues an immediate warning. On all systems, Emacs checks when you save the file, and warns if you are about to overwrite another user’s changes. You can prevent loss of the other user’s work by taking the proper corrective action instead of saving the file.

When you make the first modification in an Emacs buffer that is visiting a file, Emacs records that the file is locked by you. (It does this by creating a specially-named symbolic link(1) with special contents in the same directory.) Emacs removes the lock when you save the changes. The idea is that the file is locked whenever an Emacs buffer visiting it has unsaved changes.

You can prevent the creation of lock files by setting the variable create-lockfiles to nil. Caution: by doing so you will lose the benefits that this feature provides.

If you begin to modify the buffer while the visited file is locked by someone else, this constitutes a collision. When Emacs detects a collision, it asks you what to do, by calling the Lisp function ask-user-about-lock. You can redefine this function for the sake of customization. The standard definition of this function asks you a question and accepts three possible answers:


Steal the lock. Whoever was already changing the file loses the lock, and you gain the lock.


Proceed. Go ahead and edit the file despite its being locked by someone else.


Quit. This causes an error (file-locked), and the buffer contents remain unchanged—the modification you were trying to make does not actually take place.

If Emacs or the operating system crashes, this may leave behind lock files which are stale, so you may occasionally get warnings about spurious collisions. When you determine that the collision is spurious, just use p to tell Emacs to go ahead anyway.

Note that locking works on the basis of a file name; if a file has multiple names, Emacs does not prevent two users from editing it simultaneously under different names.

A lock file cannot be written in some circumstances, e.g., if Emacs lacks the system permissions or cannot create lock files for some other reason. In these cases, Emacs can still detect the collision when you try to save a file, by checking the file’s last-modification date. If the file has changed since the last time Emacs visited or saved it, that implies that changes have been made in some other way, and will be lost if Emacs proceeds with saving. Emacs then displays a warning message and asks for confirmation before saving; answer yes to save, and no or C-g cancel the save.

If you are notified that simultaneous editing has already taken place, one way to compare the buffer to its file is the M-x diff-buffer-with-file command. See section Comparing Files.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3.5 Shadowing Files

M-x shadow-initialize

Set up file shadowing.

M-x shadow-define-literal-group

Declare a single file to be shared between sites.

M-x shadow-define-regexp-group

Make all files that match each of a group of files be shared between hosts.

M-x shadow-define-cluster <RET> name <RET>

Define a shadow file cluster name.

M-x shadow-copy-files

Copy all pending shadow files.

M-x shadow-cancel

Cancel the instruction to shadow some files.

You can arrange to keep identical shadow copies of certain files in more than one place—possibly on different machines. To do this, first you must set up a shadow file group, which is a set of identically-named files shared between a list of sites. The file group is permanent and applies to further Emacs sessions as well as the current one. Once the group is set up, every time you exit Emacs, it will copy the file you edited to the other files in its group. You can also do the copying without exiting Emacs, by typing M-x shadow-copy-files.

To set up a shadow file group, use M-x shadow-define-literal-group or M-x shadow-define-regexp-group. See their documentation strings for further information.

Before copying a file to its shadows, Emacs asks for confirmation. You can answer “no” to bypass copying of this file, this time. If you want to cancel the shadowing permanently for a certain file, use M-x shadow-cancel to eliminate or change the shadow file group.

A shadow cluster is a group of hosts that share directories, so that copying to or from one of them is sufficient to update the file on all of them. Each shadow cluster has a name, and specifies the network address of a primary host (the one we copy files to), and a regular expression that matches the host names of all the other hosts in the cluster. You can define a shadow cluster with M-x shadow-define-cluster.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3.6 Updating Time Stamps Automatically

You can arrange to put a time stamp in a file, so that it is updated automatically each time you edit and save the file. The time stamp must be in the first eight lines of the file, and you should insert it like this:

Time-stamp: <>

or like this:

Time-stamp: " "

Then add the function time-stamp to the hook before-save-hook (@pxref{Hooks}). When you save the file, this function then automatically updates the time stamp with the current date and time. You can also use the command M-x time-stamp to update the time stamp manually. By default the time stamp is formatted according to your locale setting (@pxref{Environment}) and time zone (see Time of Day in The Emacs Lisp Reference Manual). For customizations, see the Custom group time-stamp.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 Reverting a Buffer

If you have made extensive changes to a file-visiting buffer and then change your mind, you can revert the changes and go back to the saved version of the file. To do this, type M-x revert-buffer. Since reverting unintentionally could lose a lot of work, Emacs asks for confirmation first.

The revert-buffer command tries to position point in such a way that, if the file was edited only slightly, you will be at approximately the same part of the text as before. But if you have made major changes, point may end up in a totally different location.

Reverting marks the buffer as not modified. It also clears the buffer’s undo history (@pxref{Undo}). Thus, the reversion cannot be undone—if you change your mind yet again, you can’t use the undo commands to bring the reverted changes back.

Some kinds of buffers that are not associated with files, such as Dired buffers, can also be reverted. For them, reverting means recalculating their contents. Buffers created explicitly with C-x b cannot be reverted; revert-buffer reports an error if you try.

When you edit a file that changes automatically and frequently—for example, a log of output from a process that continues to run—it may be useful for Emacs to revert the file without querying you. To request this behavior, set the variable revert-without-query to a list of regular expressions. When a file name matches one of these regular expressions, find-file and revert-buffer will revert it automatically if it has changed—provided the buffer itself is not modified. (If you have edited the text, it would be wrong to discard your changes.)

You can also tell Emacs to revert buffers periodically. To do this for a specific buffer, enable the minor mode Auto-Revert mode by typing M-x auto-revert-mode. This automatically reverts the current buffer every five seconds; you can change the interval through the variable auto-revert-interval. To do the same for all file buffers, type M-x global-auto-revert-mode to enable Global Auto-Revert mode. These minor modes do not check or revert remote files, because that is usually too slow. This behavior can be changed by setting the variable auto-revert-remote-files to non-nil.

One use of Auto-Revert mode is to “tail” a file such as a system log, so that changes made to that file by other programs are continuously displayed. To do this, just move the point to the end of the buffer, and it will stay there as the file contents change. However, if you are sure that the file will only change by growing at the end, use Auto-Revert Tail mode instead (auto-revert-tail-mode). It is more efficient for this. Auto-Revert Tail mode works also for remote files.

When a buffer is auto-reverted, a message is generated. This can be suppressed by setting auto-revert-verbose to nil.

@xref{VC Undo}, for commands to revert to earlier versions of files under version control. @xref{VC Mode Line}, for Auto Revert peculiarities when visiting files under version control.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5 Auto Reverting Non-File Buffers

Global Auto Revert Mode normally only reverts file buffers. There are two ways to auto-revert certain non-file buffers: by enabling Auto Revert Mode in those buffers (using M-x auto-revert-mode); and by setting global-auto-revert-non-file-buffers to a non-nil value. The latter enables Auto Reverting for all types of buffers for which it is implemented (listed in the menu below).

Like file buffers, non-file buffers should normally not revert while you are working on them, or while they contain information that might get lost after reverting. Therefore, they do not revert if they are modified. This can get tricky, because deciding when a non-file buffer should be marked modified is usually more difficult than for file buffers.

Another tricky detail is that, for efficiency reasons, Auto Revert often does not try to detect all possible changes in the buffer, only changes that are major or easy to detect. Hence, enabling auto-reverting for a non-file buffer does not always guarantee that all information in the buffer is up-to-date, and does not necessarily make manual reverts useless.

At the other extreme, certain buffers automatically revert every auto-revert-interval seconds. (This currently only applies to the Buffer Menu.) In this case, Auto Revert does not print any messages while reverting, even when auto-revert-verbose is non-nil.

The details depend on the particular types of buffers and are explained in the corresponding sections.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5.1 Auto Reverting the Buffer Menu

If auto-reverting of non-file buffers is enabled, the Buffer Menu (@pxref{Several Buffers}) automatically reverts every auto-revert-interval seconds, whether there is a need for it or not. (It would probably take longer to check whether there is a need than to actually revert.)

If the Buffer Menu inappropriately gets marked modified, just revert it manually using g and auto-reverting will resume. However, if you marked certain buffers to get deleted or to be displayed, you have to be careful, because reverting erases all marks. The fact that adding marks sets the buffer’s modified flag prevents Auto Revert from automatically erasing the marks.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5.2 Auto Reverting Dired buffers

Auto-reverting Dired buffers currently works on GNU or Unix style operating systems. It may not work satisfactorily on some other systems.

Dired buffers only auto-revert when the file list of the buffer’s main directory changes (e.g., when a new file is added). They do not auto-revert when information about a particular file changes (e.g., when the size changes) or when inserted subdirectories change. To be sure that all listed information is up to date, you have to manually revert using g, even if auto-reverting is enabled in the Dired buffer. Sometimes, you might get the impression that modifying or saving files listed in the main directory actually does cause auto-reverting. This is because making changes to a file, or saving it, very often causes changes in the directory itself; for instance, through backup files or auto-save files. However, this is not guaranteed.

If the Dired buffer is marked modified and there are no changes you want to protect, then most of the time you can make auto-reverting resume by manually reverting the buffer using g. There is one exception. If you flag or mark files, you can safely revert the buffer. This will not erase the flags or marks (unless the marked file has been deleted, of course). However, the buffer will stay modified, even after reverting, and auto-reverting will not resume. This is because, if you flag or mark files, you may be working on the buffer and you might not want the buffer to change without warning. If you want auto-reverting to resume in the presence of marks and flags, mark the buffer non-modified using M-~. However, adding, deleting or changing marks or flags will mark it modified again.

Remote Dired buffers are not auto-reverted (because it may be slow). Neither are Dired buffers for which you used shell wildcards or file arguments to list only some of the files. ‘*Find*’ and ‘*Locate*’ buffers do not auto-revert either.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5.3 Adding Support for Auto-Reverting additional Buffers.

This section is intended for Elisp programmers who would like to add support for auto-reverting new types of buffers.

To support auto-reverting the buffer must first of all have a suitable revert-buffer-function. See Reverting in the Emacs Lisp Reference Manual.

In addition, it must have a suitable buffer-stale-function.

Variable: buffer-stale-function

The value of this variable is a function to check whether a buffer needs reverting. This should be a function with one optional argument noconfirm. The function should return non-nil if the buffer should be reverted. The buffer is current when this function is called.

While this function is mainly intended for use in auto-reverting, it could be used for other purposes as well. For instance, if auto-reverting is not enabled, it could be used to warn the user that the buffer needs reverting. The idea behind the noconfirm argument is that it should be t if the buffer is going to be reverted without asking the user and nil if the function is just going to be used to warn the user that the buffer is out of date. In particular, for use in auto-reverting, noconfirm is t. If the function is only going to be used for auto-reverting, you can ignore the noconfirm argument.

If you just want to automatically auto-revert every auto-revert-interval seconds (like the Buffer Menu), use:

(setq-local buffer-stale-function
     #'(lambda (&optional noconfirm) 'fast))

in the buffer’s mode function.

The special return value ‘fast’ tells the caller that the need for reverting was not checked, but that reverting the buffer is fast. It also tells Auto Revert not to print any revert messages, even if auto-revert-verbose is non-nil. This is important, as getting revert messages every auto-revert-interval seconds can be very annoying. The information provided by this return value could also be useful if the function is consulted for purposes other than auto-reverting.

Once the buffer has a suitable revert-buffer-function and buffer-stale-function, several problems usually remain.

The buffer will only auto-revert if it is marked unmodified. Hence, you will have to make sure that various functions mark the buffer modified if and only if either the buffer contains information that might be lost by reverting, or there is reason to believe that the user might be inconvenienced by auto-reverting, because he is actively working on the buffer. The user can always override this by manually adjusting the modified status of the buffer. To support this, calling the revert-buffer-function on a buffer that is marked unmodified should always keep the buffer marked unmodified.

It is important to assure that point does not continuously jump around as a consequence of auto-reverting. Of course, moving point might be inevitable if the buffer radically changes.

You should make sure that the revert-buffer-function does not print messages that unnecessarily duplicate Auto Revert’s own messages, displayed if auto-revert-verbose is t, and effectively override a nil value for auto-revert-verbose. Hence, adapting a mode for auto-reverting often involves getting rid of such messages. This is especially important for buffers that automatically revert every auto-revert-interval seconds.

If the new auto-reverting is part of Emacs, you should mention it in the documentation string of global-auto-revert-non-file-buffers.

Similarly, you should add a section to this chapter. This section should at the very least make clear whether enabling auto-reverting for the buffer reliably assures that all information in the buffer is completely up to date (or will be after auto-revert-interval seconds).

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6 Auto-Saving: Protection Against Disasters

From time to time, Emacs automatically saves each visited file in a separate file, without altering the file you actually use. This is called auto-saving. It prevents you from losing more than a limited amount of work if the system crashes.

When Emacs determines that it is time for auto-saving, it considers each buffer, and each is auto-saved if auto-saving is enabled for it and it has been changed since the last time it was auto-saved. The message ‘Auto-saving...’ is displayed in the echo area during auto-saving, if any files are actually auto-saved. Errors occurring during auto-saving are caught so that they do not interfere with the execution of commands you have been typing.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6.1 Auto-Save Files

Auto-saving does not normally save in the files that you visited, because it can be very undesirable to save a change that you did not want to make permanent. Instead, auto-saving is done in a different file called the auto-save file, and the visited file is changed only when you request saving explicitly (such as with C-x C-s).

Normally, the auto-save file name is made by appending ‘#’ to the front and rear of the visited file name. Thus, a buffer visiting file ‘foo.c’ is auto-saved in a file ‘#foo.c#’. Most buffers that are not visiting files are auto-saved only if you request it explicitly; when they are auto-saved, the auto-save file name is made by appending ‘#’ to the front and rear of buffer name, then adding digits and letters at the end for uniqueness. For example, the ‘*mail*’ buffer in which you compose messages to be sent might be auto-saved in a file named ‘#*mail*#704juu’. Auto-save file names are made this way unless you reprogram parts of Emacs to do something different (the functions make-auto-save-file-name and auto-save-file-name-p). The file name to be used for auto-saving in a buffer is calculated when auto-saving is turned on in that buffer.

The variable auto-save-file-name-transforms allows a degree of control over the auto-save file name. It lets you specify a series of regular expressions and replacements to transform the auto save file name. The default value puts the auto-save files for remote files (see section Remote Files) into the temporary file directory on the local machine.

When you delete a substantial part of the text in a large buffer, auto save turns off temporarily in that buffer. This is because if you deleted the text unintentionally, you might find the auto-save file more useful if it contains the deleted text. To reenable auto-saving after this happens, save the buffer with C-x C-s, or use C-u 1 M-x auto-save-mode.

If you want auto-saving to be done in the visited file rather than in a separate auto-save file, set the variable auto-save-visited-file-name to a non-nil value. In this mode, auto-saving is very similar to explicit saving. However, differences still exist, in particular for modes which modify the buffer-saving process in non-trivial ways via various hooks (see Saving Buffers in The Emacs Lisp Reference Manual).

A buffer’s auto-save file is deleted when you save the buffer in its visited file. (You can inhibit this by setting the variable delete-auto-save-files to nil.) Changing the visited file name with C-x C-w or set-visited-file-name renames any auto-save file to go with the new visited name.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6.2 Controlling Auto-Saving

Each time you visit a file, auto-saving is turned on for that file’s buffer if the variable auto-save-default is non-nil (but not in batch mode; @pxref{Initial Options}). The default for this variable is t, so auto-saving is the usual practice for file-visiting buffers. To toggle auto-saving in the current buffer, type M-x auto-save-mode. Auto Save mode acts as a buffer-local minor mode (@pxref{Minor Modes}).

Emacs auto-saves periodically based on how many characters you have typed since the last auto-save. The variable auto-save-interval specifies how many characters there are between auto-saves. By default, it is 300. Emacs doesn’t accept values that are too small: if you customize auto-save-interval to a value less than 20, Emacs will behave as if the value is 20.

Auto-saving also takes place when you stop typing for a while. By default, it does this after 30 seconds of idleness (at this time, Emacs may also perform garbage collection; see Garbage Collection in The Emacs Lisp Reference Manual). To change this interval, customize the variable auto-save-timeout. The actual time period is longer if the current buffer is long; this is a heuristic which aims to keep out of your way when you are editing long buffers, in which auto-save takes an appreciable amount of time. Auto-saving during idle periods accomplishes two things: first, it makes sure all your work is saved if you go away from the terminal for a while; second, it may avoid some auto-saving while you are actually typing.

Emacs also does auto-saving whenever it gets a fatal error. This includes killing the Emacs job with a shell command such as ‘kill %emacs’, or disconnecting a phone line or network connection.

You can perform an auto-save explicitly with the command M-x do-auto-save.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6.3 Recovering Data from Auto-Saves

You can use the contents of an auto-save file to recover from a loss of data with the command M-x recover-file <RET> file <RET>. This visits file and then (after your confirmation) restores the contents from its auto-save file ‘#file#’. You can then save with C-x C-s to put the recovered text into file itself. For example, to recover file ‘foo.c’ from its auto-save file ‘#foo.c#’, do:

M-x recover-file <RET> foo.c <RET>
yes <RET>
C-x C-s

Before asking for confirmation, M-x recover-file displays a directory listing describing the specified file and the auto-save file, so you can compare their sizes and dates. If the auto-save file is older, M-x recover-file does not offer to read it.

If Emacs or the computer crashes, you can recover all the files you were editing from their auto save files with the command M-x recover-session. This first shows you a list of recorded interrupted sessions. Move point to the one you choose, and type C-c C-c.

Then recover-session asks about each of the files that were being edited during that session, asking whether to recover that file. If you answer y, it calls recover-file, which works in its normal fashion. It shows the dates of the original file and its auto-save file, and asks once again whether to recover that file.

When recover-session is done, the files you’ve chosen to recover are present in Emacs buffers. You should then save them. Only this—saving them—updates the files themselves.

Emacs records information about interrupted sessions in files named ‘.saves-pid-hostname’ in the directory ‘~/.emacs.d/auto-save-list/’. This directory is determined by the variable auto-save-list-file-prefix. If you set auto-save-list-file-prefix to nil, sessions are not recorded for recovery.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.7 File Name Aliases

Symbolic links and hard links both make it possible for several file names to refer to the same file. Hard links are alternate names that refer directly to the file; all the names are equally valid, and no one of them is preferred. By contrast, a symbolic link is a kind of defined alias: when ‘foo’ is a symbolic link to ‘bar’, you can use either name to refer to the file, but ‘bar’ is the real name, while ‘foo’ is just an alias. More complex cases occur when symbolic links point to directories.

Normally, if you visit a file which Emacs is already visiting under a different name, Emacs displays a message in the echo area and uses the existing buffer visiting that file. This can happen on systems that support hard or symbolic links, or if you use a long file name on a system that truncates long file names, or on a case-insensitive file system. You can suppress the message by setting the variable find-file-suppress-same-file-warnings to a non-nil value. You can disable this feature entirely by setting the variable find-file-existing-other-name to nil: then if you visit the same file under two different names, you get a separate buffer for each file name.

If the variable find-file-visit-truename is non-nil, then the file name recorded for a buffer is the file’s truename (made by replacing all symbolic links with their target names), rather than the name you specify. Setting find-file-visit-truename also implies the effect of find-file-existing-other-name.

Sometimes, a directory is ordinarily accessed through a symbolic link, and you may want Emacs to preferentially show its linked name. To do this, customize directory-abbrev-alist. Each element in this list should have the form (from . to), which means to replace from with to whenever from appears in a directory name. The from string is a regular expression (@pxref{Regexps}). It is matched against directory names anchored at the first character, and should start with ‘\`’ (to support directory names with embedded newlines, which would defeat ‘^’). The to string should be an ordinary absolute directory name pointing to the same directory. Do not use ‘~’ to stand for a home directory in the to string; Emacs performs these substitutions separately. Here’s an example, from a system on which ‘/home/fsf’ is normally accessed through a symbolic link named ‘/fsf’:

(("\\`/home/fsf" . "/fsf"))

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.8 File Directories

The file system groups files into directories. A directory listing is a list of all the files in a directory. Emacs provides commands to create and delete directories, and to make directory listings in brief format (file names only) and verbose format (sizes, dates, and authors included). Emacs also includes a directory browser feature called Dired; see @ref{Dired}.

C-x C-d dir-or-pattern <RET>

Display a brief directory listing (list-directory).

C-u C-x C-d dir-or-pattern <RET>

Display a verbose directory listing.

M-x make-directory <RET> dirname <RET>

Create a new directory named dirname.

M-x delete-directory <RET> dirname <RET>

Delete the directory named dirname. If it isn’t empty, you will be asked whether you want to delete it recursively.

The command to display a directory listing is C-x C-d (list-directory). It reads using the minibuffer a file name which is either a directory to be listed or a wildcard-containing pattern for the files to be listed. For example,

C-x C-d /u2/emacs/etc <RET>

lists all the files in directory ‘/u2/emacs/etc’. Here is an example of specifying a file name pattern:

C-x C-d /u2/emacs/src/*.c <RET>

Normally, C-x C-d displays a brief directory listing containing just file names. A numeric argument (regardless of value) tells it to make a verbose listing including sizes, dates, and owners (like ‘ls -l’).

The text of a directory listing is mostly obtained by running ls in an inferior process. Two Emacs variables control the switches passed to ls: list-directory-brief-switches is a string giving the switches to use in brief listings ("-CF" by default), and list-directory-verbose-switches is a string giving the switches to use in a verbose listing ("-l" by default).

In verbose directory listings, Emacs adds information about the amount of free space on the disk that contains the directory. To do this, it runs the program specified by directory-free-space-program with arguments directory-free-space-args.

The command M-x delete-directory prompts for a directory name using the minibuffer, and deletes the directory if it is empty. If the directory is not empty, you will be asked whether you want to delete it recursively. On systems that have a “Trash” (or “Recycle Bin”) feature, you can make this command move the specified directory to the Trash instead of deleting it outright, by changing the variable delete-by-moving-to-trash to t. See section Miscellaneous File Operations, for more information about using the Trash.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.9 Comparing Files

The command M-x diff prompts for two file names, using the minibuffer, and displays the differences between the two files in a buffer named ‘*diff*’. This works by running the diff program, using options taken from the variable diff-switches. The value of diff-switches should be a string; the default is "-u" to specify a unified context diff. See Diff in Comparing and Merging Files, for more information about the diff program.

The output of the diff command is shown using a major mode called Diff mode. See section Diff Mode.

The command M-x diff-backup compares a specified file with its most recent backup. If you specify the name of a backup file, diff-backup compares it with the source file that it is a backup of. In all other respects, this behaves like M-x diff.

The command M-x diff-buffer-with-file compares a specified buffer with its corresponding file. This shows you what changes you would make to the file if you save the buffer.

The command M-x compare-windows compares the text in the current window with that in the window that was the selected window before you selected the current one. (For more information about windows in Emacs, @ref{Windows}.) Comparison starts at point in each window, after pushing each initial point value on the mark ring in its respective buffer. Then it moves point forward in each window, one character at a time, until it reaches characters that don’t match. Then the command exits.

If point in the two windows is followed by non-matching text when the command starts, M-x compare-windows tries heuristically to advance up to matching text in the two windows, and then exits. So if you use M-x compare-windows repeatedly, each time it either skips one matching range or finds the start of another.

With a numeric argument, compare-windows ignores changes in whitespace. If the variable compare-ignore-case is non-nil, the comparison ignores differences in case as well. If the variable compare-ignore-whitespace is non-nil, compare-windows normally ignores changes in whitespace, and a prefix argument turns that off.

You can use M-x smerge-mode to turn on Smerge mode, a minor mode for editing output from the diff3 program. This is typically the result of a failed merge from a version control system update outside VC, due to conflicting changes to a file. Smerge mode provides commands to resolve conflicts by selecting specific changes.

@xref{Emerge}, for the Emerge facility, which provides a powerful interface for merging files.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.10 Diff Mode

Diff mode is a major mode used for the output of M-x diff and other similar commands. This kind of output is called a patch, because it can be passed to the patch command to automatically apply the specified changes. To select Diff mode manually, type M-x diff-mode.

The changes specified in a patch are grouped into hunks, which are contiguous chunks of text that contain one or more changed lines. Hunks can also include unchanged lines to provide context for the changes. Each hunk is preceded by a hunk header, which specifies the old and new line numbers at which the hunk occurs. Diff mode highlights each hunk header, to distinguish it from the actual contents of the hunk.

You can edit a Diff mode buffer like any other buffer. (If it is read-only, you need to make it writable first. @xref{Misc Buffer}.) Whenever you change a hunk, Diff mode attempts to automatically correct the line numbers in the hunk headers, to ensure that the patch remains correct. To disable automatic line number correction, change the variable diff-update-on-the-fly to nil.

Diff mode treats each hunk as an error message, similar to Compilation mode. Thus, you can use commands such as C-x ` to visit the corresponding source locations. @xref{Compilation Mode}.

In addition, Diff mode provides the following commands to navigate, manipulate and apply parts of patches:


Move to the next hunk-start (diff-hunk-next).

This command has a side effect: it refines the hunk you move to, highlighting its changes with better granularity. To disable this feature, type M-x diff-auto-refine-mode to toggle off the minor mode Diff Auto-Refine mode. To disable Diff Auto Refine mode by default, add this to your init file (@pxref{Hooks}):

(add-hook 'diff-mode-hook
          (lambda () (diff-auto-refine-mode -1)))

Move to the previous hunk-start (diff-hunk-prev). Like M-n, this has the side-effect of refining the hunk you move to, unless you disable Diff Auto-Refine mode.


Move to the next file-start, in a multi-file patch (diff-file-next).


Move to the previous file-start, in a multi-file patch (diff-file-prev).


Kill the hunk at point (diff-hunk-kill).


In a multi-file patch, kill the current file part. (diff-file-kill).

C-c C-a

Apply this hunk to its target file (diff-apply-hunk). With a prefix argument of C-u, revert this hunk.

C-c C-b

Highlight the changes of the hunk at point with a finer granularity (diff-refine-hunk). This allows you to see exactly which parts of each changed line were actually changed.

C-c C-c

Go to the source file and line corresponding to this hunk (diff-goto-source).

C-c C-e

Start an Ediff session with the patch (diff-ediff-patch). See Ediff in The Ediff Manual.

C-c C-n

Restrict the view to the current hunk (diff-restrict-view). @xref{Narrowing}. With a prefix argument of C-u, restrict the view to the current file of a multiple-file patch. To widen again, use C-x n w (widen).

C-c C-r

Reverse the direction of comparison for the entire buffer (diff-reverse-direction).

C-c C-s

Split the hunk at point (diff-split-hunk). This is for manually editing patches, and only works with the unified diff format produced by the ‘-u’ or ‘--unified’ options to the diff program. If you need to split a hunk in the context diff format produced by the ‘-c’ or ‘--context’ options to diff, first convert the buffer to the unified diff format with C-c C-u.

C-c C-d

Convert the entire buffer to the context diff format (diff-unified->context). With a prefix argument, convert only the text within the region.

C-c C-u

Convert the entire buffer to unified diff format (diff-context->unified). With a prefix argument, convert unified format to context format. When the mark is active, convert only the text within the region.

C-c C-w

Re-diff the current hunk, disregarding changes in whitespace (diff-ignore-whitespace-hunk).

C-x 4 A

Generate a ChangeLog entry, like C-x 4 a does (@pxref{Change Log}), for each one of the hunks (diff-add-change-log-entries-other-window). This creates a skeleton of the log of changes that you can later fill with the actual descriptions of the changes. C-x 4 a itself in Diff mode operates on behalf of the current hunk’s file, but gets the function name from the patch itself. This is useful for making log entries for functions that are deleted by the patch.

Patches sometimes include trailing whitespace on modified lines, as an unintentional and undesired change. There are two ways to deal with this problem. Firstly, if you enable Whitespace mode in a Diff buffer (@pxref{Useless Whitespace}), it automatically highlights trailing whitespace in modified lines. Secondly, you can use the command M-x diff-delete-trailing-whitespace, which searches for trailing whitespace in the lines modified by the patch, and removes that whitespace in both the patch and the patched source file(s). This command does not save the modifications that it makes, so you can decide whether to save the changes (the list of modified files is displayed in the echo area). With a prefix argument, it tries to modify the original source files rather than the patched source files.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.11 Miscellaneous File Operations

Emacs has commands for performing many other operations on files. All operate on one file; they do not accept wildcard file names.

M-x delete-file prompts for a file and deletes it. If you are deleting many files in one directory, it may be more convenient to use Dired rather than delete-file. @xref{Dired Deletion}.

M-x move-file-to-trash moves a file into the system Trash (or Recycle Bin). This is a facility available on most operating systems; files that are moved into the Trash can be brought back later if you change your mind.

By default, Emacs deletion commands do not use the Trash. To use the Trash (when it is available) for common deletion commands, change the variable delete-by-moving-to-trash to t. This affects the commands M-x delete-file and M-x delete-directory (see section File Directories), as well as the deletion commands in Dired (@pxref{Dired Deletion}). Supplying a prefix argument to M-x delete-file or M-x delete-directory makes them delete outright, instead of using the Trash, regardless of delete-by-moving-to-trash.

If a file is under version control (@pxref{Version Control}), you should delete it using M-x vc-delete-file instead of M-x delete-file. @xref{VC Delete/Rename}.

M-x copy-file reads the file old and writes a new file named new with the same contents.

M-x copy-directory copies directories, similar to the cp -r shell command. It prompts for a directory old and a destination new. If new is an existing directory, it creates a copy of the old directory and puts it in new. If new is not an existing directory, it copies all the contents of old into a new directory named new.

M-x rename-file reads two file names old and new using the minibuffer, then renames file old as new. If the file name new already exists, you must confirm with yes or renaming is not done; this is because renaming causes the old meaning of the name new to be lost. If old and new are on different file systems, the file old is copied and deleted. If the argument new is just a directory name, the real new name is in that directory, with the same non-directory component as old. For example, M-x rename-file <RET> ~/foo <RET> /tmp <RET> renames ‘~/foo’ to ‘/tmp/foo’. The same rule applies to all the remaining commands in this section. All of them ask for confirmation when the new file name already exists, too.

If a file is under version control (@pxref{Version Control}), you should rename it using M-x vc-rename-file instead of M-x rename-file. @xref{VC Delete/Rename}.

M-x add-name-to-file adds an additional name to an existing file without removing its old name. The new name is created as a hard link to the existing file. The new name must belong on the same file system that the file is on. On MS-Windows, this command works only if the file resides in an NTFS file system. On MS-DOS, it works by copying the file.

M-x make-symbolic-link reads two file names target and linkname, then creates a symbolic link named linkname, which points at target. The effect is that future attempts to open file linkname will refer to whatever file is named target at the time the opening is done, or will get an error if the name target is nonexistent at that time. This command does not expand the argument target, so that it allows you to specify a relative name as the target of the link. On MS-Windows, this command works only on MS Windows Vista and later.

M-x insert-file (also C-x i) inserts a copy of the contents of the specified file into the current buffer at point, leaving point unchanged before the contents. The position after the inserted contents is added to the mark ring, without activating the mark (@pxref{Mark Ring}).

M-x insert-file-literally is like M-x insert-file, except the file is inserted literally: it is treated as a sequence of ASCII characters with no special encoding or conversion, similar to the M-x find-file-literally command (see section Visiting Files).

M-x write-region is the inverse of M-x insert-file; it copies the contents of the region into the specified file. M-x append-to-file adds the text of the region to the end of the specified file. @xref{Accumulating Text}. The variable write-region-inhibit-fsync applies to these commands, as well as saving files; see Customizing Saving of Files.

M-x set-file-modes reads a file name followed by a file mode, and applies that file mode to the specified file. File modes, also called file permissions, determine whether a file can be read, written to, or executed, and by whom. This command reads file modes using the same symbolic or octal format accepted by the chmod command; for instance, ‘u+x’ means to add execution permission for the user who owns the file. It has no effect on operating systems that do not support file modes. chmod is a convenience alias for this function.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.12 Accessing Compressed Files

Emacs automatically uncompresses compressed files when you visit them, and automatically recompresses them if you alter them and save them. Emacs recognizes compressed files by their file names. File names ending in ‘.gz’ indicate a file compressed with gzip. Other endings indicate other compression programs.

Automatic uncompression and compression apply to all the operations in which Emacs uses the contents of a file. This includes visiting it, saving it, inserting its contents into a buffer, loading it, and byte compiling it.

To disable this feature, type the command M-x auto-compression-mode. You can disable it permanently by customizing the variable auto-compression-mode.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.13 File Archives

A file whose name ends in ‘.tar’ is normally an archive made by the tar program. Emacs views these files in a special mode called Tar mode which provides a Dired-like list of the contents (@pxref{Dired}). You can move around through the list just as you would in Dired, and visit the subfiles contained in the archive. However, not all Dired commands are available in Tar mode.

If Auto Compression mode is enabled (see section Accessing Compressed Files), then Tar mode is used also for compressed archives—files with extensions ‘.tgz’, .tar.Z and .tar.gz.

The keys e, f and <RET> all extract a component file into its own buffer. You can edit it there, and if you save the buffer, the edited version will replace the version in the Tar buffer. Clicking with the mouse on the file name in the Tar buffer does likewise. v extracts a file into a buffer in View mode (@pxref{View Mode}). o extracts the file and displays it in another window, so you could edit the file and operate on the archive simultaneously.

The I key adds a new (regular) file to the archive. The file is initially empty, but can readily be edited using the commands above. The command inserts the new file before the current one, so that using it on the topmost line of the Tar buffer makes the new file the first one in the archive, and using it at the end of the buffer makes it the last one.

d marks a file for deletion when you later use x, and u unmarks a file, as in Dired. C copies a file from the archive to disk and R renames a file within the archive. g reverts the buffer from the archive on disk. The keys M, G, and O change the file’s permission bits, group, and owner, respectively.

Saving the Tar buffer writes a new version of the archive to disk with the changes you made to the components.

You don’t need the tar program to use Tar mode—Emacs reads the archives directly. However, accessing compressed archives requires the appropriate uncompression program.

A separate but similar Archive mode is used for arc, jar, lzh, zip, rar, 7z, and zoo archives, as well as exe files that are self-extracting executables.

The key bindings of Archive mode are similar to those in Tar mode, with the addition of the m key which marks a file for subsequent operations, and M-<DEL> which unmarks all the marked files. Also, the a key toggles the display of detailed file information, for those archive types where it won’t fit in a single line. Operations such as renaming a subfile, or changing its mode or owner, are supported only for some of the archive formats.

Unlike Tar mode, Archive mode runs the archiving programs to unpack and repack archives. However, you don’t need these programs to look at the archive table of contents, only to extract or manipulate the subfiles in the archive. Details of the program names and their options can be set in the ‘Archive’ Customize group (@pxref{Customization Groups}).

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.14 Remote Files

You can refer to files on other machines using a special file name syntax:


To carry out this request, Emacs uses a remote-login program such as ftp, ssh, rlogin, or telnet. You can always specify in the file name which method to use—for example, ‘/ftp:user@host:filename’ uses FTP, whereas ‘/ssh:user@host:filename’ uses ssh. When you don’t specify a method in the file name, Emacs chooses the method as follows:

  1. If the host name starts with ‘ftp.’ (with dot), Emacs uses FTP.
  2. If the user name is ‘ftp’ or ‘anonymous’, Emacs uses FTP.
  3. If the variable tramp-default-method is set to ‘ftp’, Emacs uses FTP.
  4. If ssh-agent is running, Emacs uses scp.
  5. Otherwise, Emacs uses ssh.

You can entirely turn off the remote file name feature by setting the variable tramp-mode to nil. You can turn off the feature in individual cases by quoting the file name with ‘/:’ (see section Quoted File Names).

Remote file access through FTP is handled by the Ange-FTP package, which is documented in the following. Remote file access through the other methods is handled by the Tramp package, which has its own manual. See The Tramp Manual in The Tramp Manual.

When the Ange-FTP package is used, Emacs logs in through FTP using the name user, if that is specified in the remote file name. If user is unspecified, Emacs logs in using your user name on the local system; but if you set the variable ange-ftp-default-user to a string, that string is used instead. When logging in, Emacs may also ask for a password.

For performance reasons, Emacs does not make backup files for files accessed via FTP by default. To make it do so, change the variable ange-ftp-make-backup-files to a non-nil value.

By default, auto-save files for remote files are made in the temporary file directory on the local machine, as specified by the variable auto-save-file-name-transforms. See section Auto-Save Files.

To visit files accessible by anonymous FTP, you use special user names ‘anonymous’ or ‘ftp’. Passwords for these user names are handled specially. The variable ange-ftp-generate-anonymous-password controls what happens: if the value of this variable is a string, then that string is used as the password; if non-nil (the default), then the value of user-mail-address is used; if nil, then Emacs prompts you for a password as usual (@pxref{Passwords}).

Sometimes you may be unable to access files on a remote machine because a firewall in between blocks the connection for security reasons. If you can log in on a gateway machine from which the target files are accessible, and whose FTP server supports gatewaying features, you can still use remote file names; all you have to do is specify the name of the gateway machine by setting the variable ange-ftp-gateway-host, and set ange-ftp-smart-gateway to t. Otherwise you may be able to make remote file names work, but the procedure is complex. You can read the instructions by typing M-x finder-commentary <RET> ange-ftp <RET>.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.15 Quoted File Names

You can quote an absolute file name to prevent special characters and syntax in it from having their special effects. The way to do this is to add ‘/:’ at the beginning.

For example, you can quote a local file name which appears remote, to prevent it from being treated as a remote file name. Thus, if you have a directory named ‘/foo:’ and a file named ‘bar’ in it, you can refer to that file in Emacs as ‘/:/foo:/bar’.

/:’ can also prevent ‘~’ from being treated as a special character for a user’s home directory. For example, ‘/:/tmp/~hack’ refers to a file whose name is ‘~hack’ in directory ‘/tmp’.

Quoting with ‘/:’ is also a way to enter in the minibuffer a file name that contains ‘$’. In order for this to work, the ‘/:’ must be at the beginning of the minibuffer contents. (You can also double each ‘$’; see File Names with $.)

You can also quote wildcard characters with ‘/:’, for visiting. For example, ‘/:/tmp/foo*bar’ visits the file ‘/tmp/foo*bar’.

Another method of getting the same result is to enter ‘/tmp/foo[*]bar’, which is a wildcard specification that matches only ‘/tmp/foo*bar’. However, in many cases there is no need to quote the wildcard characters because even unquoted they give the right result. For example, if the only file name in ‘/tmp’ that starts with ‘foo’ and ends with ‘bar’ is ‘foo*bar’, then specifying ‘/tmp/foo*bar’ will visit only ‘/tmp/foo*bar’.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.16 File Name Cache

You can use the file name cache to make it easy to locate a file by name, without having to remember exactly where it is located. When typing a file name in the minibuffer, C-<TAB> (file-cache-minibuffer-complete) completes it using the file name cache. If you repeat C-<TAB>, that cycles through the possible completions of what you had originally typed. (However, note that the C-<TAB> character cannot be typed on most text terminals.)

The file name cache does not fill up automatically. Instead, you load file names into the cache using these commands:

M-x file-cache-add-directory <RET> directory <RET>

Add each file name in directory to the file name cache.

M-x file-cache-add-directory-using-find <RET> directory <RET>

Add each file name in directory and all of its nested subdirectories to the file name cache.

M-x file-cache-add-directory-using-locate <RET> directory <RET>

Add each file name in directory and all of its nested subdirectories to the file name cache, using locate to find them all.

M-x file-cache-add-directory-list <RET> variable <RET>

Add each file name in each directory listed in variable to the file name cache. variable should be a Lisp variable whose value is a list of directory names, like load-path.

M-x file-cache-clear-cache <RET>

Clear the cache; that is, remove all file names from it.

The file name cache is not persistent: it is kept and maintained only for the duration of the Emacs session. You can view the contents of the cache with the file-cache-display command.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.17 Convenience Features for Finding Files

In this section, we introduce some convenient facilities for finding recently-opened files, reading file names from a buffer, and viewing image files.

If you enable Recentf mode, with M-x recentf-mode, the ‘File’ menu includes a submenu containing a list of recently opened files. M-x recentf-save-list saves the current recent-file-list to a file, and M-x recentf-edit-list edits it.

The M-x ffap command generalizes find-file with more powerful heuristic defaults (@pxref{FFAP}), often based on the text at point. Partial Completion mode offers other features extending find-file, which can be used with ffap. @xref{Completion Options}.

Visiting image files automatically selects Image mode. In this major mode, you can type C-c C-c (image-toggle-display) to toggle between displaying the file as an image in the Emacs buffer, and displaying its underlying text (or raw byte) representation. Displaying the file as an image works only if Emacs is compiled with support for displaying such images. If the displayed image is wider or taller than the frame, the usual point motion keys (C-f, C-p, and so forth) cause different parts of the image to be displayed. You can press n (image-next-file) and p (image-previous-file) to visit the next image file and the previous image file in the same directory, respectively.

If the image can be animated, the command <RET> (image-toggle-animation) starts or stops the animation. Animation plays once, unless the option image-animate-loop is non-nil. With f (image-next-frame) and b (image-previous-frame) you can step through the individual frames. Both commands accept a numeric prefix to step through several frames at once. You can go to a specific frame with F (image-goto-frame). Frames are indexed from 1. Typing a + (image-increase-speed) increases the speed of the animation, a - (image-decrease-speed) decreases it, and a r (image-reverse-speed) reverses it. The command a 0 (image-reset-speed) resets the speed to the original value.

If Emacs was compiled with support for the ImageMagick library, it can use ImageMagick to render a wide variety of images. The variable imagemagick-enabled-types lists the image types that Emacs may render using ImageMagick; each element in the list should be an internal ImageMagick name for an image type, as a symbol or an equivalent string (e.g., BMP for ‘.bmp’ images). To enable ImageMagick for all possible image types, change imagemagick-enabled-types to t. The variable imagemagick-types-inhibit lists the image types which should never be rendered using ImageMagick, regardless of the value of imagemagick-enabled-types (the default list includes types like C and HTML, which ImageMagick can render as an image but Emacs should not). To disable ImageMagick entirely, change imagemagick-types-inhibit to t.

The Image-Dired package can also be used to view images as thumbnails. @xref{Image-Dired}.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.18 Filesets

If you regularly edit a certain group of files, you can define them as a fileset. This lets you perform certain operations, such as visiting, query-replace, and shell commands on all the files at once. To make use of filesets, you must first add the expression (filesets-init) to your init file (@pxref{Init File}). This adds a ‘Filesets’ menu to the menu bar.

The simplest way to define a fileset is by adding files to it one at a time. To add a file to fileset name, visit the file and type M-x filesets-add-buffer <RET> name <RET>. If there is no fileset name, this creates a new one, which initially contains only the current file. The command M-x filesets-remove-buffer removes the current file from a fileset.

You can also edit the list of filesets directly, with M-x filesets-edit (or by choosing ‘Edit Filesets’ from the ‘Filesets’ menu). The editing is performed in a Customize buffer (@pxref{Easy Customization}). Normally, a fileset is a simple list of files, but you can also define a fileset as a regular expression matching file names. Some examples of these more complicated filesets are shown in the Customize buffer. Remember to select ‘Save for future sessions’ if you want to use the same filesets in future Emacs sessions.

You can use the command M-x filesets-open to visit all the files in a fileset, and M-x filesets-close to close them. Use M-x filesets-run-cmd to run a shell command on all the files in a fileset. These commands are also available from the ‘Filesets’ menu, where each existing fileset is represented by a submenu.

@xref{Version Control}, for a different concept of filesets: groups of files bundled together for version control operations. Filesets of that type are unnamed, and do not persist across Emacs sessions.

[Top] [Contents] [Index] [ ? ]



If your file system does not support symbolic links, a regular file is used.

[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on September 12, 2017 using texi2html.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ < ] Back Previous section in reading order 1.2.2
[ Up ] Up Up section 1.2
[ > ] Forward Next section in reading order 1.2.4
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:

This document was generated on September 12, 2017 using texi2html.