# HG changeset patch # User Richard M. Stallman # Date 982357726 0 # Node ID a5ae50ec6fe781d28d9cd7a786ee8e886267f2e8 # Parent 0bfa71b66dd35bf6898f6542ad459dfccf865d56 Many small clarifications. New node File Name Cache, broken out of the File Convenience node. Use @command. Eliminate invalid @vindex. Delete duplicate index entries. Delete vc-ignore-vc-files and vc-handle-cvs. Add vc-handled-backends. Clarify Auto Compression mode, Tar mode, Diff mode, Smerge mode, and Archive mode. Rewrite Shadow File node. Rewrite Timestamp text. diff -r 0bfa71b66dd3 -r a5ae50ec6fe7 man/files.texi --- a/man/files.texi Fri Feb 16 15:55:20 2001 +0000 +++ b/man/files.texi Fri Feb 16 21:08:46 2001 +0000 @@ -34,6 +34,7 @@ * File Archives:: Operating on tar, zip, jar etc. archive files. * Remote Files:: Accessing files on other sites. * Quoted File Names:: Quoting special characters in file names. +* File Name Cache:: Completion against a list of files you often use. * File Conveniences:: Convenience Features for Finding Files. @end menu @@ -97,7 +98,7 @@ @xref{Minibuffer File}. @samp{$} in a file name is used to substitute environment variables. -For example, if you have used the shell command @samp{export +For example, if you have used the shell command @command{export FOO=rms/hacks} to set up an environment variable named @env{FOO}, then you can use @file{/u/$FOO/test.c} or @file{/u/$@{FOO@}/test.c} as an abbreviation for @file{/u/rms/hacks/test.c}. The environment variable @@ -230,11 +231,11 @@ @cindex wildcard characters in file names @vindex find-file-wildcards - If the file name you specify contains @code{sh}-style wildcard -characters, Emacs visits all the files that match it. @xref{Quoted File -Names}, if you want to visit a file whose name actually contains -wildcard characters. Wildcards comprise @samp{?}, @samp{*} and -@samp{[@dots{}]} sequences. The wildcard feature can be disabled by + If the file name you specify contains shell-style wildcard +characters, Emacs visits all the files that match it. Wildcards +comprise @samp{?}, @samp{*} and @samp{[@dots{}]} sequences. +@xref{Quoted File Names}, for how to visit a file whose name actually +contains wildcard characters. You can disable the wildcard feature by customizing @code{find-file-wildcards}. If you visit a file that the operating system won't let you modify, @@ -281,8 +282,7 @@ system. @xref{Frames}. @findex find-file-literally -@vindex require-final-newline@r{, and }find-file-literally - If you wish to edit a file as a sequence of characters with no special + If you wish to edit a file as a sequence of ASCII characters with no special encoding or conversion, use the @kbd{M-x find-file-literally} command. It visits a file, like @kbd{C-x C-f}, but does not do format conversion (@pxref{Formatted Text}), character code conversion (@pxref{Coding @@ -440,7 +440,8 @@ * Backup:: How Emacs saves the old version of your file. * Interlocking:: How Emacs protects against simultaneous editing of one file by two users. -* Shadowing: File Shadowing. Copying files to `shadows' automatically. +* Shadowing: File Shadowing. + Copying files to `shadows' automatically. * Time Stamps:: Emacs can update time stamps on saved files. @end menu @@ -449,7 +450,6 @@ @cindex backup file @vindex make-backup-files @vindex vc-make-backup-files -@vindex backup-enable-predicate On most operating systems, rewriting a file automatically destroys all record of what the file used to contain. Thus, saving a file from Emacs @@ -471,8 +471,9 @@ @vindex temporary-file-directory @vindex small-temporary-file-directory The default value of the @code{backup-enable-predicate} variable -prevents backup files being written for files in the directories named -by @code{temporary-file-directory} or @code{small-temporary-file-directory}. +prevents backup files being written for files in the directories used +for temporary files, specified by @code{temporary-file-directory} or +@code{small-temporary-file-directory}. At your option, Emacs can keep either a single backup file or a series of numbered backup files for each file that you edit. @@ -513,28 +514,29 @@ You can change this behaviour by defining the variable @code{make-backup-file-name-function} to a suitable function. Alternatively you can customize the variable -@code{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 @code{("." . @var{dir})} to make all backups in the -directory with absolute name @var{dir}; the names will be mangled to -prevent clashes between files with the same names originating in -different directories. Alternatively, adding, say, @code{("." ".~")} -would make backups in the invisible sub-directory @file{.~} of the -original file's directory. The directories are created if necessary -when the backup is made. +@var{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 @code{("." . @var{dir})} to make +all backups in the directory with absolute name @var{dir}; Emacs +modifies the backup file names to avoid clashes between files with the +same names originating in different directories. Alternatively, +adding, say, @code{("." ".~")} would make backups in the invisible +subdirectory @file{.~} of the original file's directory. Emacs +creates the directory, if necessary, to make the backup. + + If access control stops Emacs from writing backup files under the usual +names, it writes the backup file as @file{%backup%~} in your home +directory. Only one such file can exist, so only the most recently +made such backup is available. If you choose to have a series of numbered backup files, backup file -names are made by appending @samp{.~}, the number, and another @samp{~} -to the original file name. Thus, the backup files of @file{eval.c} -would be called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, through -names like @file{eval.c.~259~} and beyond. As for single backups, -@code{backup-directory-alist} can be used to control the location of -numbered backups. - - If protection stops you from writing backup files under the usual names, -the backup file is written as @file{%backup%~} in your home directory. -Only one such file can exist, so only the most recently made such backup is -available. +names contain @samp{.~}, the number, and another @samp{~} after the +original file name. Thus, the backup files of @file{eval.c} would be +called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, all the way +through names like @file{eval.c.~259~} and beyond. The variable +@code{backup-directory-alist} applies to numbered backups just as +usual. @vindex version-control The choice of single backup or numbered backups is controlled by the @@ -620,7 +622,7 @@ @vindex backup-by-copying-when-mismatch @vindex backup-by-copying-when-privileged-mismatch @cindex file ownership, and backup -@cindex backup, and user's uid +@cindex backup, and user-id The choice of renaming or copying is controlled by four variables. Renaming is the default choice. If the variable @code{backup-by-copying} is non-@code{nil}, copying is used. Otherwise, @@ -632,8 +634,8 @@ change. @code{backup-by-copying-when-mismatch} is @code{t} by default if you start Emacs as the superuser. The fourth variable, @code{backup-by-copying-when-privileged-mismatch}, gives the highest -numeric user id for which @code{backup-by-copying-when-mismatch} will be -forced on. This is useful when low-numbered uid's are assigned to +numeric user-id for which @code{backup-by-copying-when-mismatch} will be +forced on. This is useful when low-numbered user-id are assigned to special system users, such as @code{root}, @code{bin}, @code{daemon}, etc., which must maintain ownership of files. @@ -732,43 +734,44 @@ @table @kbd @item M-x shadow-initialize Set up file shadowing. +@item M-x shadow-define-literal-group +Declare a single file to be shared between sites. +@item M-x shadow-define-regexp-group +Make all files that match each of a group of files be shared between hosts. @item M-x shadow-define-cluster @key{RET} @var{name} @key{RET} Define a shadow file cluster @var{name}. -@item M-x shadow-define-regexp-group -Make each of a group of files be shared between hosts. -@item M-x shadow-define-literal-group -Declare a single file to be shared between sites. @item M-x shadow-copy-files Copy all pending shadow files. -@item M-x shadow-cancel () -Cancel the instruction to copy some files. +@item M-x shadow-cancel +Cancel the instruction to shadow some files. @end table -You can arrange to keep identical copies of files in more than one -place---possibly on different machines. When you save a file, Emacs can -check whether it is on the list of files with @dfn{shadows}, and if so, -it tries to copy it when you exit Emacs (or use the @kbd{M-x -shadow-copy-files} command). - -A @dfn{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. Clusters are defined by a name, the network address of a -primary host (the one we copy files to), and a regular expression that -matches the hostnames of all the sites in the cluster. A @dfn{file -group} is a set of identically-named files shared between a list of -sites. - -Add clusters (if necessary) and file groups with @kbd{M-x -shadow-define-cluster}, @kbd{M-x shadow-define-literal-group}, and -@kbd{M-x shadow-define-regexp-group} (see the documentation for these -functions for information on how and when to use them). After doing -this once, everything should be automatic. The lists of clusters and -shadows are remembered from one emacs session to another. - -If you do not want to copy a particular file, you can answer "no" and be -asked again next time you hit @kbd{C-x 4 s} or exit Emacs. If you do -not want to be asked again, use @kbd{M-x shadow-cancel}, and you will -not be asked until you change the file and save it again. +You can arrange to keep identical @dfn{shadow} copies of certain files +in more than one place---possibly on different machines. To do this, +first you must set up a @dfn{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 @kbd{M-x +shadow-copy-files}. + +To set up a file group, use @kbd{M-x shadow-define-literal-group} or +@kbd{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 +@kbd{M-x shadow-cancel} to eliminate or change the shadow file group. + +A @dfn{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 hostnames of all the other hosts +in the cluster. You can define a shadow cluster with @kbd{M-x +shadow-define-cluster}. @node Time Stamps @subsection Updating Time Stamps Automatically @@ -777,27 +780,29 @@ @cindex modification dates @cindex locale, date format -You can arrange to have time stamp text in a file updated -automatically to reflect the modification time when you save the -file. To do this, include in the first eight lines a template like +You can arrange put a time stamp in a file, so that it will be updated +automatically each time you edit and save the file. The time stamp +has to be in the first eight lines of the file, and you should +insert it like this: + @example Time-stamp: <> @end example + @noindent -or +or like this: + @example Time-stamp: "" @end example -@noindent -and customize the value of the hook @code{write-file-hooks} to add -@code{time-stamp}. Such a template is updated with the current time -and date when the file is written. You can also use the command -@kbd{M-x time-stamp} to update the time stamp manually. - -You can customize the form of the template and the time string used -along with other parameters in the Custom group @code{time-stamp}. -Note that non-numeric fields in the time stamp are printed according -to your locale setting. + + Then add the hook function @code{time-stamp} to the hook +@code{write-file-hooks}; that hook function will automatically update +the time stamp, inserting the current date and time when you save the +file. You can also use the command @kbd{M-x time-stamp} to update the +time stamp manually. For other customizations, see the Custom group +@code{time-stamp}. Note that non-numeric fields in the time stamp are +formatted according to your locale setting (@pxref{Environment}). @node Reverting @section Reverting a Buffer @@ -986,14 +991,13 @@ this---saving them---updates the files themselves. @vindex auto-save-list-file-prefix - Interrupted sessions are recorded for later recovery in files named + Emacs records interrupted sessions for later recovery in files named @file{~/.emacs.d/auto-save-list/.saves-@var{pid}-@var{hostname}}. The @samp{~/.emacs.d/auto-save-list/.saves-} portion of these names comes -from the value of @code{auto-save-list-file-prefix}. You can arrange -to record sessions in a different place by setting that variable in -your @file{.emacs} file. If you set @code{auto-save-list-file-prefix} -to @code{nil} in your @file{.emacs} file, sessions are not recorded -for recovery. +from the value of @code{auto-save-list-file-prefix}. You can record +sessions in a different place by customizing that variable. If you +set @code{auto-save-list-file-prefix} to @code{nil} in your +@file{.emacs} file, sessions are not recorded for recovery. @node File Aliases @section File Name Aliases @@ -1011,18 +1015,14 @@ two different buffers, but it warns you about the situation. @vindex find-file-existing-other-name - Normally, if you visit a file which Emacs is already visiting under a -different name, Emacs prints a message in the echo area and uses an -existing buffer, where that file is visited under another name. This -can happen on systems that support symbolic links, or if you use a long -file name on a system which truncates long file names. - - If Emacs should use different buffers when visiting the same file -under different names, set the variable -@code{find-file-existing-other-name} to @code{nil}. A non-@code{nil} -value, which is the default, means @code{find-file} uses the existing -buffer visiting the file, no matter which of the file's names you -specify. + 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 symbolic links, or if you use a long file name on a +system that truncates long file names. You can disable this feature +by setting the variable @code{find-file-existing-other-name} to +@code{nil}. Then if you visit the same file under two different names, +you get a separate buffer for each file name. @vindex find-file-visit-truename @cindex truenames of files @@ -1044,12 +1044,11 @@ description of what was changed in that version. The Emacs version control interface is called VC. Its commands work -with three version control systems---RCS, CVS and SCCS. The GNU project -recommends RCS and CVS, which are free software and available from the -Free Software Foundation. -@cindex CSSC -There is a GNU clone of SCCS called CSSC, but RCS is technically -superior. +with three version control systems---RCS, CVS and SCCS. The GNU +project recommends RCS and CVS, which are free software and available +from the Free Software Foundation. We also have free software to +replace SCCS, known as CSSC; if you are using SCCS and don't want to +make the incompatible change to RCS or CVS, you can switch to CSSC. @menu * Introduction to VC:: How version control works in general. @@ -1504,10 +1503,10 @@ @cindex PCL-CVS @pindex cvs @cindex CVS Dired Mode -The VC Dired Mode described here works with all the VC-supported version -control systems. There is a similar facility specialized for use with -CVS, called PCL-CVS. @xref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The -Emacs Front-End to CVS}. + The VC Dired Mode described here works with all the version control +systems that VC supports. Another more powerful facility, designed +specifically for CVS, is called PCL-CVS. @xref{Top, , About PCL-CVS, +pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}. @kindex C-x v d @findex vc-directory @@ -2153,16 +2152,6 @@ There are many ways of customizing VC. The options you can set fall into four categories, described in the following sections. -@vindex vc-ignore-vc-files -@cindex Version control, deactivating - In addition, it is possible to turn VC on and off generally by setting -the variable @code{vc-ignore-vc-files}. Normally VC will notice the -presence of version control on a file you visit and automatically invoke -the relevant program to check the file's state. Change -@code{vc-ignore-vc-files} if this isn't the right thing, for instance, -if you edit files under version control but don't have the relevant -version control programs available. - @menu * Backend Options:: Customizing the back-end to your needs. * VC Workfile Handling:: Various options concerning working files. @@ -2174,6 +2163,13 @@ @node Backend Options @subsubsection Options for VC Backends +@vindex vc-handled-backends + By default, VC detects automatically which files are managed by RCS, +which by CVS, and which by SCCS, and it tries to do the right thing in +all three cases. If you want VC to ignore one or more of these +backends, set @code{vc-handled-backends} to the list of backends that +@emph{should} be handled. + @cindex backend options (VC) @cindex locking under version control You can tell RCS and CVS whether to use locking for a file or not @@ -2212,12 +2208,6 @@ intend to change the file. See the CVS documentation for details on using the watch feature. -@vindex vc-handle-cvs - You can turn off use of VC for CVS-managed files by setting the -variable @code{vc-handle-cvs} to @code{nil}. If you do this, Emacs -treats these files as if they were not registered, and the VC commands -are not available for them. You must do all CVS operations manually. - @node VC Workfile Handling @subsubsection VC Workfile Handling @@ -2405,24 +2395,26 @@ @cindex diffs @cindex patches @cindex Diff mode -Differences between versions of files are often distributed as -@dfn{patches} output by @command{diff} or a version control system. -@kbd{M-x diff-mode} turns on Diff mode, a major mode for viewing and -editing patches, either as `unified diffs' or `context diffs'. - - See also @ref{Emerge} and @ref{Top,,, ediff, The Ediff Manual}, for -convenient facilities for merging two similar files. + Differences between versions of files are often distributed as +@dfn{patches}, which are the output from @command{diff} or a version +control system that uses @command{diff}. @kbd{M-x diff-mode} turns on +Diff mode, a major mode for viewing and editing patches, either as +``unified diffs'' or ``context diffs.'' @cindex Smerge mode @findex smerge-mode @cindex failed merges @cindex merges, failed @pindex diff3 -Use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor mode for -editing output from the @command{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. + You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor +mode for editing output from the @command{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. + + See also @ref{Emerge}, and @ref{Top,,, ediff, The Ediff Manual}, for +convenient facilities for merging two similar files. @node Misc File Ops @section Miscellaneous File Operations @@ -2530,11 +2522,16 @@ @cindex Tar mode @pindex tar - If you visit a file with extension @samp{.tar}, it is assumed to be an -@dfn{archive} made by the @code{tar} program and it is viewed in a Tar -mode buffer. This provides a Dired-like listing of the contents. -@xref{Dired}. You can move around the component files as in Dired to -visit and manipulate them. + A file whose name ends in @samp{.tar} is normally an @dfn{archive} +made by the @code{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 you enable Auto Compression mode (@pxref{Compressed Files}), then +Tar mode is used also for compressed archives---files with extensions +@samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}. The keys @kbd{e}, @kbd{f} and @kbd{RET} all extract a component file into its own buffer. You can edit it there and when you save the buffer @@ -2557,17 +2554,9 @@ Saving the Tar buffer writes a new version of the archive to disk with the changes you made to the components. - If you enable Auto Compression mode (@pxref{Compressed Files}), then -Tar mode will be used also for compressed archives in files with -extensions @samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}. - - It is not necessary to have the @code{tar} program available to use -Tar mode or Archive mode---Emacs reads the archives directly. For -compressed archives such as @code{.tar.gz}, you need the appropriate -uncompress program to be available to Emacs. - -It is not necessary to have the @code{tar} program available to use Tar -mode or Archive mode---Emacs reads the archives directly. + You don't need the @code{tar} program to use Tar mode---Emacs reads +the archives directly. However, accessing compressed archives +requires the appropriate uncompression program. @cindex Archive mode @cindex mode, archive @@ -2584,24 +2573,22 @@ @cindex Java class archives @cindex unzip archives A separate but similar Archive mode is used for archives produced by -the programs @code{arc}, @code{zip}, @code{lzh} and @code{zoo} which -have extensions corresponding to the program names. These archiving -programs are typically used on MS-DOS and MS-Windows systems. Java -class archives with extension @samp{.jar} are also recognized. - - The keybindings in Archive mode are similar to those in Tar mode, with -the addition of the @kbd{m} key which marks a file for subsequent +the programs @code{arc}, @code{jar}, @code{lzh}, @code{zip}, and +@code{zoo}, which have extensions corresponding to the program names. + + The keybindings of Archive mode are similar to those in Tar mode, +with the addition of the @kbd{m} key which marks a file for subsequent operations, and @kbd{M-@key{DEL}} which unmarks all the marked files. -Also, the @kbd{a} key toggles the display of file information in those -archive types where all of of the info is too long to be displayed on a -single line. Operations such as @samp{change mode}, @samp{change owner} -and @samp{rename} are supported only for some of the archive formats. - - Unlike Tar mode, Archive mode runs the appropriate program to unpack -and repack archives. Details of the program names and their options can -be set in the @samp{Archive} Customize group. However, you don't need -these programs to @emph{view} the archive contents, only to extract and -delete archived files. +Also, the @kbd{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 program to unpack +and repack archives. Details of the program names and their options +can be set in the @samp{Archive} Customize group. However, you don't +need these programs to the archive table of contents, only to extract +or manipulate the subfiles in the archive. @node Remote Files @section Remote Files @@ -2655,26 +2642,19 @@ @vindex ange-ftp-smart-gateway @vindex ange-ftp-gateway-host Sometimes you may be unable to access files on a remote machine -because some machine in between (usually called a @dfn{firewall}) -blocks the connection for security reasons. However, you might have -account on another machine, called a @dfn{gateway}, from which the -target files @strong{are} accessible. Instead of logging into the -gateway, downloading the files, then copying them to your local -machine, you can set the variable @code{ange-ftp-smart-gateway} to a -non-@code{nil} value, and Emacs will use advanced FTP features to -access the remote machine. If this doesn't work, try setting the -variable @code{ange-ftp-gateway-host} to the name of the gateway -machine (which is the name you use to log into the gateway). Then -Emacs will try to run the FTP process on the gateway for you. If that -doesn't work either (because the FTP program on your machine doesn't -support some of the required features), read the instructions in the -@file{ange-ftp.el} file about working with gateways. You can read -these instructions by typing @kbd{M-x finder-commentary @key{RET} -ange-ftp @key{RET}}. Those instructions include various additional -tips for using @code{ange-ftp}. +because a @dfn{firewall} in between blocks the connection for security +reasons. If you can log in on a @dfn{gateway} machine from which the +target files @emph{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 @code{ange-ftp-gateway-host}, and set +@code{ange-ftp-smart-gateway} to @code{t}. Otherwise you may be able +to make remote file names work, but the procedure is complex. You can +read the instructions by typing @kbd{M-x finder-commentary @key{RET} +ange-ftp @key{RET}}. @vindex file-name-handler-alist -@cindex disabling ange-ftp +@cindex disabling remote files You can entirely turn off the FTP file name feature by removing the entries @var{ange-ftp-completion-hook-function} and @var{ange-ftp-hook-function} from the variable @@ -2712,78 +2692,57 @@ specifying @file{/tmp/foo*bar} will visit just @file{/tmp/foo*bar}. Another way is to specify @file{/tmp/foo[*]bar}. -@node File Conveniences -@section Convenience Features for Finding Files - -@table @kbd -@item M-x ff-find-other-file -Find the header or source file corresponding to the current buffer's -file. -@item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET} -Add @var{directory} to the file cache. -@item M-x locate @key{RET} @var{pattern} @key{RET} -Run the program @command{locate} to match @var{pattern} in the database, -putting results in a buffer. -@item M-x locate-with-filter @key{RET} @var{pattern} @key{RET} @var{filter} @key{RET} -Like @code{locate}, but use a @var{filter} on the results. -@item M-x auto-image-file-mode -Toggle visiting of image files as images. -@end table - -@findex ff-find-other-file -@vindex ff-other-file-alist -The command @kbd{ff-find-other-file} finds a file related to the one -visited by the current buffer, based on customizable patterns. -Typically this will be the header file corresponding to a C/C++ source -file, or vice versa. The patterns describing the corresponding files -are customizable via @code{ff-other-file-alist}. - -@cindex filename caching +@node File Name Cache +@section File Name Cache + +@cindex file name caching @cindex cache of file names @pindex find -@pindex locate -@vindex file-cache-delete-regexps +@kindex C-@key{TAB} +@findex file-cache-minibuffer-complete + You can use the @dfn{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, @kbd{C-@key{tab}} +(@code{file-cache-minibuffer-complete}) completes it using the file +name cache. If you repeat @kbd{C-@key{tab}}, that cycles through the +possible completions of what you had originally typed. Note that the +@kbd{C-@key{tab}} character cannot be typed on most text-only +terminals. + + The file name cache does not fill up automatically. Instead, you +load file names into the cache using these commands: + @findex file-cache-add-directory -You can use a cache to make it easy to locate files by name without -having to remember exactly where they are. When typing a filename in -the minibuffer you can @kbd{C-tab} will complete it using the filename -cache and cycle through possible completions. (The @kbd{C-tab} key -can't be distinguished from @kbd{TAB} on all terminals.) The command -@kbd{M-x file-cache-add-directory} adds the files in a directory to the -cache and @kbd{M-x file-cache-add-directory-list} acts on a list of -directories like @code{load-path} or @code{exec-path}. @kbd{M-x -file-cache-add-directory-using-find} uses the @command{find} program to -add a directory tree to the cache and @kbd{M-x -file-cache-add-directory-using-locate} uses the @command{locate} program -to add files matching a pattern. Use @kbd{M-x file-cache-clear-cache} -to remove all items from the cache; @kbd{M-x file-cache-delete-regexps} -and similar functions remove items from it selectively. - -@pindex locate -@findex locate -@findex locate-with-filter -@cindex file database (locate) -@vindex locate-command -@kbd{M-x locate} runs an interface to the @code{locate} program for -searching a pre-built database of file names; most Dired commands are -avilable for use on the result. @xref{, ,Find , find, GNU Findutils}. -@kbd{M-x locate-with-filter} is similar, but keeps only lines matching a -regular expression. Customize the option @code{locate-command} to use -another program than the default, GNU @code{locate}. - -The @kbd{M-x ffap} command generalizes @kbd{M-x find-file}. @xref{FFAP}. -Partial Completion mode offers other features extending @kbd{M-x -find-file} which can be used with @code{ffap}. @xref{Completion -Options}. +@table @kbd +@item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET} +Add each file name in @var{directory} to the file name cache. +@item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET} +Add each file name in @var{directory} and all of its nested +subdirectories to the file name cache. +@item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET} +Add each file name in @var{directory} and all of its nested +subdirectories to the file name cache, using @command{locate} to find +them all. +@item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET} +Add each file name in each directory listed in @var{variable} +to the file name cache. @var{variable} should be a Lisp variable +such as @code{load-path} or @code{exec-path}, whose value is a list +of directory names. +@item M-x file-cache-clear-cache @key{RET} +Clear the cache; that is, remove all file names from it. +@end table + +@node File Conveniences +@section Convenience Features for Finding Files @findex recentf-mode @vindex recentf-mode @findex recentf-save-list @findex recentf-edit-list -The command @kbd{M-x recentf-mode} or the Customize option of the same -name adds to the Files menu a submenu containing a list of recently -opened files. @kbd{recentf-save-list} saves the current file list to a -file and @kbd{recentf-edit-list} edits it. + If you enable Recentf mode, with @kbd{M-x recentf-mode}, the +@samp{Files} menu includes a submenu containing a list of recently +opened files. @kbd{M-x recentf-save-list} saves the current +recent-file-list to a file, and @kbd{M-x recentf-edit-list} edits it. @findex auto-image-file-mode @findex mode, auto-image-file @@ -2791,11 +2750,15 @@ @cindex visiting image files @vindex image-file-name-regexps @vindex image-file-name-extensions -When Auto-image-file minor mode is enabled, image files are displayed as -images when they are visited or inserted into buffers if Emacs can -display the relevant image type. File names matching -@code{image-file-name-extensions} or @code{image-file-name-regexps} are -considered to contain images. Note that Emacs can only display images -of the types for which the appropriate support libraries were linked -into Emacs when it was built. In particular, the MS-Windows version -of Emacs doesn't support image files as of version 21.1. + When Auto-image-file minor mode is enabled, visiting an image file +displays it as an image, not as text. Likewise, inserting an image +file into a buffer inserts it as an image. This works only when Emacs +can display the relevant image type. The variables +@code{image-file-name-extensions} or @code{image-file-name-regexps} +control which file names are recognized as containing images. + + The @kbd{M-x ffap} command generalizes @code{find-file} with more +powerful heuristic defaults (@pxref{FFAP}), often based on the text at +point. Partial Completion mode offers other features extending +@code{find-file}, which can be used with @code{ffap}. +@xref{Completion Options}.