15. Recent File Navigation

To install `recent-files', put the following statements into your initialization file

  (recent-files-initialize)

`recent-files' adds the menu "Recent Files" (or whatever name you choose, (see section Customization) to Emacs's menubar. Its entries are the files (and directories) that have recently been opened by Emacs. You can open one of these files again by selecting its entry in the "Recent Files" menu. The list of file entries in this menu is preserved from one Emacs session to another. You can prevent Emacs from saving this list by selecting "Don't save recent-files list on exit" from the menu. If you have disabled saving, you can re-enable it by selecting "Save recent-files list on exit".

The menu has permanent and non-permanent entries. Permanent entries are marked with an asterisk in front of the filename. The non-permanent entries are hidden in a submenu.

Each time you open a file in Emacs, it is added as a non-permanent entry to the menu. The value of recent-files-number-of-entries determines how many non-permanent entries are held in the menu. When the number of non-permanent entries reaches this value, the least recently added non-permanent entry is removed from the menu when another non-permanent entry is added. It is not removed from the list, though; it may reappear when entries are deleted from the list. The number of entries saved to disk is the value of the variable recent-files-number-of-saved-entries.

Permanent entries are not removed from the menu. You can make a file entry permanent by selecting "Make <buffer> permanent" (where <buffer> is the name of the current buffer) when the current buffer holds this file. "Make <buffer> non-permanent" makes the file entry of the current buffer non-permanent.

The command "Kill buffer <buffer> and delete entry" is handy when you have accidentally opened a file but want to keep neither the buffer nor the entry.

You can erase the list of non-permanent entries by selecting "Erase non-permanent entries" from the menu.

15.1 Customization

There are lots of variables to control the behaviour of recent-files. You do not have to change any of them if you like it as it comes out of the box. However, you may want to look at these options to make it behave different.

recent-files-number-of-entries

Controls how many non-permanent entries are shown in the recent-files list. The default is 15.

recent-files-number-of-saved-entries

Controls how many non-permanent entries are saved to disk when Emacs exits or recent-files-save-the-list is called. The default is 50.

recent-files-save-file

The name of the file where the recent-files list is saved between Emacs session. You probably don't need to change this. The default is ".recent-files.el" in your home directory.

recent-files-dont-include

A list of regular expressions for files that should not be included into the recent-files list. This list is empty by default. For instance, a list to exclude all .newsrc files, all auto-save-files, and all files in the /tmp directory (but not the /tmp directory itself) would look like this:

(setq recent-files-dont-include '("/\\.newsrc" "~$" "^/tmp/."))

The default is empty.

recent-files-use-full-names

If the value of this variable is non-nil, the full pathnames of the files are shown in the recent-files menu. Otherwise only the filename part (or the last name component if it is a directory) is shown in the menu. The default it t, i.e. show full names.

recent-files-filename-replacements

This is a list of pairs of regular expressions and replacement strings. If a filename matches one of the regular expressions, the matching part is replaced by the replacement string for display in the recent-files menu. Example: My home directory is "/users/mmc/nickel/". I want to replace it with "~/". I also want to replace the directory "/imports/teleservices/mmc/avc2/", where I work a lot, with ".../avc2/". The list then looks like

(setq recent-files-filename-replacements '(("/users/mmc/nickel/" . "~/") ("/imports/teleservices/mmc/avc2/" . ".../avc2/")))

Only the first match is replaced. So, if you have several entries in this list that may match a filename simultaneously, put the one you want to match (usually the most special) in front of the others. The default is to replace the home directory with "~".

recent-files-sort-function

Contains a function symbol to sort the display of filenames in the recent-files menu. Supplied are two functions, recent-files-dont-sort and recent-files-sort-alphabetically. The first, which is the default, preserves the order of "most recent on top".

recent-files-permanent-submenu

If this variable is non-nil, the permanent entries are put into a separate submenu of the recent-files menu. The default is nil.

recent-files-non-permanent-submenu

If this variable is non-nil, the non-permanent entries are put into a separate submenu of the recent-files menu. The default is currently t, but probably should be nil, and we may change it back. (You can set both recent-files-permanent-submenu and recent-files-non-permanent-submenu to t to have both lists in separate submenus.)

recent-files-commands-submenu

If this variable is non-nil, the commands if recent-files are placed in a submenu of the recent-files menu. The default is nil.

recent-files-commands-submenu-title

If the commands are placed in a submenu, this string is used as the title of the submenu. The default is "Commands...".

recent-files-actions-on-top

If this variable is non-nil, the "action" menu entries ("Make <buffer> permanent" etc.) are put on top of the menu. Otherwise they appear below the file entries or submenus. The default is nil.

recent-files-permanent-first

If this variable is t, the permanent entries are put first in the recent-files menu, i.e. above the non-permanent entries. If the value is nil, non-permanent entries appear first. If the value is neither t nor nil, the entries are sorted according to recent-files-sort-function. The default is 'sort.

recent-files-find-file-command

This variable contains the command to execute when a file entry is selected from the menu. Usually this will be find-file, which is the default.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.