[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] Changes to files.texi
|
From: |
Glenn Morris |
|
Subject: |
[Emacs-diffs] Changes to files.texi |
|
Date: |
Thu, 06 Sep 2007 04:36:21 +0000 |
CVSROOT: /sources/emacs
Module name: emacs
Changes by: Glenn Morris <gm> 07/09/06 04:36:21
Index: files.texi
===================================================================
RCS file: files.texi
diff -N files.texi
--- files.texi 7 Aug 2007 16:48:19 -0000 1.165
+++ /dev/null 1 Jan 1970 00:00:00 -0000
@@ -1,2950 +0,0 @@
address@hidden This is part of the Emacs manual.
address@hidden Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999,
2000,
address@hidden 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software
Foundation, Inc.
address@hidden See file emacs.texi for copying conditions.
address@hidden Files, Buffers, Keyboard Macros, Top
address@hidden File Handling
address@hidden files
-
- The operating system stores data permanently in named @dfn{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
address@hidden 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 @dfn{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.
-
address@hidden
-* File Names:: How to type and edit file-name arguments.
-* Visiting:: Visiting a file prepares Emacs to edit the file.
-* Saving:: Saving makes your changes permanent.
-* Reverting:: Reverting cancels all the changes not saved.
address@hidden
-* Autorevert:: Auto Reverting non-file buffers.
address@hidden ifnottex
-* Auto Save:: Auto Save periodically protects against loss of data.
-* File Aliases:: Handling multiple names for one file.
-* Version Control:: Version control systems (RCS, CVS and SCCS).
-* Directories:: Creating, deleting, and listing file directories.
-* Comparing Files:: Finding where two files differ.
-* Diff Mode:: Mode for editing file differences.
-* Misc File Ops:: Other things you can do on files.
-* Compressed Files:: Accessing compressed files.
-* 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.
-* Filesets:: Handling sets of files.
address@hidden menu
-
address@hidden File Names
address@hidden File Names
address@hidden file names
-
- Most Emacs commands that operate on a file require you to specify the
-file name. (Saving and reverting are exceptions; the buffer knows which
-file name to use for them.) You enter the file name using the
-minibuffer (@pxref{Minibuffer}). @dfn{Completion} is available
-(@pxref{Completion}) to make it easier to specify long file names. When
-completing file names, Emacs ignores those whose file-name extensions
-appear in the variable @code{completion-ignored-extensions}; see
address@hidden Options}.
-
- For most operations, there is a @dfn{default file name} which is used
-if you type just @key{RET} to enter an empty argument. Normally the
-default file name is the name of the file visited in the current buffer;
-this makes it easy to operate on that file with any of the Emacs file
-commands.
-
address@hidden default-directory
- Each buffer has a default directory which is normally the same as the
-directory of the file visited in that buffer. When you enter a file
-name without a directory, the default directory is used. If you specify
-a directory in a relative fashion, with a name that does not start with
-a slash, it is interpreted with respect to the default directory. The
-default directory is kept in the variable @code{default-directory},
-which has a separate value in every buffer.
-
address@hidden cd
address@hidden pwd
- 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
address@hidden command is used. A file-visiting buffer's default directory
-is initialized to the directory of the file it visits. If you create
-a buffer with @kbd{C-x b}, its default directory is copied from that
-of the buffer that was current at the time.
-
- For example, if the default file name is @file{/u/rms/gnu/gnu.tasks}
-then the default directory is normally @file{/u/rms/gnu/}. If you
-type just @samp{foo}, which does not specify a directory, it is short
-for @file{/u/rms/gnu/foo}. @samp{../.login} would stand for
address@hidden/u/rms/.login}. @samp{new/foo} would stand for the file name
address@hidden/u/rms/gnu/new/foo}.
-
address@hidden insert-default-directory
- The default directory actually appears in the minibuffer when the
-minibuffer becomes active to read a file name. This serves two
-purposes: it @emph{shows} you what the default is, so that you can type
-a relative file name and know with certainty what it will mean, and it
-allows you to @emph{edit} the default to specify a different directory.
-This insertion of the default directory is inhibited if the variable
address@hidden is set to @code{nil}.
-
- Note that it is legitimate to type an absolute file name after you
-enter the minibuffer, ignoring the presence of the default directory
-name as part of the text. The final minibuffer contents may look
-invalid, but that is not so. For example, if the minibuffer starts out
-with @samp{/usr/tmp/} and you add @samp{/x1/rms/foo}, you get
address@hidden/usr/tmp//x1/rms/foo}; but Emacs ignores everything through the
-first slash in the double slash; the result is @samp{/x1/rms/foo}.
address@hidden File}.
-
address@hidden home directory shorthand
- You can use @file{~/} in a file name to mean your home directory,
-or @address@hidden/} to mean the home directory of a user whose
-login name is @address@hidden
-On MS-Windows and MS-DOS systems, where a user doesn't have a home
-directory, Emacs replaces @file{~/} with the value of the
-environment variable @code{HOME}; see @ref{General Variables}. On
-these systems, the @address@hidden/} construct is supported only
-for the current user, i.e., only if @var{user-id} is the current
-user's login name.}.
-
address@hidden environment variables in file names
address@hidden expansion of environment variables
address@hidden @code{$} in file names
- @anchor{File Names with address@hidden in a file name is used to
-substitute an environment variable. The environment variable name
-consists of all the alphanumeric characters after the @samp{$};
-alternatively, it can be enclosed in braces after the @samp{$}. 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/address@hidden@}/test.c} as an
-abbreviation for @file{/u/rms/hacks/test.c}. If the environment
-variable is not defined, no substitution occurs: @file{/u/$notdefined}
-stands for itself (assuming the environment variable @env{notdefined}
-is not defined).
-
- Note that shell commands to set environment variables affect Emacs
-only when done before Emacs is started.
-
- To access a file with @samp{$} in its name, if the @samp{$} causes
-expansion, type @samp{$$}. This pair is converted to a single
address@hidden at the same time as variable substitution is performed for a
-single @samp{$}. Alternatively, quote the whole file name with
address@hidden/:} (@pxref{Quoted File Names}). File names which begin with a
-literal @samp{~} should also be quoted with @samp{/:}.
-
address@hidden substitute-in-file-name
- The Lisp function that performs the @samp{$}-substitution is called
address@hidden The substitution is performed only on
-file names read as such using the minibuffer.
-
- You can include address@hidden characters in file names if you set the
-variable @code{file-name-coding-system} to a address@hidden value.
address@hidden Name Coding}.
-
address@hidden Visiting
address@hidden Visiting Files
address@hidden visiting files
address@hidden open file
-
address@hidden @kbd
address@hidden C-x C-f
-Visit a file (@code{find-file}).
address@hidden C-x C-r
-Visit a file for viewing, without allowing changes to it
-(@code{find-file-read-only}).
address@hidden C-x C-v
-Visit a different file instead of the one visited last
-(@code{find-alternate-file}).
address@hidden C-x 4 f
-Visit a file, in another window (@code{find-file-other-window}). Don't
-alter what is displayed in the selected window.
address@hidden C-x 5 f
-Visit a file, in a new frame (@code{find-file-other-frame}). Don't
-alter what is displayed in the selected frame.
address@hidden M-x find-file-literally
-Visit a file with no conversion of the contents.
address@hidden table
-
address@hidden files, visiting and saving
address@hidden saving files
- @dfn{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. We often say that this buffer ``is visiting'' that
-file, or that the buffer's ``visited file'' is that file. Emacs
-constructs the buffer name from the file name by throwing away the
-directory, keeping just the name proper. For example, a file named
address@hidden/usr/rms/emacs.tex} would get a buffer named @samp{emacs.tex}.
-If there is already a buffer with that name, Emacs constructs a unique
-name---the normal method is to append @samp{<2>}, @samp{<3>}, and so
-on, but you can select other methods (@pxref{Uniquify}).
-
- Each window's mode line shows the name of the buffer that is being displayed
-in that window, so you can always tell what buffer you are editing.
-
- The changes you make with editing commands are made in the Emacs
-buffer. They do not take effect in the file that you visited, or any
-permanent place, until you @dfn{save} the buffer. Saving the buffer
-means that Emacs writes the current contents of the buffer into its
-visited file. @xref{Saving}.
-
address@hidden modified (buffer)
- If a buffer contains changes that have not been saved, we say the
-buffer is @dfn{modified}. This is important because it implies that
-some changes will be lost if the buffer is not saved. The mode line
-displays two stars near the left margin to indicate that the buffer is
-modified.
-
address@hidden C-x C-f
address@hidden find-file
- To visit a file, use the command @kbd{C-x C-f} (@code{find-file}). Follow
-the command with the name of the file you wish to visit, terminated by a
address@hidden
-
- The file name is read using the minibuffer (@pxref{Minibuffer}), with
-defaulting and completion in the standard manner (@pxref{File Names}).
-While in the minibuffer, you can abort @kbd{C-x C-f} by typing
address@hidden File-name completion ignores certain file names; for more
-about this, see @ref{Completion Options}.
-
- Your confirmation that @kbd{C-x C-f} has completed successfully is
-the appearance of new text on the screen and a new buffer name in the
-mode line. If the specified file does not exist and you could not
-create it, or exists but you can't read it, then you get an error,
-with an error message displayed in the echo area.
-
- If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make
-another copy. It selects the existing buffer containing that file.
-However, before doing so, it checks whether the file itself has changed
-since you visited or saved it last. If the file has changed, Emacs offers
-to reread it.
-
address@hidden large-file-warning-threshold
address@hidden maximum buffer size exceeded, error message
- If you try to visit a file larger than
address@hidden (the default is 10000000, which is
-about 10 megabytes), Emacs will ask you for confirmation first. You
-can answer @kbd{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 around 256 megabytes on 32-bit machines
-(@pxref{Buffers}). If you try, Emacs will display an error message
-saying that the maximum buffer size has been exceeded.
-
address@hidden file selection dialog
- 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 Unix and
-GNU/Linux platforms, Emacs does that 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. However,
-dropping a file into a window displaying a Dired buffer moves or
-copies the file into the displayed directory. For details, see
address@hidden and Drop}, and @ref{Misc Dired Features}.
-
address@hidden creating files
- What if you want to create a new file? Just visit it. Emacs displays
address@hidden(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.
-
- Emacs recognizes from the contents of a file which end-of-line
-convention it uses to separate lines---newline (used on GNU/Linux and
-on Unix), carriage-return linefeed (used on Microsoft systems), or
-just carriage-return (used on the Macintosh)---and automatically
-converts the contents to the normal Emacs convention, which is that
-the newline character separates lines. This is a part of the general
-feature of coding system conversion (@pxref{Coding Systems}), and
-makes it possible to edit files imported from different operating
-systems with equal convenience. If you change the text and save the
-file, Emacs performs the inverse conversion, changing newlines back
-into carriage-return linefeed or just carriage-return if appropriate.
-
address@hidden find-file-run-dired
- If the file you specify is actually a directory, @kbd{C-x C-f} invokes
-Dired, the Emacs directory browser, so that you can ``edit'' the contents
-of the directory (@pxref{Dired}). Dired is a convenient way to view, delete,
-or operate on the files in the directory. However, if the variable
address@hidden is @code{nil}, then it is an error to try
-to visit a directory.
-
- Files which are actually collections of other files, or @dfn{file
-archives}, are visited in special modes which invoke a Dired-like
-environment to allow operations on archive members. @xref{File
-Archives}, for more about these features.
-
address@hidden wildcard characters in file names
address@hidden find-file-wildcards
- 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 @samp{?}, @samp{*}, and
address@hidden@dots{}]} sequences. To enter the wild card @samp{?} in a file
-name in the minibuffer, you need to type @kbd{C-q ?}. @xref{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 @code{find-file-wildcards}.
-
- 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 @kbd{C-x C-q}
-(@code{toggle-read-only}). @xref{Misc Buffer}.
-
address@hidden C-x C-r
address@hidden find-file-read-only
- If you want to visit a file as read-only in order to protect
-yourself from entering changes accidentally, visit it with the command
address@hidden C-r} (@code{find-file-read-only}) instead of @kbd{C-x C-f}.
-
address@hidden C-x C-v
address@hidden find-alternate-file
- If you visit a nonexistent file unintentionally (because you typed the
-wrong file name), use the @kbd{C-x C-v} command
-(@code{find-alternate-file}) to visit the file you really wanted.
address@hidden C-v} is similar to @kbd{C-x C-f}, but it kills the current
-buffer (after first offering to save it if it is modified). When
address@hidden 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.
-
address@hidden C-x 4 f
address@hidden find-file-other-window
- @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f}
-except that the buffer containing the specified file is selected in another
-window. The window that was selected before @kbd{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}.
-
address@hidden C-x 5 f
address@hidden find-file-other-frame
- @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a
-new frame, or makes visible any existing frame showing the file you
-seek. This feature is available only when you are using a window
-system. @xref{Frames}.
-
address@hidden find-file-literally
- If you wish to edit a file as a sequence of @acronym{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
-Systems}), or automatic uncompression (@pxref{Compressed Files}), and
-does not add a final newline because of @code{require-final-newline}.
-If you already have visited the same file in the usual (non-literal)
-manner, this command asks you whether to visit it literally instead.
-
address@hidden find-file-hook
address@hidden 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-functions}; this variable holds a list
-of functions, and the functions are called one by one (with no
-arguments) until one of them returns address@hidden This is not a
-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-hook}, with no arguments.
-This variable is a normal hook. In the case of a nonexistent file, the
address@hidden 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}).
-
address@hidden Saving
address@hidden Saving Files
-
- @dfn{Saving} a buffer in Emacs means writing its contents back into the file
-that was visited in the buffer.
-
address@hidden
-* Save Commands:: Commands for saving files.
-* Backup:: How Emacs saves the old version of your file.
-* Customize Save:: Customizing the saving of files.
-* Interlocking:: How Emacs protects against simultaneous editing
- of one file by two users.
-* Shadowing: File Shadowing. Copying files to "shadows" automatically.
-* Time Stamps:: Emacs can update time stamps on saved files.
address@hidden menu
-
address@hidden Save Commands
address@hidden Commands for Saving Files
-
- These are the commands that relate to saving and writing files.
-
address@hidden @kbd
address@hidden C-x C-s
-Save the current buffer in its visited file on disk (@code{save-buffer}).
address@hidden C-x s
-Save any or all buffers in their visited files (@code{save-some-buffers}).
address@hidden M-~
-Forget that the current buffer has been changed (@code{not-modified}).
-With prefix argument (@kbd{C-u}), mark the current buffer as changed.
address@hidden C-x C-w
-Save the current buffer with a specified file name (@code{write-file}).
address@hidden M-x set-visited-file-name
-Change the file name under which the current buffer will be saved.
address@hidden table
-
address@hidden C-x C-s
address@hidden save-buffer
- When you wish to save the file and make your changes permanent, type
address@hidden C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x
C-s}
-displays a message like this:
-
address@hidden
-Wrote /u/rms/gnu/gnu.tasks
address@hidden example
-
address@hidden
-If the selected 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, @kbd{C-x C-s} displays a message
-like this in the echo area:
-
address@hidden
-(No changes need to be saved)
address@hidden example
-
address@hidden C-x s
address@hidden save-some-buffers
- The command @kbd{C-x s} (@code{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 @code{query-replace}:
-
address@hidden @kbd
address@hidden y
-Save this buffer and ask about the rest of the buffers.
address@hidden n
-Don't save this buffer, but ask about the rest of the buffers.
address@hidden !
-Save this buffer and all the rest with no more questions.
address@hidden following generates acceptable underfull hbox
address@hidden @key{RET}
-Terminate @code{save-some-buffers} without any more saving.
address@hidden .
-Save this buffer, then exit @code{save-some-buffers} without even asking
-about other buffers.
address@hidden C-r
-View the buffer that you are currently being asked about. When you exit
-View mode, you get back to @code{save-some-buffers}, which asks the
-question again.
address@hidden d
-Diff the buffer against its corresponding file, so you can see
-what changes you would be saving.
address@hidden C-h
-Display a help message about these options.
address@hidden table
-
- @kbd{C-x C-c}, the key sequence to exit Emacs, invokes
address@hidden and therefore asks the same questions.
-
address@hidden M-~
address@hidden not-modified
- If you have changed a buffer but you do not want to save the changes,
-you should take some action to prevent it. Otherwise, each time you use
address@hidden s} or @kbd{C-x C-c}, you are liable to save this buffer by
-mistake. One thing you can do is type @kbd{M-~} (@code{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. (@samp{~} is often used as a mathematical symbol for `not'; thus
address@hidden is `not', metafied.) You could also use
address@hidden (see below) to mark the buffer as visiting
-a different file name, one which is not in use for anything important.
-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 @dfn{reverting}. @xref{Reverting}. (You could also undo all the
-changes by repeating the undo command @kbd{C-x u} until you have undone
-all the changes; but reverting is easier.) You can also kill the buffer.
-
address@hidden set-visited-file-name
- @kbd{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. @code{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 @kbd{C-x C-s} in that buffer
address@hidden save.
-
address@hidden C-x C-w
address@hidden write-file
- If you wish to mark the buffer as visiting a different file and save it
-right away, use @kbd{C-x C-w} (@code{write-file}). It is
-equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}
-(except that @kbd{C-x C-w} asks for confirmation if the file exists).
address@hidden C-s} used on a buffer that is not visiting a file has the
-same effect as @kbd{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 (@pxref{File Names}).
-
- If the new file name implies a major mode, then @kbd{C-x C-w} switches
-to that major mode, in most cases. The command
address@hidden 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.
address@hidden,, Simultaneous Editing}.
-
address@hidden Backup
address@hidden Backup Files
address@hidden backup file
address@hidden make-backup-files
address@hidden vc-make-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
address@hidden file, before actually saving.
-
- For most files, the variable @code{make-backup-files} determines
-whether to make backup files. On most operating systems, its default
-value is @code{t}, so that Emacs does write backup files.
-
- For files managed by a version control system (@pxref{Version
-Control}), the variable @code{vc-make-backup-files} determines whether
-to make backup files. By default it is @code{nil}, since backup files
-are redundant when you store all the previous versions in a version
-control system.
address@hidden
address@hidden VC Options,,,emacs-xtra, Specialized Emacs Features}.
address@hidden iftex
address@hidden
address@hidden VC Options}.
address@hidden ifnottex
-
-
- 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.
-
address@hidden backup-enable-predicate
address@hidden temporary-file-directory
address@hidden small-temporary-file-directory
- The default value of the @code{backup-enable-predicate} variable
-prevents backup files being written for files in the directories used
-for temporary files, specified by @code{temporary-file-directory} or
address@hidden
-
- Emacs makes a backup for a file only the first time the file is saved
-from one buffer. No matter how many times you save a file, its backup file
-continues to contain the contents from before the file was visited.
-Normally this means that the backup file contains the contents from before
-the current editing session; however, if you kill the buffer and then visit
-the file again, a new backup file will be made by the next save.
-
- You can also explicitly request making another backup file from a
-buffer even though it has already been saved at least once. If you save
-the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made
-into a backup file if you save the buffer again. @kbd{C-u C-u C-x C-s}
-saves the buffer, but first makes the previous file contents into a new
-backup file. @kbd{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.
-
address@hidden
-* One or Many: Numbered Backups. Whether to make one backup file or many.
-* Names: Backup Names. How backup files are named.
-* Deletion: Backup Deletion. Emacs deletes excess numbered backups.
-* Copying: Backup Copying. Backups can be made by copying or renaming.
address@hidden menu
-
address@hidden Numbered Backups
address@hidden Numbered Backups
-
address@hidden version-control
- The choice of single backup file or multiple numbered backup files
-is controlled by the variable @code{version-control}. Its possible
-values are:
-
address@hidden @code
address@hidden t
-Make numbered backups.
address@hidden nil
-Make numbered backups for files that have numbered backups already.
-Otherwise, make single backups.
address@hidden never
-Never make numbered backups; always make single backups.
address@hidden table
-
address@hidden
-The usual way to set this variable is globally, through your
address@hidden file or the customization buffer. However, you can set
address@hidden locally in an individual buffer to control the
-making of backups for that buffer's file. For example, Rmail mode
-locally sets @code{version-control} to @code{never} to make sure that
-there is only one backup for an Rmail file. @xref{Locals}.
-
address@hidden @env{VERSION_CONTROL} environment variable
- If you set the environment variable @env{VERSION_CONTROL}, to tell
-various GNU utilities what to do with backup files, Emacs also obeys the
-environment variable by setting the Lisp variable @code{version-control}
-accordingly at startup. If the environment variable's value is @samp{t}
-or @samp{numbered}, then @code{version-control} becomes @code{t}; if the
-value is @samp{nil} or @samp{existing}, then @code{version-control}
-becomes @code{nil}; if it is @samp{never} or @samp{simple}, then
address@hidden becomes @code{never}.
-
address@hidden Backup Names
address@hidden Single or Numbered Backups
-
- When Emacs makes a single backup file, its name is normally
-constructed by appending @samp{~} to the file name being edited; thus,
-the backup file for @file{eval.c} would be @file{eval.c~}.
-
address@hidden make-backup-file-name-function
address@hidden backup-directory-alist
- You can change this behavior by defining the variable
address@hidden to a suitable function.
-Alternatively you can customize the variable
address@hidden 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 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
address@hidden applies to numbered backups just as
-usual.
-
address@hidden Backup Deletion
address@hidden 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.
-
address@hidden kept-old-versions
address@hidden kept-new-versions
- The two variables @code{kept-old-versions} and
address@hidden 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 @code{kept-new-versions}. By
-default, both variables are 2.
-
address@hidden delete-old-versions
- If @code{delete-old-versions} is @code{t}, Emacs deletes the excess
-backup files silently. If it is @code{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 @kbd{.} (Period) command can also be used to delete old versions.
address@hidden Deletion}.
-
address@hidden Backup Copying
address@hidden 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).
-
- Having the owner change is usually a good idea, because then the owner
-always shows who last edited the file. Also, the owners of the backups
-show who produced those versions. Occasionally there is a file whose
-owner should not change; it is a good idea for such files to contain
-local variable lists to set @code{backup-by-copying-when-mismatch}
-locally (@pxref{File Variables}).
-
address@hidden backup-by-copying
address@hidden backup-by-copying-when-linked
address@hidden backup-by-copying-when-mismatch
address@hidden backup-by-copying-when-privileged-mismatch
address@hidden file ownership, and backup
address@hidden backup, and user-id
- The choice of renaming or copying is controlled by four variables.
-Renaming is the default choice. If the variable
address@hidden is address@hidden, copying is used. Otherwise,
-if the variable @code{backup-by-copying-when-linked} is address@hidden,
-then copying is used for files that have multiple names, but renaming
-may still be used when the file being edited has only one name. If the
-variable @code{backup-by-copying-when-mismatch} is address@hidden, then
-copying is used if renaming would cause the file's owner or group to
-change. @code{backup-by-copying-when-mismatch} is @code{t} by default
-if you start Emacs as the superuser. The fourth variable,
address@hidden, gives the highest
-numeric user-id for which @code{backup-by-copying-when-mismatch} will be
-forced on. This is useful when low-numbered user-ids are assigned to
-special system users, such as @code{root}, @code{bin}, @code{daemon},
-etc., which must maintain ownership of files.
-
- 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.
-
address@hidden Customize Save
address@hidden Customizing Saving of Files
-
address@hidden require-final-newline
- If the value of the variable @code{require-final-newline} is
address@hidden, saving or writing a file silently puts a newline at the end
-if there isn't already one there. If the value is @code{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 @code{visit-save}, that means to add
-newlines both on visiting and on saving. If the value is @code{nil},
-Emacs leaves the end of the file unchanged; if it's neither @code{nil}
-nor @code{t}, Emacs asks you whether to add a newline. The default is
address@hidden
-
address@hidden mode-require-final-newline
- Many major modes are designed for specific kinds of files that are
-always supposed to end in newlines. These major modes set the
-variable @code{require-final-newline} according to
address@hidden By setting the latter variable,
-you can control how these modes handle final newlines.
-
address@hidden write-region-inhibit-fsync
- When Emacs saves a file, it invokes the @code{fsync} system call to
-force the data immediately out to disk. This is important for safety
-if the system crashes or in case of power outage. However, it can be
-disruptive on laptops using power saving, because it requires the disk
-to spin up each time you save a file. Setting
address@hidden to a address@hidden value disables
-this synchronization. Be careful---this means increased risk of data
-loss.
-
address@hidden Interlocking
address@hidden Protection against Simultaneous Editing
-
address@hidden file dates
address@hidden simultaneous editing
- Simultaneous editing occurs when two users visit the same file, both
-make changes, and then both save them. If nobody were informed that
-this was happening, whichever user saved 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.
-
address@hidden ask-user-about-lock
address@hidden locking files
- When you make the first modification in an Emacs buffer that is
-visiting a file, Emacs records that the file is @dfn{locked} by you.
-(It does this by creating a symbolic link in the same directory with a
-different name.) 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.
-
address@hidden collision
- If you begin to modify the buffer while the visited file is locked by
-someone else, this constitutes a @dfn{collision}. When Emacs detects a
-collision, it asks you what to do, by calling the Lisp function
address@hidden 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:
-
address@hidden @kbd
address@hidden s
-Steal the lock. Whoever was already changing the file loses the lock,
-and you gain the lock.
address@hidden p
-Proceed. Go ahead and edit the file despite its being locked by someone else.
address@hidden q
-Quit. This causes an error (@code{file-locked}), and the buffer
-contents remain unchanged---the modification you were trying to make
-does not actually take place.
address@hidden table
-
- Note that locking works on the basis of a file name; if a file has
-multiple names, Emacs does not realize that the two names are the same file
-and cannot prevent two users from editing it simultaneously under different
-names. However, basing locking on names means that Emacs can interlock the
-editing of new files that will not really exist until they are saved.
-
- Some systems are not configured to allow Emacs to make locks, and
-there are cases where lock files cannot be written. In these cases,
-Emacs cannot detect trouble in advance, but it still can detect the
-collision when you try to save a file and overwrite someone else's
-changes.
-
- 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 @kbd{p} to tell Emacs to go ahead anyway.
-
- Every time Emacs saves a buffer, it first checks the last-modification
-date of the existing file on disk to verify that it has not changed since the
-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
-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.
-
- The first thing you should do when notified that simultaneous editing
-has already taken place is to list the directory with @kbd{C-u C-x C-d}
-(@pxref{Directories}). This shows the file's current author. You
-should attempt to contact him to warn him not to continue editing.
-Often the next step is to save the contents of your Emacs buffer under a
-different name, and use @code{diff} to compare the two address@hidden
-
address@hidden File Shadowing
address@hidden Shadowing Files
address@hidden shadow files
address@hidden file shadows
address@hidden shadow-initialize
-
address@hidden @kbd
address@hidden M-x shadow-initialize
-Set up file shadowing.
address@hidden M-x shadow-define-literal-group
-Declare a single file to be shared between sites.
address@hidden M-x shadow-define-regexp-group
-Make all files that match each of a group of files be shared between hosts.
address@hidden M-x shadow-define-cluster @key{RET} @var{name} @key{RET}
-Define a shadow file cluster @var{name}.
address@hidden M-x shadow-copy-files
-Copy all pending shadow files.
address@hidden M-x shadow-cancel
-Cancel the instruction to shadow some files.
address@hidden table
-
-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 shadow 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
address@hidden 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 host names of all the other hosts
-in the cluster. You can define a shadow cluster with @kbd{M-x
-shadow-define-cluster}.
-
address@hidden Time Stamps
address@hidden Updating Time Stamps Automatically
address@hidden time stamps
address@hidden modification dates
address@hidden locale, date format
-
-You can arrange to 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:
-
address@hidden
-Time-stamp: <>
address@hidden example
-
address@hidden
-or like this:
-
address@hidden
-Time-stamp: " "
address@hidden example
-
address@hidden time-stamp
- Then add the hook function @code{time-stamp} to the hook
address@hidden; 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
address@hidden Note that non-numeric fields in the time stamp are
-formatted according to your locale setting (@pxref{Environment}).
-
address@hidden Reverting
address@hidden Reverting a Buffer
address@hidden revert-buffer
address@hidden drastic changes
address@hidden reread a file
-
- If you have made extensive changes to a file and then change your mind
-about them, you can get rid of them by reading in the previous version
-of the file. To do this, use @kbd{M-x revert-buffer}, which operates on
-the current buffer. Since reverting a buffer unintentionally could lose
-a lot of work, you must confirm this command with @kbd{yes}.
-
- @code{revert-buffer} tries to position point in such a way that, if
-the file was edited only slightly, you will be at approximately the
-same piece of text after reverting as before. However, if you have made
-drastic changes, point may wind up in a totally different piece of text.
-
- Reverting marks the buffer as ``not modified'' until another change is
-made.
-
- Some kinds of buffers whose contents reflect data bases other than files,
-such as Dired buffers, can also be reverted. For them, reverting means
-recalculating their contents from the appropriate data base. Buffers
-created explicitly with @kbd{C-x b} cannot be reverted; @code{revert-buffer}
-reports an error when asked to do so.
-
address@hidden revert-without-query
- 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, whenever you
-visit the file again with @kbd{C-x C-f}.
-
- To request this behavior, set the variable @code{revert-without-query}
-to a list of regular expressions. When a file name matches one of these
-regular expressions, @code{find-file} and @code{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.)
-
address@hidden Global Auto-Revert mode
address@hidden mode, Global Auto-Revert
address@hidden Auto-Revert mode
address@hidden mode, Auto-Revert
address@hidden global-auto-revert-mode
address@hidden auto-revert-mode
address@hidden auto-revert-tail-mode
-
- You may find it useful to have Emacs revert files automatically when
-they change. Three minor modes are available to do this.
-
- @kbd{M-x global-auto-revert-mode} enables Global Auto-Revert mode,
-which periodically checks all file buffers and reverts when the
-corresponding file has changed. @kbd{M-x auto-revert-mode} enables a
-local version, Auto-Revert mode, which applies only to the current
-buffer.
-
- You can use Auto-Revert mode 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
-(@code{auto-revert-tail-mode}). It is more efficient for this.
-
address@hidden auto-revert-interval
- The variable @code{auto-revert-interval} controls how often to check
-for a changed file. Since checking a remote file is too slow, these
-modes do not check or revert remote files.
-
- @xref{VC Mode Line}, for Auto Revert peculiarities in buffers that
-visit files under version control.
-
address@hidden
address@hidden arevert-xtra.texi
address@hidden ifnottex
-
address@hidden Auto Save
address@hidden Auto-Saving: Protection Against Disasters
address@hidden Auto Save mode
address@hidden mode, Auto Save
address@hidden crashes
-
- Emacs saves all the visited files from time to time (based on counting
-your keystrokes) without being asked. This is called @dfn{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 @samp{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.
-
address@hidden
-* Files: Auto Save Files. The file where auto-saved changes are
- actually made until you save the file.
-* Control: Auto Save Control. Controlling when and how often to auto-save.
-* Recover:: Recovering text from auto-save files.
address@hidden menu
-
address@hidden Auto Save Files
address@hidden Auto-Save Files
-
- Auto-saving does not normally save in the files that you visited, because
-it can be very undesirable to save a program that is in an inconsistent
-state when you have made half of a planned change. Instead, auto-saving
-is done in a different file called the @dfn{auto-save file}, and the
-visited file is changed only when you request saving explicitly (such as
-with @kbd{C-x C-s}).
-
- Normally, the auto-save file name is made by appending @samp{#} to the
-front and rear of the visited file name. Thus, a buffer visiting file
address@hidden 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
address@hidden 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 might be 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
address@hidden). The file name to be used for auto-saving
-in a buffer is calculated when auto-saving is turned on in that buffer.
-
address@hidden auto-save for remote files
address@hidden auto-save-file-name-transforms
- The variable @code{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 (@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
-useful if it contains the deleted text. To reenable auto-saving after
-this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x
-auto-save-mode}.
-
address@hidden auto-save-visited-file-name
- If you want auto-saving to be done in the visited file rather than
-in a separate auto-save file, set the variable
address@hidden to a address@hidden value. In this
-mode, there is no real difference between auto-saving and explicit
-saving.
-
address@hidden delete-auto-save-files
- 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
address@hidden to @code{nil}.) Changing the visited
-file name with @kbd{C-x C-w} or @code{set-visited-file-name} renames
-any auto-save file to go with the new visited name.
-
address@hidden Auto Save Control
address@hidden Controlling Auto-Saving
-
address@hidden auto-save-default
address@hidden auto-save-mode
- Each time you visit a file, auto-saving is turned on for that file's
-buffer if the variable @code{auto-save-default} is address@hidden (but not
-in batch mode; @pxref{Entering Emacs}). The default for this variable is
address@hidden, so auto-saving is the usual practice for file-visiting buffers.
-Auto-saving can be turned on or off for any existing buffer with the
-command @kbd{M-x auto-save-mode}. Like other minor mode commands, @kbd{M-x
-auto-save-mode} turns auto-saving on with a positive argument, off with a
-zero or negative argument; with no argument, it toggles.
-
address@hidden auto-save-interval
- Emacs does auto-saving periodically based on counting how many characters
-you have typed since the last time auto-saving was done. The variable
address@hidden 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 @code{auto-save-interval} to a value less
-than 20, Emacs will behave as if the value is 20.
-
address@hidden auto-save-timeout
- Auto-saving also takes place when you stop typing for a while. The
-variable @code{auto-save-timeout} says how many seconds Emacs should
-wait before it does an auto save (and perhaps also a garbage
-collection). (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 @samp{kill
-%emacs}, or disconnecting a phone line or network connection.
-
address@hidden do-auto-save
- You can request an auto-save explicitly with the command @kbd{M-x
-do-auto-save}.
-
address@hidden Recover
address@hidden Recovering Data from Auto-Saves
-
address@hidden recover-file
- You can use the contents of an auto-save file to recover from a loss
-of data with the command @kbd{M-x recover-file @key{RET} @var{file}
address@hidden This visits @var{file} and then (after your confirmation)
-restores the contents from its auto-save file @address@hidden
-You can then save with @kbd{C-x C-s} to put the recovered text into
address@hidden itself. For example, to recover file @file{foo.c} from its
-auto-save file @file{#foo.c#}, do:@refill
-
address@hidden
-M-x recover-file @key{RET} foo.c @key{RET}
-yes @key{RET}
-C-x C-s
address@hidden example
-
- Before asking for confirmation, @kbd{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, @kbd{M-x recover-file} does not offer to read it.
-
address@hidden recover-session
- If Emacs or the computer crashes, you can recover all the files you
-were editing from their auto save files with the command @kbd{M-x
-recover-session}. This first shows you a list of recorded interrupted
-sessions. Move point to the one you choose, and type @kbd{C-c C-c}.
-
- Then @code{recover-session} asks about each of the files that were
-being edited during that session, asking whether to recover that file.
-If you answer @kbd{y}, it calls @code{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 @code{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.
-
address@hidden auto-save-list-file-prefix
- Emacs records information about interrupted sessions for later
-recovery in files named
address@hidden/.emacs.d/auto-save-list/address@hidden@var{hostname}}. All
-of this name except the @address@hidden@var{hostname}} part 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
address@hidden file, sessions are not recorded for recovery.
-
address@hidden File Aliases
address@hidden File Name Aliases
address@hidden symbolic links (visiting)
address@hidden hard links (visiting)
-
- 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 @file{foo} is a symbolic link to @file{bar}, you can use
-either name to refer to the file, but @file{bar} is the real name, while
address@hidden is just an alias. More complex cases occur when symbolic
-links point to directories.
-
address@hidden find-file-existing-other-name
address@hidden 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 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
address@hidden to a address@hidden
-value. You can disable this feature entirely by setting the variable
address@hidden to @code{nil}: then if you visit
-the same file under two different names, you get a separate buffer for
-each file name.
-
address@hidden find-file-visit-truename
address@hidden truenames of files
address@hidden file truenames
- If the variable @code{find-file-visit-truename} is address@hidden,
-then the file name recorded for a buffer is the file's @dfn{truename}
-(made by replacing all symbolic links with their target names), rather
-than the name you specify. Setting @code{find-file-visit-truename} also
-implies the effect of @code{find-file-existing-other-name}.
-
address@hidden Version Control
address@hidden Version Control
address@hidden version control
-
- @dfn{Version control systems} are packages that can record multiple
-versions of a source file, usually storing the unchanged parts of the
-file just once. Version control systems also record history information
-such as the creation time of each version, who created it, and a
-description of what was changed in that version.
-
- The Emacs version control interface is called VC. Its commands work
-with different version control systems---currently, it supports CVS,
-GNU Arch, RCS, Meta-CVS, Subversion, and SCCS. Of these, the GNU
-project distributes CVS, GNU Arch, and RCS; we recommend that you use
-either CVS or GNU Arch for your projects, and RCS for individual
-files. 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.
-
- VC is enabled by default in Emacs. To disable it, set the
-customizable variable @code{vc-handled-backends} to @code{nil}
address@hidden
-(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
address@hidden iftex
address@hidden
-(@pxref{Customizing VC}).
address@hidden ifnottex
-
-
address@hidden
-* Introduction to VC:: How version control works in general.
-* 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.
-* Branches:: Multiple lines of development.
address@hidden
-* Remote Repositories:: Efficient access to remote CVS servers.
-* Snapshots:: Sets of file versions treated as a unit.
-* Miscellaneous VC:: Various other commands and features of VC.
-* Customizing VC:: Variables that change VC's behavior.
address@hidden ifnottex
address@hidden menu
-
address@hidden Introduction to VC
address@hidden Introduction to Version Control
-
- VC allows you to use a version control system from within Emacs,
-integrating the version control operations smoothly with editing. VC
-provides a uniform interface to version control, so that regardless of
-which version control system is in use, you can use it the same way.
-
- This section provides a general overview of version control, and
-describes the version control systems that VC supports. You can skip
-this section if you are already familiar with the version control system
-you want to use.
-
address@hidden
-* Why Version Control?:: Understanding the problems it addresses
-* 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.
address@hidden menu
-
address@hidden Why Version Control?
address@hidden Understanding the problems it addresses
-
- Version control systems provide you with three important capabilities:
-reversibility, concurrency, and history.
-
- The most basic capability you get from a version-control system is
-reversibility, the ability to back up to a saved, known-good state when
-you discover that some modification you did was a mistake or a bad idea.
-
- Version-control systems also support concurrency, the ability to
-have many people modifying the same collection of code or documents
-knowing that conflicting modifications can be detected and resolved.
-
- Version-control systems give you the capability to attach a history
-to your data, explanatory comments about the intention behind each
-change to it. Even for a programmer working solo change histories
-are an important aid to memory; for a multi-person project they
-become a vitally important form of communication among developers.
-
address@hidden Version Systems
address@hidden Supported Version Control Systems
-
address@hidden back end (version control)
- VC currently works with six different version control systems or
-``back ends'': CVS, GNU Arch, RCS, Meta-CVS, Subversion, and SCCS.
-
address@hidden CVS
- CVS is a free version control system that is used for the majority
-of free software projects today. It allows concurrent multi-user
-development either locally or over the network. Some of its
-shortcomings, corrected by newer systems such as GNU Arch, are that it
-lacks atomic commits or support for renaming files. VC supports all
-basic editing operations under CVS, but for some less common tasks you
-still need to call CVS from the command line. Note also that before
-using CVS you must set up a repository, which is a subject too complex
-to treat here.
-
address@hidden GNU Arch
address@hidden Arch
- GNU Arch is a new version control system that is designed for
-distributed work. It differs in many ways from old well-known
-systems, such as CVS and RCS. It supports different transports for
-interoperating between users, offline operations, and it has good
-branching and merging features. It also supports atomic commits, and
-history of file renaming and moving. VC does not support all
-operations provided by GNU Arch, so you must sometimes invoke it from
-the command line, or use a specialized module.
-
address@hidden RCS
- RCS is the free version control system around which VC was initially
-built. The VC commands are therefore conceptually closest to RCS.
-Almost everything you can do with RCS can be done through VC. You
-cannot use RCS over the network though, and it only works at the level
-of individual files, rather than projects. You should use it if you
-want a simple, yet reliable tool for handling individual files.
-
address@hidden SVN
address@hidden Subversion
- Subversion is a free version control system designed to be similar
-to CVS but without CVS's problems. Subversion supports atomic commits,
-and versions directories, symbolic links, meta-data, renames, copies,
-and deletes. It can be used via http or via its own protocol.
-
address@hidden MCVS
address@hidden Meta-CVS
- Meta-CVS is another attempt to solve problems arising in CVS. It
-supports directory structure versioning, improved branching and
-merging, and use of symbolic links and meta-data in repositories.
-
address@hidden SCCS
- SCCS is a proprietary but widely used version control system. In
-terms of capabilities, it is the weakest of the six that VC supports.
-VC compensates for certain features missing in SCCS (snapshots, for
-example) by implementing them itself, but some other VC features, such
-as multiple branches, are not available with SCCS. Since SCCS is
-non-free, not respecting its users freedom, you should not use it;
-use its free replacement CSSC instead. But you should use CSSC only
-if for some reason you cannot use RCS, or one of the higher-level
-systems such as CVS or GNU Arch.
-
-In the following, we discuss mainly RCS, SCCS and CVS. Nearly
-everything said about CVS applies to GNU Arch, Subversion and Meta-CVS
-as well.
-
address@hidden VC Concepts
address@hidden Concepts of Version Control
-
address@hidden master file
address@hidden registered file
- When a file is under version control, we also say that it is
address@hidden in the version control system. Each registered file
-has a corresponding @dfn{master file} which represents the file's
-present state plus its change history---enough to reconstruct the
-current version or any earlier version. Usually the master file also
-records a @dfn{log entry} for each version, describing in words what was
-changed in that version.
-
address@hidden work file
address@hidden checking out files
- The file that is maintained under version control is sometimes called
-the @dfn{work file} corresponding to its master file. You edit the work
-file and make changes in it, as you would with an ordinary file. (With
-SCCS and RCS, you must @dfn{lock} the file before you start to edit it.)
-After you are done with a set of changes, you @dfn{check the file in},
-which records the changes in the master file, along with a log entry for
-them.
-
- To go beyond these basic concepts, you will need to understand three
-ways in which version-control systems can differ from each other. They
-can be locking or merging; they can be file-based or changeset-based;
-and they can be centralized or decentralized. VC handles all these
-choices, but they lead to differing behaviors which you will need
-to understand as you use it.
-
address@hidden locking versus merging
- A version control system typically has some mechanism to coordinate
-between users who want to change the same file. One method is
address@hidden (analogous to the locking that Emacs uses to detect
-simultaneous editing of a file, but distinct from it). In a locking
-system, such as SCCS, you must @dfn{lock} a file before you start to
-edit it. The other method is @dfn{merging}; the system tries to
-merge your changes with other people's changes when you check them in.
-
- With version control locking, work files are normally read-only so
-that you cannot change them. You ask the version control system to make
-a work file writable for you by locking it; only one user can do
-this at any given time. When you check in your changes, that unlocks
-the file, making the work file read-only again. This allows other users
-to lock the file to make further changes.
-
- By contrast, a merging system lets each user check out and modify a
-work file at any time. When you check in a a file, the system will
-attempt to merge your changes with any others checked into the
-repository since you checked out the file.
-
- Both locking and merging systems can have problems when multiple users
-try to modify the same file at the same time. Locking systems have
address@hidden conflicts}; a user may try to check a file out and be unable
-to because it is locked. In merging systems, @dfn{merge conflicts}
-happen when you check in a change to a file that conflicts with a change
-checked in by someone else after your checkout. Both kinds of conflict
-have to be resolved by human judgment and communication.
-
- SCCS always uses locking. RCS is lock-based by default but can be told
-to operate in a merging style. CVS is merge-based by default but can
-be told to operate in a locking mode. Most later version-control
-systems, such as Subversion and GNU Arch, have been fundamentally
-merging-based rather than locking-based. This is because experience
-has shown that the merging-based approach is generally superior to
-the locking one, both in convenience to developers and in minimizing
-the number and severity of conflicts that actually occur.
-
- While it is rather unlikely that anyone will ever again build a
-fundamentally locking-based rather than merging-based version-control
-system in the future, merging-based version-systems sometimes have locks
-retrofitted onto them for reasons having nothing to do with technology.
address@hidden the control-freak instincts of managers.} For this
-reason, and to support older systems still in use, VC mode supports
-both locking and merging version control and tries to hide the differences
-between them as much as possible.
-
address@hidden files versus changesets.
- On SCCS, RCS, CVS, and other early version-control systems, checkins
-and other operations are @dfn{file-based}; each file has its own
address@hidden file} with its own comment- and revision history separate
-from that of all other files in the system. Later systems, beginning
-with Subversion, are @dfn{changeset-based}; a checkin may include
-changes to several files and that change set is treated as a unit by the
-system. Any comment associated with the change doesn't belong to any
-one file, but is attached to the changeset itself.
-
- Changeset-based version control is in general both more flexible and
-more powerful than file-based version control; usually, when a change to
-multiple files has to be backed out, it's good to be able to easily
-identify and remove all of it.
-
address@hidden centralized vs. decentralized
- Early version-control systems were designed around a @dfn{centralized}
-model in which each project has only one repository used by all
-developers. SCCS, RCS, CVS, and Subversion share this kind of model.
-It has two important problems. One is that a single repository is a
-single point of failure---if the repository server is down all work
-stops. The other is that you need to be connected live to the server to
-do checkins and checkouts; if you're offline, you can't work.
-
- Newer version-control systems like GNU Arch are @dfn{decentralized}.
-A project may have several different repositories, and these systems
-support a sort of super-merge between repositories that tries to
-reconcile their change histories. At the limit, each developer has
-his/her own repository, and repository merges replace checkin/commit
-operations.
-
- VC's job is to help you manage the traffic between your personal
-workfiles and a repository. Whether that repository is a single master
-or one of a network of peer repositories is not something VC has to care
-about. Thus, the difference between a centralized and a decentralized
-version-control system is invisible to VC mode.
-
address@hidden
-(@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}).
address@hidden iftex
address@hidden
-(@pxref{CVS Options}).
address@hidden ifnottex
-
-
address@hidden Types of Log File
address@hidden Types of Log File
address@hidden types of log file
address@hidden log File, types of
address@hidden version control log
-
- Projects that use a revision control system can have @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
address@hidden control log}, @dfn{RCS log}, or @dfn{CVS log}.
-
- The other kind of log is the file @file{ChangeLog} (@pxref{Change
-Log}). It provides a chronological record of all changes to a large
-portion of a program---typically 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.
address@hidden Log}.
-
- A project maintained with version control can use just the per-file
-log, or it can use both kinds of logs. It can handle some files one
-way and some files the other way. Each project has its policy, which
-you should follow.
-
- When the policy is to use both, you typically want to write an entry
-for each change just once, then put it into both logs. 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}
address@hidden
-(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
address@hidden iftex
address@hidden
-(@pxref{Change Logs and VC}).
address@hidden ifnottex
-
-
address@hidden VC Mode Line
address@hidden Version Control and the Mode Line
-
- When you visit a file that is under version control, Emacs indicates
-this on the mode line. For example, @samp{RCS-1.3} says that RCS is
-used for that file, and the current version is 1.3.
-
- The character between the back-end name and the version number
-indicates the version control status of the file. @samp{-} means that
-the work file is not locked (if locking is in use), or not modified (if
-locking is not in use). @samp{:} indicates that the file is locked, or
-that it is modified. If the file is locked by some other user (for
-instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
-
address@hidden auto-revert-check-vc-info
- When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is
-under version control, it updates the version control information in
-the mode line. However, Auto Revert mode may not properly update this
-information if the version control status changes without changes to
-the work file, from outside the current Emacs session. If you set
address@hidden to @code{t}, Auto Revert mode updates
-the version control status information every
address@hidden seconds, even if the work file itself is
-unchanged. The resulting CPU usage depends on the version control
-system, but is usually not excessive.
-
address@hidden Basic VC Editing
address@hidden Basic Editing under Version Control
-
- The principal VC command is an all-purpose command that performs
-either locking or check-in, depending on the situation.
-
address@hidden @kbd
address@hidden C-x v v
-Perform the next logical version control operation on this file.
address@hidden table
-
address@hidden vc-next-action
address@hidden C-x v v
- The precise action of this command depends on the state of the file,
-and whether the version control system uses locking or not. SCCS and
-RCS normally use locking; CVS normally does not use locking.
-
address@hidden vc-toggle-read-only
address@hidden C-x C-q @r{(Version Control)}
- As a special convenience that is particularly useful for files with
-locking, you can let Emacs check a file in or out whenever you change
-its read-only flag. This means, for example, that you cannot
-accidentally edit a file without properly checking it out first. To
-achieve this, bind the key @kbd{C-x C-q} to @kbd{vc-toggle-read-only}
-in your @file{~/.emacs} file. (@xref{Init Rebinding}.)
-
address@hidden
-* VC with Locking:: RCS in its default mode, SCCS, and optionally CVS.
-* Without Locking:: Without locking: default mode for CVS.
-* Advanced C-x v v:: Advanced features available with a prefix argument.
-* Log Buffer:: Features available in log entry buffers.
address@hidden menu
-
address@hidden VC with Locking
address@hidden Basic Version Control with Locking
-
- If locking is used for the file (as with SCCS, and RCS in its default
-mode), @kbd{C-x v v} can either lock a file or check it in:
-
address@hidden @bullet
address@hidden
-If the file is not locked, @kbd{C-x v v} locks it, and
-makes it writable so that you can change it.
-
address@hidden
-If the file is locked by you, and contains changes, @kbd{C-x v v} checks
-in the changes. In order to do this, it first reads the log entry
-for the new version. @xref{Log Buffer}.
-
address@hidden
-If the file is locked by you, but you have not changed it since you
-locked it, @kbd{C-x v v} releases the lock and makes the file read-only
-again.
-
address@hidden
-If the file is locked by some other user, @kbd{C-x v v} asks you whether
-you want to ``steal the lock'' from that user. If you say yes, the file
-becomes locked by you, but a message is sent to the person who had
-formerly locked the file, to inform him of what has happened.
address@hidden itemize
-
- These rules also apply when you use CVS in locking mode, except
-that there is no such thing as stealing a lock.
-
address@hidden Without Locking
address@hidden Basic Version Control without Locking
-
- When there is no locking---the default for CVS---work files are always
-writable; you do not need to do anything before you begin to edit a
-file. The status indicator on the mode line is @samp{-} if the file is
-unmodified; it flips to @samp{:} as soon as you save any changes in the
-work file.
-
- Here is what @kbd{C-x v v} does when using CVS:
-
address@hidden @bullet
address@hidden
-If some other user has checked in changes into the master file, Emacs
-asks you whether you want to merge those changes into your own work
-file. You must do this before you can check in your own changes. (To
-pick up any recent changes from the master file @emph{without} trying
-to commit your own changes, type @kbd{C-x v m @key{RET}}.)
address@hidden
-
address@hidden
-If there are no new changes in the master file, but you have made
-modifications in your work file, @kbd{C-x v v} checks in your changes.
-In order to do this, it first reads the log entry for the new version.
address@hidden Buffer}.
-
address@hidden
-If the file is not modified, the @kbd{C-x v v} does nothing.
address@hidden itemize
-
- These rules also apply when you use RCS in the mode that does not
-require locking, except that automatic merging of changes from the
-master file is not implemented. Unfortunately, this means that nothing
-informs you if another user has checked in changes in the same file
-since you began editing it, and when this happens, his changes will be
-effectively removed when you check in your version (though they will
-remain in the master file, so they will not be entirely lost). You must
-therefore verify that the current version is unchanged, before you
-check in your changes. We hope to eliminate this risk and provide
-automatic merging with RCS in a future Emacs version.
-
- In addition, locking is possible with RCS even in this mode, although
-it is not required; @kbd{C-x v v} with an unmodified file locks the
-file, just as it does with RCS in its normal (locking) mode.
-
address@hidden Advanced C-x v v
address@hidden Advanced Control in @kbd{C-x v v}
-
address@hidden version number to check in/out
- When you give a prefix argument to @code{vc-next-action} (@kbd{C-u
-C-x v v}), it still performs the next logical version control
-operation, but accepts additional arguments to specify precisely how
-to do the operation.
-
address@hidden @bullet
address@hidden
-If the file is modified (or locked), you can specify the version
-number to use for the new version that you check in. This is one way
-to create a new branch (@pxref{Branches}).
-
address@hidden
-If the file is not modified (and unlocked), you can specify the
-version to select; this lets you start working from an older version,
-or on another branch. If you do not enter any version, that takes you
-to the highest version on the current branch; therefore @kbd{C-u C-x
-v v @key{RET}} is a convenient way to get the latest version of a file from
-the repository.
-
address@hidden
address@hidden 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
address@hidden
-(@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs
-Features}).
address@hidden iftex
address@hidden
-(@pxref{Local Version Control}).
address@hidden ifnottex
-
address@hidden itemize
-
address@hidden Log Buffer
address@hidden Features of the Log Entry Buffer
-
- When you check in changes, @kbd{C-x v v} first reads a log entry. It
-pops up a buffer called @samp{*VC-Log*} for you to enter the log entry.
-
- Sometimes the @samp{*VC-Log*} buffer contains default text when you enter it,
-typically the last log message entered. If it does, mark and point
-are set around the entire contents of the buffer so that it is easy to
-kill the contents of the buffer with @kbd{C-w}.
-
address@hidden log-edit-insert-changelog
- If you work by writing entries in the @file{ChangeLog}
-(@pxref{Change Log}) and then commit the change under revision
-control, you can generate the Log Edit text from the ChangeLog using
address@hidden C-a} (@kbd{log-edit-insert-changelog}). This looks for
-entries for the file(s) concerned in the top entry in the ChangeLog
-and uses those paragraphs as the log text. This text is only inserted
-if the top entry was made under your user name on the current date.
address@hidden
address@hidden Logs and VC,,,emacs-xtra, Specialized Emacs Features},
address@hidden iftex
address@hidden
address@hidden Logs and VC},
address@hidden ifnottex
-for the opposite way of working---generating ChangeLog entries from
-the revision control log.
-
- In the @samp{*VC-Log*} buffer, @kbd{C-c C-f} (@kbd{M-x
-log-edit-show-files}) shows the list of files to be committed in case
-you need to check that. (This can be a list of more than one file if
-you use VC Dired mode or PCL-CVS.
address@hidden
address@hidden Dired Mode,,,emacs-xtra, Specialized Emacs Features},
address@hidden iftex
address@hidden
address@hidden Dired Mode},
address@hidden ifnottex
-and @ref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs
-Front-End to CVS}.)
-
- When you have finished editing the log message, type @kbd{C-c C-c} to
-exit the buffer and commit the change.
-
- To abort check-in, just @strong{don't} type @kbd{C-c C-c} in that
-buffer. You can switch buffers and do other editing. As long as you
-don't try to check in another file, the entry you were editing remains
-in the @samp{*VC-Log*} buffer, and you can go back to that buffer at any
-time to complete the check-in.
-
- If you change several source files for the same reason, it is often
-convenient to specify the same log entry for many of the files. To do
-this, use the history of previous log entries. The commands @kbd{M-n},
address@hidden, @kbd{M-s} and @kbd{M-r} for doing this work just like the
-minibuffer history commands (except that these versions are used outside
-the minibuffer).
-
address@hidden vc-log-mode-hook
- Each time you check in a file, the log entry buffer is put into VC Log
-mode, which involves running two hooks: @code{text-mode-hook} and
address@hidden @xref{Hooks}.
-
address@hidden Old Versions
address@hidden Examining And Comparing Old Versions
-
- One of the convenient features of version control is the ability
-to examine any version of a file, or compare two versions.
-
address@hidden @kbd
address@hidden C-x v ~ @var{version} @key{RET}
-Examine version @var{version} of the visited file, in a buffer of its
-own.
-
address@hidden C-x v =
-Compare the current buffer contents with the master version from which
-you started editing.
-
address@hidden C-u C-x v = @var{file} @key{RET} @var{oldvers} @key{RET}
@var{newvers} @key{RET}
-Compare the specified two versions of @var{file}.
-
address@hidden C-x v g
-Display the file with per-line version information and using colors.
address@hidden table
-
address@hidden vc-version-other-window
address@hidden C-x v ~
- To examine an old version in its entirety, visit the file and then type
address@hidden v ~ @var{version} @key{RET}} (@code{vc-version-other-window}).
-This puts the text of version @var{version} in a file named
address@hidden@address@hidden, and visits it in its own buffer
-in a separate window. (In RCS, you can also select an old version
-and create a branch from it. @xref{Branches}.)
-
address@hidden vc-diff
address@hidden C-x v =
- It is usually more convenient to compare two versions of the file,
-with the command @kbd{C-x v =} (@code{vc-diff}). Plain @kbd{C-x v =}
-compares the current buffer contents (saving them in the file if
-necessary) with the master version from which you started editing the
-file (this is not necessarily the latest version of the file).
address@hidden C-x v =}, with a numeric argument, reads a file name and two
-version numbers, then compares those versions of the specified file.
-Both forms display the output in a special buffer in another window.
-
- You can specify a checked-in version by its number; an empty input
-specifies the current contents of the work file (which may be different
-from all the checked-in versions). You can also specify a snapshot name
address@hidden
-(@pxref{Snapshots,,,emacs-xtra, Specialized Emacs Features})
address@hidden iftex
address@hidden
-(@pxref{Snapshots})
address@hidden ifnottex
-instead of one or both version numbers.
-
- If you supply a directory name instead of the name of a registered
-file, this command compares the two specified versions of all registered
-files in that directory and its subdirectories.
-
address@hidden vc-diff-switches
address@hidden vc-rcs-diff-switches
- @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
address@hidden (@pxref{Comparing Files}), it receives those
-specified by @code{vc-diff-switches}, plus those specified for the
-specific back end by @address@hidden For
-instance, when the version control back end is RCS, @code{diff} uses
-the options in @code{vc-rcs-diff-switches}. The
address@hidden@dots{}diff-switches} variables are @code{nil} by default.
-
- The buffer produced by @kbd{C-x v =} supports the commands of
-Compilation mode (@pxref{Compilation Mode}), such as @kbd{C-x `} and
address@hidden C-c}, in both the ``old'' and ``new'' text, and they always
-find the corresponding locations in the current work file. (Older
-versions are not, in general, present as files on your disk.)
-
address@hidden vc-annotate
address@hidden C-x v g
- For some back ends, you can display the file @dfn{annotated} with
-per-line version information and using colors to enhance the visual
-appearance, with the command @kbd{M-x vc-annotate}. It creates a new
-buffer (the ``annotate buffer'') displaying the file's text, with each
-part colored to show how old it is. Text colored red is new, blue means
-old, and intermediate colors indicate intermediate ages. By default,
-the color is scaled over the full range of ages, such that the oldest
-changes are blue, and the newest changes are red.
-
- 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 the time span in
-days the color range should cover.
-
- From the annotate buffer, these and other color scaling options are
-available from the @samp{VC-Annotate} menu. In this buffer, you can
-also use the following keys to browse the annotations of past revisions,
-view diffs, or view log entries:
-
address@hidden @kbd
address@hidden P
-Annotate the previous revision, that is to say, the revision before
-the one currently annotated. A numeric prefix argument is a repeat
-count, so @kbd{C-u 10 P} would take you back 10 revisions.
-
address@hidden N
-Annotate the next revision---the one after the revision currently
-annotated. A numeric prefix argument is a repeat count.
-
address@hidden J
-Annotate the revision indicated by the current line.
-
address@hidden A
-Annotate the revision before the one indicated by the current line.
-This is useful to see the state the file was in before the change on
-the current line was made.
-
address@hidden D
-Display the diff between the current line's revision and the previous
-revision. This is useful to see what the current line's revision
-actually changed in the file.
-
address@hidden L
-Show the log of the current line's revision. This is useful to see
-the author's description of the changes in the revision on the current
-line.
-
address@hidden W
-Annotate the workfile version--the one you are editing. If you used
address@hidden and @kbd{N} to browse to other revisions, use this key to
-return to your current version.
address@hidden table
-
address@hidden Secondary VC Commands
address@hidden The Secondary Commands of VC
-
- This section explains the secondary commands of VC; those that you might
-use once a day.
-
address@hidden
-* Registering:: Putting a file under version control.
-* VC Status:: Viewing the VC status of files.
-* VC Undo:: Canceling changes before or after check-in.
address@hidden
-* VC Dired Mode:: Listing files managed by version control.
-* VC Dired Commands:: Commands to use in a VC Dired buffer.
address@hidden ifnottex
address@hidden menu
-
address@hidden Registering
address@hidden Registering a File for Version Control
-
address@hidden C-x v i
address@hidden vc-register
- You can put any file under version control by simply visiting it, and
-then typing @address@hidden v i}} (@code{vc-register}).
-
address@hidden @kbd
address@hidden C-x v i
-Register the visited file for version control.
address@hidden table
-
- To register the file, Emacs must choose which version control system
-to use for it. If the file's directory already contains files
-registered in a version control system, Emacs uses that system. If
-there is more than one system in use for a directory, Emacs uses the
-one that appears first in @code{vc-handled-backends}
address@hidden
-(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
address@hidden iftex
address@hidden
-(@pxref{Customizing VC}).
address@hidden ifnottex
-On the other hand, if there are no files already registered, Emacs uses
-the first system from @code{vc-handled-backends} that could register
-the file (for example, you cannot register a file under CVS if its
-directory is not already part of a CVS tree); with the default value
-of @code{vc-handled-backends}, this means that Emacs uses RCS in this
-situation.
-
- If locking is in use, @kbd{C-x v i} leaves the file unlocked and
-read-only. Type @kbd{C-x v v} if you wish to start editing it. After
-registering a file with CVS, you must subsequently commit the initial
-version by typing @kbd{C-x v v}. Until you do that, the version
-appears as @samp{@@@@} in the mode line.
-
address@hidden vc-default-init-version
address@hidden 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
address@hidden, or you can give @kbd{C-x v i} a numeric
-argument; then it reads the initial version number for this particular
-file using the minibuffer.
-
address@hidden vc-initial-comment
- If @code{vc-initial-comment} is address@hidden, @kbd{C-x v i} reads an
-initial comment to describe the purpose of this source file. Reading
-the initial comment works like reading a log entry (@pxref{Log Buffer}).
-
address@hidden VC Status
address@hidden VC Status Commands
-
address@hidden @kbd
address@hidden C-x v l
-Display version control state and change history.
address@hidden table
-
address@hidden C-x v l
address@hidden vc-print-log
- To view the detailed version control status and history of a file,
-type @kbd{C-x v l} (@code{vc-print-log}). It displays the history of
-changes to the current file, including the text of the log entries. The
-output appears in a separate window. The point is centered at the
-revision of the file that is currently being visited.
-
- In the change log buffer, you can use the following keys to move
-between the logs of revisions and of files, to view past revisions, and
-to view diffs:
-
address@hidden @kbd
address@hidden p
-Move to the previous revision-item in the buffer. (Revision entries in the log
-buffer are usually in reverse-chronological order, so the previous
-revision-item usually corresponds to a newer revision.) A numeric
-prefix argument is a repeat count.
-
address@hidden n
-Move to the next revision-item (which most often corresponds to the
-previous revision of the file). A numeric prefix argument is a repeat
-count.
-
address@hidden P
-Move to the log of the previous file, when the logs of multiple files
-are in the log buffer
address@hidden
-(@pxref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}).
address@hidden iftex
address@hidden
-(@pxref{VC Dired Mode}).
address@hidden ifnottex
-Otherwise, just move to the beginning of the log. A numeric prefix
-argument is a repeat count, so @kbd{C-u 10 P} would move backward 10
-files.
-
address@hidden N
-Move to the log of the next file, when the logs of multiple files are
-in the log buffer
address@hidden
-(@pxref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}).
address@hidden iftex
address@hidden
-(@pxref{VC Dired Mode}).
address@hidden ifnottex
-It also takes a numeric prefix argument as a repeat count.
-
address@hidden f
-Visit the revision indicated at the current line, like typing @kbd{C-x
-v ~} and specifying this revision's number (@pxref{Old Versions}).
-
address@hidden d
-Display the diff (@pxref{Comparing Files}) between the revision
-indicated at the current line and the next earlier revision. This is
-useful to see what actually changed when the revision indicated on the
-current line was committed.
address@hidden table
-
address@hidden VC Undo
address@hidden Undoing Version Control Actions
-
address@hidden @kbd
address@hidden C-x v u
-Revert the buffer and the file to the version from which you started
-editing the file.
-
address@hidden C-x v c
-Remove the last-entered change from the master for the visited file.
-This undoes your last check-in.
address@hidden table
-
address@hidden C-x v u
address@hidden vc-revert-buffer
- If you want to discard your current set of changes and revert to the
-version from which you started editing the file, use @kbd{C-x v u}
-(@code{vc-revert-buffer}). This leaves the file unlocked; if locking
-is in use, you must first lock the file again before you change it
-again. @kbd{C-x v u} requires confirmation, unless it sees that you
-haven't made any changes with respect to the master version.
-
- @kbd{C-x v u} is also the command to unlock a file if you lock it and
-then decide not to change it.
-
address@hidden C-x v c
address@hidden vc-cancel-version
- To cancel a change that you already checked in, use @kbd{C-x v c}
-(@code{vc-cancel-version}). This command discards all record of the
-most recent checked-in version, but only if your work file corresponds
-to that version---you cannot use @kbd{C-x v c} to cancel a version
-that is not the latest on its branch. @kbd{C-x v c} also offers to
-revert your work file and buffer to the previous version (the one that
-precedes the version that is deleted).
-
- If you answer @kbd{no}, VC keeps your changes in the buffer, and locks
-the file. The no-revert option is useful when you have checked in a
-change and then discover a trivial error in it; you can cancel the
-erroneous check-in, fix the error, and check the file in again.
-
- When @kbd{C-x v c} does not revert the buffer, it unexpands all
-version control headers in the buffer instead
address@hidden
-(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}).
address@hidden iftex
address@hidden
-(@pxref{Version Headers}).
address@hidden ifnottex
-This is because the buffer no longer corresponds to any existing
-version. If you check it in again, the check-in process will expand
-the headers properly for the new version number.
-
- However, it is impossible to unexpand the RCS @address@hidden header
-automatically. If you use that header feature, you have to unexpand it
-by hand---by deleting the entry for the version that you just canceled.
-
- Be careful when invoking @kbd{C-x v c}, as it is easy to lose a lot of
-work with it. To help you be careful, this command always requires
-confirmation with @kbd{yes}. Note also that this command is disabled
-under CVS, because canceling versions is very dangerous and discouraged
-with CVS.
-
address@hidden
address@hidden vc1-xtra.texi needs extra level of lowering.
address@hidden
address@hidden vc1-xtra.texi
address@hidden
address@hidden ifnottex
-
address@hidden Branches
address@hidden Multiple Branches of a File
address@hidden branch (version control)
address@hidden trunk (version control)
-
- One use of version control is to maintain multiple ``current''
-versions of a file. For example, you might have different versions of a
-program in which you are gradually adding various unfinished new
-features. Each such independent line of development is called a
address@hidden VC allows you to create branches, switch between
-different branches, and merge changes from one branch to another.
-Please note, however, that branches are not supported for SCCS.
-
- A file's main line of development is usually called the @dfn{trunk}.
-The versions on the trunk are normally numbered 1.1, 1.2, 1.3, etc. At
-any such version, you can start an independent branch. A branch
-starting at version 1.2 would have version number 1.2.1.1, and consecutive
-versions on this branch would have numbers 1.2.1.2, 1.2.1.3, 1.2.1.4,
-and so on. If there is a second branch also starting at version 1.2, it
-would consist of versions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc.
-
address@hidden head version
- If you omit the final component of a version number, that is called a
address@hidden number}. It refers to the highest existing version on that
-branch---the @dfn{head version} of that branch. The branches in the
-example above have branch numbers 1.2.1 and 1.2.2.
-
address@hidden
-* Switching Branches:: How to get to another existing branch.
-* Creating Branches:: How to start a new branch.
-* Merging:: Transferring changes between branches.
-* Multi-User Branching:: Multiple users working at multiple branches
- in parallel.
address@hidden menu
-
address@hidden Switching Branches
address@hidden Switching between Branches
-
- To switch between branches, type @kbd{C-u C-x v v} and specify the
-version number you want to select. This version is then visited
address@hidden (write-protected), so you can examine it before locking
-it. Switching branches in this way is allowed only when the file is not
-locked.
-
- You can omit the minor version number, thus giving only the branch
-number; this takes you to the head version on the chosen branch. If you
-only type @key{RET}, Emacs goes to the highest version on the trunk.
-
- After you have switched to any branch (including the main branch), you
-stay on it for subsequent VC commands, until you explicitly select some
-other branch.
-
address@hidden Creating Branches
address@hidden Creating New Branches
-
- To create a new branch from a head version (one that is the latest in
-the branch that contains it), first select that version if necessary,
-lock it with @kbd{C-x v v}, and make whatever changes you want. Then,
-when you check in the changes, use @kbd{C-u C-x v v}. This lets you
-specify the version number for the new version. You should specify a
-suitable branch number for a branch starting at the current version.
-For example, if the current version is 2.5, the branch number should be
-2.5.1, 2.5.2, and so on, depending on the number of existing branches at
-that point.
-
- To create a new branch at an older version (one that is no longer the
-head of a branch), first select that version (@pxref{Switching
-Branches}), then lock it with @kbd{C-x v v}. You'll be asked to
-confirm, when you lock the old version, that you really mean to create a
-new branch---if you say no, you'll be offered a chance to lock the
-latest version instead.
-
- Then make your changes and type @kbd{C-x v v} again to check in a new
-version. This automatically creates a new branch starting from the
-selected version. You need not specially request a new branch, because
-that's the only way to add a new version at a point that is not the head
-of a branch.
-
- After the branch is created, you ``stay'' on it. That means that
-subsequent check-ins create new versions on that branch. To leave the
-branch, you must explicitly select a different version with @kbd{C-u C-x
-v v}. To transfer changes from one branch to another, use the merge
-command, described in the next section.
-
address@hidden Merging
address@hidden Merging Branches
-
address@hidden merging changes
- When you have finished the changes on a certain branch, you will
-often want to incorporate them into the file's main line of development
-(the trunk). This is not a trivial operation, because development might
-also have proceeded on the trunk, so that you must @dfn{merge} the
-changes into a file that has already been changed otherwise. VC allows
-you to do this (and other things) with the @code{vc-merge} command.
-
address@hidden @kbd
address@hidden C-x v m (vc-merge)
-Merge changes into the work file.
address@hidden table
-
address@hidden C-x v m
address@hidden vc-merge
- @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it
-into the current version of the work file. It firsts asks you in the
-minibuffer where the changes should come from. If you just type
address@hidden, Emacs merges any changes that were made on the same branch
-since you checked the file out (we call this @dfn{merging the news}).
-This is the common way to pick up recent changes from the repository,
-regardless of whether you have already changed the file yourself.
-
- You can also enter a branch number or a pair of version numbers in
-the minibuffer. Then @kbd{C-x v m} finds the changes from that
-branch, or the differences between the two versions you specified, and
-merges them into the current version of the current file.
-
- As an example, suppose that you have finished a certain feature on
-branch 1.3.1. In the meantime, development on the trunk has proceeded
-to version 1.5. To merge the changes from the branch to the trunk,
-first go to the head version of the trunk, by typing @kbd{C-u C-x v v
address@hidden Version 1.5 is now current. If locking is used for the file,
-type @kbd{C-x v v} to lock version 1.5 so that you can change it. Next,
-type @kbd{C-x v m 1.3.1 @key{RET}}. This takes the entire set of changes on
-branch 1.3.1 (relative to version 1.3, where the branch started, up to
-the last version on the branch) and merges it into the current version
-of the work file. You can now check in the changed file, thus creating
-version 1.6 containing the changes from the branch.
-
- It is possible to do further editing after merging the branch, before
-the next check-in. But it is usually wiser to check in the merged
-version, then lock it and make the further changes. This will keep
-a better record of the history of changes.
-
address@hidden conflicts
address@hidden resolving conflicts
- When you merge changes into a file that has itself been modified, the
-changes might overlap. We call this situation a @dfn{conflict}, and
-reconciling the conflicting changes is called @dfn{resolving a
-conflict}.
-
- Whenever conflicts occur during merging, VC detects them, tells you
-about them in the echo area, and asks whether you want help in merging.
-If you say yes, it starts an Ediff session (@pxref{Top,
-Ediff, Ediff, ediff, The Ediff Manual}).
-
- If you say no, the conflicting changes are both inserted into the
-file, surrounded by @dfn{conflict markers}. The example below shows how
-a conflict region looks; the file is called @samp{name} and the current
-master file version with user B's changes in it is 1.11.
-
address@hidden @w here is so CVS won't think this is a conflict.
address@hidden
address@hidden
address@hidden<}<<<<<< name
- @var{User A's version}
-=======
- @var{User B's version}
address@hidden>}>>>>>> 1.11
address@hidden group
address@hidden smallexample
-
address@hidden vc-resolve-conflicts
- Then you can resolve the conflicts by editing the file manually. Or
-you can type @code{M-x vc-resolve-conflicts} after visiting the file.
-This starts an Ediff session, as described above. Don't forget to
-check in the merged version afterwards.
-
address@hidden Multi-User Branching
address@hidden Multi-User Branching
-
- It is often useful for multiple developers to work simultaneously on
-different branches of a file. CVS allows this by default; for RCS, it
-is possible if you create multiple source directories. Each source
-directory should have a link named @file{RCS} which points to a common
-directory of RCS master files. Then each source directory can have its
-own choice of selected versions, but all share the same common RCS
-records.
-
- This technique works reliably and automatically, provided that the
-source files contain RCS version headers
address@hidden
-(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}).
address@hidden iftex
address@hidden
-(@pxref{Version Headers}).
address@hidden ifnottex
-The headers enable Emacs to be sure, at all times, which version
-number is present in the work file.
-
- If the files do not have version headers, you must instead tell Emacs
-explicitly in each session which branch you are working on. To do this,
-first find the file, then type @kbd{C-u C-x v v} and specify the correct
-branch number. This ensures that Emacs knows which branch it is using
-during this particular editing session.
-
address@hidden
address@hidden vc2-xtra.texi
address@hidden ifnottex
-
address@hidden Directories
address@hidden File Directories
-
address@hidden file directory
address@hidden directory listing
- The file system groups files into @dfn{directories}. A @dfn{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}.
-
address@hidden @kbd
address@hidden C-x C-d @var{dir-or-pattern} @key{RET}
-Display a brief directory listing (@code{list-directory}).
address@hidden C-u C-x C-d @var{dir-or-pattern} @key{RET}
-Display a verbose directory listing.
address@hidden M-x make-directory @key{RET} @var{dirname} @key{RET}
-Create a new directory named @var{dirname}.
address@hidden M-x delete-directory @key{RET} @var{dirname} @key{RET}
-Delete the directory named @var{dirname}. It must be empty,
-or you get an error.
address@hidden table
-
address@hidden list-directory
address@hidden C-x C-d
- The command to display a directory listing is @kbd{C-x C-d}
-(@code{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,
-
address@hidden
-C-x C-d /u2/emacs/etc @key{RET}
address@hidden example
-
address@hidden
-lists all the files in directory @file{/u2/emacs/etc}. Here is an
-example of specifying a file name pattern:
-
address@hidden
-C-x C-d /u2/emacs/src/*.c @key{RET}
address@hidden example
-
- 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
address@hidden -l}).
-
address@hidden list-directory-brief-switches
address@hidden list-directory-verbose-switches
- The text of a directory listing is mostly obtained by running
address@hidden in an inferior process. Two Emacs variables control the
-switches passed to @code{ls}: @code{list-directory-brief-switches} is
-a string giving the switches to use in brief listings (@code{"-CF"} by
-default), and @code{list-directory-verbose-switches} is a string
-giving the switches to use in a verbose listing (@code{"-l"} by
-default).
-
address@hidden directory-free-space-program
address@hidden directory-free-space-args
- 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
address@hidden with arguments
address@hidden
-
address@hidden Comparing Files
address@hidden Comparing Files
address@hidden comparing files
-
address@hidden diff
address@hidden diff-switches
- The command @kbd{M-x diff} compares two files, displaying the
-differences in an Emacs buffer named @samp{*diff*}. It works by
-running the @code{diff} program, using options taken from the variable
address@hidden The value of @code{diff-switches} should be a
-string; the default is @code{"-c"} to specify a context diff.
address@hidden,, Diff, diff, Comparing and Merging Files}, for more
-information about @command{diff} output formats.
-
address@hidden diff-backup
- The command @kbd{M-x diff-backup} compares a specified file with its most
-recent backup. If you specify the name of a backup file,
address@hidden compares it with the source file that it is a backup
-of.
-
address@hidden compare-windows
- The command @kbd{M-x compare-windows} compares the text in the
-current window with that in the next window. (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, @kbd{M-x compare-windows} tries heuristically to
-advance up to matching text in the two windows, and then exits. So if
-you use @kbd{M-x compare-windows} repeatedly, each time it either
-skips one matching range or finds the start of another.
-
address@hidden compare-ignore-case
address@hidden compare-ignore-whitespace
- With a numeric argument, @code{compare-windows} ignores changes in
-whitespace. If the variable @code{compare-ignore-case} is
address@hidden, the comparison ignores differences in case as well.
-If the variable @code{compare-ignore-whitespace} is address@hidden,
address@hidden normally ignores changes in whitespace, and a
-prefix argument turns that off.
-
address@hidden Smerge mode
address@hidden smerge-mode
address@hidden failed merges
address@hidden merges, failed
address@hidden comparing 3 files (@code{diff3})
- 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.
-
address@hidden
address@hidden,,, emacs-xtra, Specialized Emacs Features},
address@hidden iftex
address@hidden
address@hidden,
address@hidden ifnottex
-for the Emerge facility, which provides a powerful interface for
-merging files.
-
address@hidden Diff Mode
address@hidden Diff Mode
address@hidden Diff mode
address@hidden diff-mode
address@hidden patches, editing
-
- Diff mode is used for the output of @kbd{M-x diff}; it is also
-useful for editing patches and comparisons produced by the
address@hidden program. To select Diff mode manually, type @kbd{M-x
-diff-mode}.
-
- One general feature of Diff mode is that manual edits to the patch
-automatically correct line numbers, including those in the hunk
-header, so that you can actually apply the edited patch. Diff mode
-treats each hunk location as an ``error message,'' so that you can use
-commands such as @kbd{C-x '} to visit the corresponding source
-locations. It also provides the following commands to navigate,
-manipulate and apply parts of patches:
-
address@hidden @kbd
address@hidden M-n
-Move to the next hunk-start (@code{diff-hunk-next}).
-
address@hidden M-p
-Move to the previous hunk-start (@code{diff-hunk-prev}).
-
address@hidden address@hidden
-Move to the next file-start, in a multi-file patch
-(@code{diff-file-next}).
-
address@hidden address@hidden
-Move to the previous file-start, in a multi-file patch
-(@code{diff-file-prev}).
-
address@hidden M-k
-Kill the hunk at point (@code{diff-hunk-kill}).
-
address@hidden M-K
-In a multi-file patch, kill the current file part.
-(@code{diff-file-kill}).
-
address@hidden C-c C-a
-Apply this hunk to its target file (@code{diff-apply-hunk}). With a
-prefix argument of @kbd{C-u}, revert this hunk.
-
address@hidden C-c C-c
-Go to the source corresponding to this hunk (@code{diff-goto-source}).
-
address@hidden C-c C-e
-Start an Ediff session with the patch (@code{diff-ediff-patch}).
address@hidden, Ediff, Ediff, ediff, The Ediff Manual}.
-
address@hidden C-c C-n
-Restrict the view to the current hunk (@code{diff-restrict-view}).
address@hidden With a prefix argument of @kbd{C-u}, restrict the
-view to the current patch of a multiple file patch. To widen again,
-use @kbd{C-x n w}.
-
address@hidden C-c C-r
-Reverse the direction of comparison for the entire buffer
-(@code{diff-reverse-direction}).
-
address@hidden C-c C-s
-Split the hunk at point (@code{diff-split-hunk}). This is for
-manually editing patches, and only works with the unified diff format.
-
address@hidden C-c C-u
-Convert the entire buffer to unified format
-(@code{diff-context->unified}). With a prefix argument, convert
-unified format to context format. In Transient Mark mode, when the
-mark is active, this command operates only on the region.
-
address@hidden C-c C-w
-Refine the current hunk so that it disregards changes in whitespace
-(@code{diff-refine-hunk}).
address@hidden table
-
- @kbd{C-x 4 a} in Diff mode operates on behalf of the target file,
-but gets the function name from the patch itself. @xref{Change Log}.
-This is useful for making log entries for functions that are deleted
-by the patch.
-
address@hidden Misc File Ops
address@hidden 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.
-
address@hidden view-file
address@hidden viewing
address@hidden View mode
address@hidden mode, View
- @kbd{M-x view-file} allows you to scan or read a file by sequential
-screenfuls. It reads a file name argument using the minibuffer. After
-reading the file into an Emacs buffer, @code{view-file} displays the
-beginning. You can then type @key{SPC} to scroll forward one windowful,
-or @key{DEL} to scroll backward. Various other commands are provided
-for moving around in the file, but none for changing it; type @kbd{?}
-while viewing for a list of them. They are mostly the same as normal
-Emacs cursor motion commands. To exit from viewing, type @kbd{q}.
-The commands for viewing are defined by a special minor mode called View
-mode.
-
- A related command, @kbd{M-x view-buffer}, views a buffer already present
-in Emacs. @xref{Misc Buffer}.
-
address@hidden C-x i
address@hidden insert-file
- @kbd{M-x insert-file} (also @kbd{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 and the mark after them.
-
address@hidden insert-file-literally
- @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file},
-except the file is inserted ``literally'': it is treated as a sequence
-of @acronym{ASCII} characters with no special encoding or conversion,
-similar to the @kbd{M-x find-file-literally} command
-(@pxref{Visiting}).
-
address@hidden write-region
- @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it
-copies the contents of the region into the specified file. @kbd{M-x
-append-to-file} adds the text of the region to the end of the
-specified file. @xref{Accumulating Text}. The variable
address@hidden applies to these commands, as well
-as saving files; see @ref{Customize Save}.
-
address@hidden delete-file
address@hidden deletion (of files)
- @kbd{M-x delete-file} deletes the specified file, like the @code{rm}
-command in the shell. If you are deleting many files in one directory, it
-may be more convenient to use Dired (@pxref{Dired}).
-
address@hidden rename-file
- @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using
-the minibuffer, then renames file @var{old} as @var{new}. If the file name
address@hidden already exists, you must confirm with @kbd{yes} or renaming is
not
-done; this is because renaming causes the old meaning of the name @var{new}
-to be lost. If @var{old} and @var{new} are on different file systems, the
-file @var{old} is copied and deleted.
-
- If the argument @var{new} is just a directory name, the real new
-name is in that directory, with the same non-directory component as
address@hidden For example, @kbd{M-x rename-file RET ~/foo RET /tmp RET}
-renames @file{~/foo} to @file{/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.
-
address@hidden add-name-to-file
address@hidden hard links (creation)
- The similar command @kbd{M-x add-name-to-file} is used to add 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.
-
address@hidden copy-file
address@hidden copying files
- @kbd{M-x copy-file} reads the file @var{old} and writes a new file
-named @var{new} with the same contents.
-
address@hidden make-symbolic-link
address@hidden symbolic links (creation)
- @kbd{M-x make-symbolic-link} reads two file names @var{target} and
address@hidden, then creates a symbolic link named @var{linkname},
-which points at @var{target}. The effect is that future attempts to
-open file @var{linkname} will refer to whatever file is named
address@hidden at the time the opening is done, or will get an error if
-the name @var{target} is nonexistent at that time. This command does
-not expand the argument @var{target}, so that it allows you to specify
-a relative name as the target of the link.
-
- Not all systems support symbolic links; on systems that don't
-support them, this command is not defined.
-
address@hidden Compressed Files
address@hidden Accessing Compressed Files
address@hidden compression
address@hidden uncompression
address@hidden Auto Compression mode
address@hidden mode, Auto Compression
address@hidden gzip
-
- 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 @samp{.gz} indicate a file compressed with
address@hidden 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.
-
address@hidden auto-compression-mode
address@hidden auto-compression-mode
- To disable this feature, type the command @kbd{M-x
-auto-compression-mode}. You can disable it permanently by
-customizing the variable @code{auto-compression-mode}.
-
address@hidden File Archives
address@hidden File Archives
address@hidden mode, tar
address@hidden Tar mode
address@hidden file archives
-
- 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 Auto Compression mode is enabled (@pxref{Compressed Files}), then
-Tar mode is used also for compressed archives---files with extensions
address@hidden, @code{.tar.Z} and @code{.tar.gz}.
-
- The keys @kbd{e}, @kbd{f} and @key{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.
address@hidden extracts a file into a buffer in View mode. @kbd{o} extracts
-the file and displays it in another window, so you could edit the file
-and operate on the archive simultaneously. @kbd{d} marks a file for
-deletion when you later use @kbd{x}, and @kbd{u} unmarks a file, as in
-Dired. @kbd{C} copies a file from the archive to disk and @kbd{R}
-renames a file within the archive. @kbd{g} reverts the buffer from
-the archive on disk.
-
- The keys @kbd{M}, @kbd{G}, and @kbd{O} change the file's permission
-bits, group, and owner, respectively.
-
- If your display supports colors and the mouse, moving the mouse
-pointer across a file name highlights that file name, indicating that
-you can click on it. Clicking @kbd{Mouse-2} on the highlighted file
-name extracts the file into a buffer and displays that buffer.
-
- 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 @code{tar} program to use Tar mode---Emacs reads
-the archives directly. However, accessing compressed archives
-requires the appropriate uncompression program.
-
address@hidden Archive mode
address@hidden mode, archive
address@hidden @code{arc}
address@hidden @code{jar}
address@hidden @code{zip}
address@hidden @code{lzh}
address@hidden @code{zoo}
address@hidden arc
address@hidden jar
address@hidden zip
address@hidden lzh
address@hidden zoo
address@hidden Java class archives
address@hidden unzip archives
- A separate but similar Archive mode is used for archives produced by
-the programs @code{arc}, @code{jar}, @code{lzh}, @code{zip}, and
address@hidden, which have extensions corresponding to the program names.
-Archive mode also works for those @code{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 @kbd{m} key which marks a file for subsequent
-operations, and @address@hidden which unmarks all the marked 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 look at the archive table of contents, only to
-extract or manipulate the subfiles in the archive.
-
address@hidden Remote Files
address@hidden Remote Files
-
address@hidden Tramp
address@hidden FTP
address@hidden remote file access
- You can refer to files on other machines using a special file name
-syntax:
-
address@hidden
address@hidden
-/@var{host}:@var{filename}
-/@var{user}@@@var{host}:@var{filename}
-/@var{user}@@@address@hidden:@var{filename}
-/@var{method}:@var{user}@@@var{host}:@var{filename}
-/@var{method}:@var{user}@@@address@hidden:@var{filename}
address@hidden group
address@hidden example
-
address@hidden
-To carry out this request, Emacs uses either the FTP program or a
-remote-login program such as @command{ssh}, @command{rlogin}, or
address@hidden You can always specify in the file name which
-method to use---for example,
address@hidden/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP, whereas
address@hidden/ssh:@var{user}@@@var{host}:@var{filename}} uses @command{ssh}.
-When you don't specify a method in the file name, Emacs chooses
-the method as follows:
-
address@hidden
address@hidden
-If the host name starts with @samp{ftp.} (with dot), then Emacs uses
-FTP.
address@hidden
-If the user name is @samp{ftp} or @samp{anonymous}, then Emacs uses
-FTP.
address@hidden
-Otherwise, Emacs uses @command{ssh}.
address@hidden enumerate
-
address@hidden
-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.
address@hidden, The Tramp Manual,, tramp, The Tramp Manual}.
-
-When the Ange-FTP package is used, Emacs logs in through FTP using your
-user name or the name @var{user}. It may ask you for a password from
-time to time; this is used for logging in on @var{host}. The form using
address@hidden allows you to access servers running on a non-default TCP
-port.
-
address@hidden backups for remote files
address@hidden ange-ftp-make-backup-files
- If you want to disable backups for remote files, set the variable
address@hidden 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}.
-
address@hidden ange-ftp
address@hidden ange-ftp-default-user
address@hidden user name for remote file access
- Normally, if you do not specify a user name in a remote file name,
-that means to use your own user name. But if you set the variable
address@hidden to a string, that string is used instead.
-
address@hidden anonymous FTP
address@hidden ange-ftp-generate-anonymous-password
- To visit files accessible by anonymous FTP, you use special user
-names @samp{anonymous} or @samp{ftp}. Passwords for these user names
-are handled specially. The variable
address@hidden controls what happens: if
-the value of this variable is a string, then that string is used as
-the password; if address@hidden (the default), then the value of
address@hidden is used; if @code{nil}, then Emacs prompts
-you for a password as usual.
-
address@hidden firewall, and accessing remote files
address@hidden gateway, and remote file access with @code{ange-ftp}
address@hidden ange-ftp-smart-gateway
address@hidden ange-ftp-gateway-host
- Sometimes you may be unable to access files on a remote machine
-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
address@hidden 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}}.
-
address@hidden file-name-handler-alist
address@hidden disabling remote files
- You can entirely turn off the FTP file name feature by removing the
-entries @code{ange-ftp-completion-hook-function} and
address@hidden from the variable
address@hidden You can turn off the feature in
-individual cases by quoting the file name with @samp{/:} (@pxref{Quoted
-File Names}).
-
address@hidden Quoted File Names
address@hidden Quoted File Names
-
address@hidden quoting file names
address@hidden file names, quote special characters
- You can @dfn{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 @samp{/:} 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 @file{/foo:} and a file named @file{bar} in it, you
-can refer to that file in Emacs as @samp{/:/foo:/bar}.
-
- @samp{/:} can also prevent @samp{~} from being treated as a special
-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}.
-
- 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
address@hidden/:} 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
address@hidden/tmp/foo*bar}.
-
- Another method of getting the same result is to enter
address@hidden/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
address@hidden/tmp/foo*bar}.
-
address@hidden File Name Cache
address@hidden File Name Cache
-
address@hidden file name caching
address@hidden cache of file names
address@hidden find
address@hidden address@hidden
address@hidden 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, @address@hidden
-(@code{file-cache-minibuffer-complete}) completes it using the file
-name cache. If you repeat @address@hidden, that cycles through the
-possible completions of what you had originally typed. (However, note
-that the @address@hidden 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:
-
address@hidden file-cache-add-directory
address@hidden @kbd
address@hidden M-x file-cache-add-directory @key{RET} @var{directory} @key{RET}
-Add each file name in @var{directory} to the file name cache.
address@hidden 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.
address@hidden 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.
address@hidden 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.
address@hidden M-x file-cache-clear-cache @key{RET}
-Clear the cache; that is, remove all file names from it.
address@hidden table
-
- 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 @code{file-cache-display} command.
-
address@hidden File Conveniences
address@hidden 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.
-
address@hidden recentf-mode
address@hidden recentf-mode
address@hidden recentf-save-list
address@hidden recentf-edit-list
- If you enable Recentf mode, with @kbd{M-x recentf-mode}, the
address@hidden menu includes a submenu containing a list of recently
-opened files. @kbd{M-x recentf-save-list} saves the current
address@hidden to a file, and @kbd{M-x recentf-edit-list}
-edits it.
-
- 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
address@hidden, which can be used with @code{ffap}.
address@hidden Options}.
-
address@hidden image-mode
address@hidden image-toggle-display
address@hidden images, viewing
- Visiting image files automatically selects Image mode. This major
-mode allows you to toggle between displaying the file as an image in
-the Emacs buffer, and displaying its underlying text representation,
-using the command @kbd{C-c C-c} (@code{image-toggle-display}). This
-works only when Emacs can display the specific image type. If the
-displayed image is wider or taller than the frame, the usual point
-motion keys (@kbd{C-f}, @kbd{C-p}, and so forth) cause different parts
-of the image to be displayed.
-
address@hidden thumbs-mode
address@hidden mode, thumbs
- See also the Image-Dired package (@pxref{Image-Dired}) for viewing
-images as thumbnails.
-
address@hidden Filesets
address@hidden Filesets
address@hidden filesets
-
address@hidden filesets-init
- If you regularly edit a certain group of files, you can define them
-as a @dfn{fileset}. This lets you perform certain operations, such as
-visiting, @code{query-replace}, and shell commands on all the files
-at once. To make use of filesets, you must first add the expression
address@hidden(filesets-init)} to your @file{.emacs} file (@pxref{Init File}).
-This adds a @samp{Filesets} menu to the menu bar.
-
address@hidden filesets-add-buffer
address@hidden filesets-remove-buffer
- The simplest way to define a fileset is by adding files to it one
-at a time. To add a file to fileset @var{name}, visit the file and
-type @kbd{M-x filesets-add-buffer @kbd{RET} @var{name} @kbd{RET}}. If
-there is no fileset @var{name}, this creates a new one, which
-initially creates only the current file. The command @kbd{M-x
-filesets-remove-buffer} removes the current file from a fileset.
-
- You can also edit the list of filesets directly, with @kbd{M-x
-filesets-edit} (or by choosing @samp{Edit Filesets} from the
address@hidden menu). The editing is performed in a Customize buffer
-(@pxref{Easy Customization}). Filesets need not be a simple list of
-files---you can also define filesets using regular expression matching
-file names. Some examples of these more complicated filesets are
-shown in the Customize buffer. Remember to select @samp{Save for
-future sessions} if you want to use the same filesets in future Emacs
-sessions.
-
- You can use the command @kbd{M-x filesets-open} to visit all the
-files in a fileset, and @kbd{M-x filesets-close} to close them. Use
address@hidden filesets-run-cmd} to run a shell command on all the files in
-a fileset. These commands are also available from the @samp{Filesets}
-menu, where each existing fileset is represented by a submenu.
-
address@hidden
- arch-tag: 768d32cb-e15a-4cc1-b7bf-62c00ee12250
address@hidden ignore