@findex cd
@findex pwd
- The command @kbd{M-x pwd} prints the current buffer's default
+ The command @kbd{M-x pwd} displays the current buffer's default
directory, and the command @kbd{M-x cd} sets it (to a value read using
the minibuffer). A buffer's default directory changes only when the
@code{cd} command is used. A file-visiting buffer's default directory
@cindex environment variables in file names
@cindex expansion of environment variables
+@cindex @code{$} in file names
+@anchor{File Names with $}
@samp{$} in a file name is used to substitute environment variables.
For example, if you have used the shell command @command{export
FOO=rms/hacks} to set up an environment variable named @env{FOO}, then
@section Visiting Files
@cindex visiting files
-@c WideCommands
@table @kbd
@item C-x C-f
Visit a file (@code{find-file}).
another copy. It selects the existing buffer containing that file.
However, before doing so, it checks that the file itself has not changed
since you visited or saved it last. If the file has changed, a warning
-message is printed. @xref{Interlocking,,Simultaneous Editing}.
+message is shown. @xref{Interlocking,,Simultaneous Editing}.
@cindex maximum buffer size exceeded, error message
Since Emacs reads the visited file in its entirety, files whose size
is larger than the maximum Emacs buffer size (@pxref{Buffers}) cannot be
-visited; if you try, Emacs will print an error message saying that the
+visited; if you try, Emacs will display an error message saying that the
maximum buffer size has been exceeded.
@cindex creating files
- What if you want to create a new file? Just visit it. Emacs prints
+ What if you want to create a new file? Just visit it. Emacs displays
@samp{(New file)} in the echo area, but in other respects behaves as if
you had visited an existing empty file. If you make any changes and
save them, the file is created.
If you already have visited the same file in the usual (non-literal)
manner, this command asks you whether to visit it literally instead.
-@vindex find-file-hooks
-@vindex find-file-not-found-hooks
+@vindex find-file-hook
+@vindex find-file-not-found-functions
Two special hook variables allow extensions to modify the operation of
visiting files. Visiting a file that does not exist runs the functions
-in the list @code{find-file-not-found-hooks}; this variable holds a list
+in the list @code{find-file-not-found-functions}; this variable holds a list
of functions, and the functions are called one by one (with no
arguments) until one of them returns non-@code{nil}. This is not a
-normal hook, and the name ends in @samp{-hooks} rather than @samp{-hook}
+normal hook, and the name ends in @samp{-functions} rather than @samp{-hook}
to indicate that fact.
Successful visiting of any file, whether existing or not, calls the
-functions in the list @code{find-file-hooks}, with no arguments.
-This variable is really a normal hook, but it has an abnormal name for
-historical compatibility. In the case of a nonexistent file, the
-@code{find-file-not-found-hooks} are run first. @xref{Hooks}.
+functions in the list @code{find-file-hook}, with no arguments.
+This variable is a normal hook. In the case of a nonexistent file, the
+@code{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
file was last visited or saved. If the date does not match, it implies
that changes were made in the file in some other way, and these changes are
about to be lost if Emacs actually does save. To prevent this, Emacs
-prints a warning message and asks for confirmation before saving.
+displays a warning message and asks for confirmation before saving.
Occasionally you will know why the file was changed and know that it does
not matter; then you can answer @kbd{yes} and proceed. Otherwise, you should
cancel the save with @kbd{C-g} and investigate the situation.
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
+regular expression that matches the host names of all the other hosts
in the cluster. You can define a shadow cluster with @kbd{M-x
shadow-define-cluster}.
@end example
Then add the hook function @code{time-stamp} to the hook
-@code{write-file-hooks}; that hook function will automatically update
+@code{write-file-functions}; 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
@file{foo.c} is auto-saved in a file @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
-@samp{#%} to the front and @samp{#} to the rear of buffer name. For
+@samp{#} to the front and rear of buffer name, then
+adding digits and letters at the end for uniqueness. For
example, the @samp{*mail*} buffer in which you compose messages to be
-sent is auto-saved in a file named @file{#%*mail*#}. Auto-save file
+sent might auto-saved in a file named @file{#*mail*#704juu}. Auto-save file
names are made this way unless you reprogram parts of Emacs to do
something different (the functions @code{make-auto-save-file-name} and
@code{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.
+@cindex auto-save for remote files
+@vindex auto-save-file-name-transforms
+The variable @code{auto-save-file-name-transforms} allows a
+degree of control over the auto-save file name. The default value is
+set up to put the auto-save files for remote files
+(@pxref{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
Emacs does auto-saving periodically based on counting how many characters
you have typed since the last time auto-saving was done. The variable
@code{auto-save-interval} specifies how many characters there are between
-auto-saves. By default, it is 300.
+auto-saves. By default, it is 300. Emacs doesn't accept values that are
+too small: if you customize @code{auto-save-interval} to a value less
+than 20, Emacs will behave as if the value is 20.
@vindex auto-save-timeout
Auto-saving also takes place when you stop typing for a while. The
@vindex auto-save-list-file-prefix
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 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.
+@file{~/.emacs.d/auto-save-list/.saves-@var{pid}-@var{hostname}}. All
+of this name except @file{@var{pid}-@var{hostname}} comes 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
two different buffers, but it warns you about the situation.
@vindex find-file-existing-other-name
+@vindex find-file-suppress-same-file-warnings
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.
+system that truncates long file names. You can suppress the message by
+setting the variable @code{find-file-suppress-same-file-warnings} to a
+non-@code{nil} value. You can disable this feature entirely 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
@menu
* Introduction to VC:: How version control works in general.
-* VC Mode Line:: How the mode line shows version control status.
+* VC Mode Line:: How the mode line shows version control status.
* Basic VC Editing:: How to edit a file under version control.
* Old Versions:: Examining and comparing old versions.
* Secondary VC Commands:: The commands used a little less frequently.
@menu
* Version Systems:: Supported version control back-end systems.
* VC Concepts:: Words and concepts related to version control.
+* Types of Log File:: The per-file VC log in contrast to the ChangeLog.
@end menu
@node Version Systems
check-in time. However, CVS can also be set up to require locking.
(@pxref{CVS Options}).
+@node Types of Log File
+@subsubsection Types of Log File
+@cindex types of log file
+@cindex log File, types of
+@cindex version control log
+
+GNU projects under a revision control system generally possess
+@emph{two} types of log for changes. One is the per-file log
+maintained by the revision control system: each time you check in a
+change, you must fill out a @dfn{log entry} for the change (@pxref{Log
+Buffer}). This kind of log is called the @dfn{version control log},
+also the @dfn{revision control log}, @dfn{RCS log}, or @dfn{CVS log}.
+
+The other kind of log is the change log file, typically a file called
+@file{ChangeLog}. It provides a chronological record of all changes
+to a large portion of a program---one directory and its
+subdirectories. A small program would use one @file{ChangeLog} file;
+a large program may well merit a @file{ChangeLog} file in each major
+directory. @xref{Change Log}.
+
+When you use version control, you can use just the per-file log if you
+wish, or you can use both kinds of logs. When you use both, you
+typically want to write just one entry for each change. You can write
+the entry in @file{ChangeLog}, then copy it to the log buffer when you
+check in the change. Or you can write the entry in the log buffer
+while checking in the change, and later use the @kbd{C-x v a} command
+to copy it to @file{ChangeLog} (@pxref{Change Logs and VC}).
+
@node VC Mode Line
@subsection Version Control and the Mode Line
@node Advanced C-x C-q
@subsubsection Advanced Control in @kbd{C-x C-q}
+@cindex version number to check in/out
When you give a prefix argument to @code{vc-next-action} (@kbd{C-u
C-x C-q}), it still performs the next logical version control
operation, but accepts additional arguments to specify precisely how
the repository.
@item
+@cindex specific version control system
Instead of the version number, you can also specify the name of a
version control system. This is useful when one file is being managed
with two version control systems at the same time (@pxref{Local
@kbd{C-x v =} works by running a variant of the @code{diff} utility
designed to work with the version control system in use. When you
invoke @code{diff} this way, in addition to the options specified by
-@code{diff-switches} (@pxref{Comparing files}), it receives those
+@code{diff-switches} (@pxref{Comparing Files}), it receives those
specified by @code{vc-diff-switches}, plus those specified for the
specific back end by @code{vc-@var{backend}-diff-switches}. For
instance, when the version control back end is RCS, @code{diff} uses
@kindex C-x v g
For CVS-controlled files, you can display the result of the CVS
annotate command, using colors to enhance the visual appearance. Use
-the command @kbd{M-x vc-annotate} to do this. Red means new, blue
-means old, and intermediate colors indicate intermediate ages. By
-default, the time scale is 360 days, so that everything more than one
-year old is shown in blue. Giving a prefix argument @var{n} to this
-command multiplies the time scale by @var{n}, so that all text over
-@var{n} years old is shown in blue.
+the command @kbd{M-x vc-annotate} to do this. It creates a new buffer
+to display file's text, colored to show how old each part is. Text
+colored red is new, blue means old, and intermediate colors indicate
+intermediate ages. By default, the time scale is 360 days, so that
+everything more than one year old is shown in blue.
+
+ When you give a prefix argument to this command, it uses the
+minibuffer to read two arguments: which version number to display and
+annotate (instead of the current file contents), and a stretch factor
+for the time scale. A stretch factor of 0.1 means that the color
+range from red to blue spans the past 36 days instead of 360 days. A
+stretch factor greater than 1 means the color range spans more than a
+year.
@node Secondary VC Commands
@subsection The Secondary Commands of VC
version by typing @kbd{C-x C-q}.
@vindex vc-default-init-version
+@cindex initial version number to register
The initial version number for a newly registered file is 1.1, by
default. You can specify a different default by setting the variable
@code{vc-default-init-version}, or you can give @kbd{C-x v i} a numeric
working area, then works by direct interactions with the CVS server.
One difficulty is that access to the CVS server is often slow, and
-that developers might need to work offline as well. VC is designed
+that developers might need to work off-line as well. VC is designed
to reduce the amount of network interaction necessary.
@menu
While using local RCS, you can pick up recent changes from the CVS
repository into your local file, or commit some of your changes back
to CVS, without terminating local RCS version control. To do this,
-switch to the CVS backend temporarily, with the @kbd{C-x v b} command:
+switch to the CVS back end temporarily, with the @kbd{C-x v b} command:
@table @kbd
@item C-x v b
users, but there is a mode called @dfn{non-strict locking} in which
you can check-in changes without locking the file first. Use
@samp{rcs -U} to switch to non-strict locking for a particular file,
-see the @code{rcs} manpage for details.
+see the @code{rcs} manual page for details.
When deducing the version control state of an RCS file, VC first
looks for an RCS version header string in the file (@pxref{Version
For one thing, you can set the @env{CVSREAD} environment variable
(the value you use makes no difference). If this variable is defined,
CVS makes your work files read-only by default. In Emacs, you must
-type @kbd{C-x C-q} to make the file writeable, so that editing works
+type @kbd{C-x C-q} to make the file writable, so that editing works
in fact similar as if locking was used. Note however, that no actual
-locking is performed, so several users can make their files writeable
+locking is performed, so several users can make their files writable
at the same time. When setting @env{CVSREAD} for the first time, make
sure to check out all your modules anew, so that the file protections
are set correctly.
Another way to achieve something similar to locking is to use the
@dfn{watch} feature of CVS. If a file is being watched, CVS makes it
read-only by default, and you must also use @kbd{C-x C-q} in Emacs to
-make it writable. VC calls @code{cvs edit} to make the file writeable,
+make it writable. VC calls @code{cvs edit} to make the file writable,
and CVS takes care to notify other developers of the fact that you
intend to change the file. See the CVS documentation for details on
using the watch feature.
repositories. It also does not make any version backups.
You can also set @code{vc-cvs-stay-local} to a regular expression
-that is matched against the repository hostname; VC then stays local
+that is matched against the repository host name; VC then stays local
only for repositories from hosts that match the pattern.
@node Directories
C-x C-d /u2/emacs/src/*.c @key{RET}
@end example
- Normally, @kbd{C-x C-d} prints a brief directory listing containing
+ Normally, @kbd{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
@samp{ls -l}).
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,
+ The key bindings 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 detailed file
@node Remote Files
@section Remote Files
+@cindex Tramp
+ In the following, file access via FTP will be discussed. In
+addition to that facility, it is also possible to access remote files
+through a shell connection. @xref{Top, The Tramp Manual,, tramp, The
+Tramp Manual}.
+
@cindex FTP
@cindex remote file access
You can refer to files on other machines using a special file name syntax:
is used for logging in on @var{host}. The form using @var{port} allows
you to access servers running on a non-default TCP port.
+For using Tramp, the file name syntax looks like this:
+
+@example
+@group
+/[@var{host}]@var{filename}
+/[@var{user}@@@var{host}]@var{filename}
+/[@var{method}/@var{user}@@@var{host}]@var{filename}
+@end group
+@end example
+
+@noindent
+Note that the square brackets are part of the file names.
+
@cindex backups for remote files
@vindex ange-ftp-make-backup-files
If you want to disable backups for remote files, set the variable
@code{ange-ftp-make-backup-files} to @code{nil}.
+ By default, the auto-save files (@pxref{Auto Save Files}) for remote
+files are made in the temporary file directory on the local machine.
+This is achieved using the variable @code{auto-save-file-name-transforms}.
+
@cindex ange-ftp
@vindex ange-ftp-default-user
@cindex user name for remote file access
character for a user's home directory. For example, @file{/:/tmp/~hack}
refers to a file whose name is @file{~hack} in directory @file{/tmp}.
- Likewise, quoting with @samp{/:} is one way to enter in the minibuffer
-a file name that contains @samp{$}. However, the @samp{/:} must be at
-the beginning of the minibuffer in order to quote @samp{$}.
+ Quoting with @samp{/:} is also a way to enter in the minibuffer a
+file name that contains @samp{$}. In order for this to work, the
+@samp{/:} must be at the beginning of the minibuffer contents. (You
+can also double each @samp{$}; see @ref{File Names with $}.)
You can also quote wildcard characters with @samp{/:}, for visiting.
-For example, @file{/:/tmp/foo*bar} visits the file @file{/tmp/foo*bar}.
-However, in most cases you can simply type the wildcard characters for
-themselves. For example, if the only file name in @file{/tmp} that
-starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar}, then
-specifying @file{/tmp/foo*bar} will visit just @file{/tmp/foo*bar}.
-Another way is to specify @file{/tmp/foo[*]bar}.
+For example, @file{/:/tmp/foo*bar} visits the file
+@file{/tmp/foo*bar}.
+
+ Another method of getting the same result is to enter
+@file{/tmp/foo[*]bar}, which is a wildcard specification that matches
+only @file{/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 @file{/tmp} that
+starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar},
+then specifying @file{/tmp/foo*bar} will visit only
+@file{/tmp/foo*bar}.
@node File Name Cache
@section File Name Cache