@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2011
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012
@c Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Maintaining, Abbrevs, Building, Top
@chapter Maintaining Large Programs
This chapter describes Emacs features for maintaining large
-programs.
+programs. If you are maintaining a large Lisp program, then in
+addition to the features described here, you may find
+the @file{ERT} (``Emacs Lisp Regression Testing'') library useful
+(@pxref{Top,,ERT,ert, Emacs Lisp Regression Testing}).
@menu
* Version Control:: Using version control systems.
one revision for each changed file.
@table @kbd
-@itemx C-x v v
+@item C-x v v
Perform the next appropriate version control operation on the current
VC fileset.
@end table
@item
If every work file in the VC fileset has been modified, commit the
-changes. To do this, Emacs pops up a @samp{*vc-log*} buffer; type the
+changes. To do this, Emacs pops up a @file{*vc-log*} buffer; type the
desired log entry for the new revision, followed by @kbd{C-c C-c} to
commit. @xref{Log Buffer}.
@item
If each file is locked by you and contains changes, commit the
-changes. To do this, Emacs pops up a @samp{*vc-log*} buffer; type the
+changes. To do this, Emacs pops up a @file{*vc-log*} buffer; type the
desired log entry for the new revision, followed by @kbd{C-c C-c} to
commit (@pxref{Log Buffer}).
@cindex C-c C-c @r{(Log Edit mode)}
@findex log-edit-done
When you tell VC to commit a change, it pops up a buffer named
-@samp{*vc-log*}. In this buffer, you should write a @dfn{log entry}
+@file{*vc-log*}. In this buffer, you should write a @dfn{log entry}
describing the changes you have made (@pxref{Why Version Control?}).
After you are done, type @kbd{C-c C-c} (@code{log-edit-done}) to exit
the buffer and commit the change, together with your log entry.
@cindex Log Edit mode
@cindex mode, Log Edit
@vindex vc-log-mode-hook
- The major mode for the @samp{*vc-log*} buffer is Log Edit mode, a
+ The major mode for the @file{*vc-log*} buffer is Log Edit mode, a
variant of Text mode (@pxref{Text Mode}). On entering Log Edit mode,
Emacs runs the hooks @code{text-mode-hook} and @code{vc-log-mode-hook}
(@pxref{Hooks}).
- In the @samp{*vc-log*} buffer, you can write one or more @dfn{header
+ In the @file{*vc-log*} buffer, you can write one or more @dfn{header
lines}, specifying additional information to be supplied to the
version control system. Each header line must occupy a single line at
the top of the buffer; the first line that is not a header line is
@findex log-edit-show-files
@kindex C-c C-d @r{(Log Edit mode)}
@findex log-edit-show-diff
- While in the @samp{*vc-log*} buffer, the ``current VC fileset'' is
+ While in the @file{*vc-log*} buffer, the ``current VC fileset'' is
considered to be the fileset that will be committed if you type
@w{@kbd{C-c C-c}}. To view a list of the files in the VC fileset,
type @w{@kbd{C-c C-f}} (@code{log-edit-show-files}). To view a diff
If the VC fileset includes one or more @file{ChangeLog} files
(@pxref{Change Log}), type @kbd{C-c C-a}
(@code{log-edit-insert-changelog}) to pull the relevant entries into
-the @samp{*vc-log*} buffer. If the topmost item in each
+the @file{*vc-log*} buffer. If the topmost item in each
@file{ChangeLog} was made under your user name on the current date,
this command searches that item for entries matching the file(s) to be
committed, and inserts them.
To abort a commit, 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 make another commit, the entry you were editing remains
-in the @samp{*vc-log*} buffer, and you can go back to that buffer at
+in the @file{*vc-log*} buffer, and you can go back to that buffer at
any time to complete the commit.
@kindex M-n @r{(Log Edit mode)}
On a locking-based version control system (@pxref{VCS Merging}),
registering a file leaves it unlocked and read-only. Type @kbd{C-x v
-v} if you wish to start editing it.
+v} to start editing it.
@node Old Revisions
@subsection Examining And Comparing Old Revisions
@ifnottex
@item M-x vc-ediff
-Like @kbd{C-x v =}, but using Ediff. @xref{Top, Ediff, ediff, The
+Like @kbd{C-x v =}, but using Ediff. @xref{Top,, Ediff, ediff, The
Ediff Manual}.
@end ifnottex
@ifnottex
@findex vc-ediff
@kbd{M-x vc-ediff} works like @kbd{C-x v =}, except that it uses an
-Ediff session. @xref{Top, Ediff, ediff, The Ediff Manual}.
+Ediff session. @xref{Top,, Ediff, ediff, The Ediff Manual}.
@end ifnottex
@findex vc-root-diff
(@code{vc-print-root-log}).
@item C-x v I
-Display the changes that will be received with a pull operation
+Display the changes that a pull operation will retrieve
(@code{vc-log-incoming}).
@item C-x v O
@kindex C-x v l
@findex vc-print-log
- The command @kbd{C-x v l} (@code{vc-print-log}) displays a buffer
-named @samp{*vc-change-log*}, showing the history of changes made to
-the current file, including who made the changes, the dates, and the
-log entry for each change (these are the same log entries you would
-enter via the @samp{*vc-log*} buffer; @pxref{Log Buffer}). Point is
+ @kbd{C-x v l} (@code{vc-print-log}) displays a buffer named
+@file{*vc-change-log*}, showing the history of changes made to the
+current file, including who made the changes, the dates, and the log
+entry for each change (these are the same log entries you would enter
+via the @file{*vc-log*} buffer; @pxref{Log Buffer}). Point is
centered at the revision of the file currently being visited. With a
prefix argument, the command prompts for the revision to center on,
and the maximum number of revisions to display.
@findex vc-print-root-log
@findex log-view-toggle-entry-display
@kbd{C-x v L} (@code{vc-print-root-log}) displays a
-@samp{*vc-change-log*} buffer showing the history of the entire
+@file{*vc-change-log*} buffer showing the history of the entire
version-controlled directory tree (RCS, SCCS, and CVS do not support
this feature). With a prefix argument, the command prompts for the
maximum number of revisions to display.
The @kbd{C-x v L} history is shown in a compact form, usually
showing only the first line of each log entry. However, you can type
@key{RET} (@code{log-view-toggle-entry-display}) in the
-@samp{*vc-change-log*} buffer to reveal the entire log entry for the
+@file{*vc-change-log*} buffer to reveal the entire log entry for the
revision at point. A second @key{RET} hides it again.
On a decentralized version control system, the @kbd{C-x v I}
another repository, the next time you run the ``push'' command; with a
prefix argument, it prompts for a specific destination repository.
- In the @samp{*vc-change-log*} buffer, you can use the following keys
+ In the @file{*vc-change-log*} buffer, you can use the following keys
to move between the logs of revisions and of files, and to examine and
compare past revisions (@pxref{Old Revisions}):
@vindex vc-log-show-limit
Because fetching many log entries can be slow, the
-@samp{*vc-change-log*} buffer displays no more than 2000 revisions by
+@file{*vc-change-log*} buffer displays no more than 2000 revisions by
default. The variable @code{vc-log-show-limit} specifies this limit;
if you set the value to zero, that removes the limit. You can also
increase the number of revisions shown in an existing
-@samp{*vc-change-log*} buffer by clicking on the @samp{Show 2X
+@file{*vc-change-log*} buffer by clicking on the @samp{Show 2X
entries} or @samp{Show unlimited entries} buttons at the end of the
buffer. However, RCS, SCCS, and CVS do not support this feature.
To use the VC Directory buffer, type @kbd{C-x v d} (@code{vc-dir}).
This reads a directory name using the minibuffer, and switches to a VC
Directory buffer for that directory. By default, the buffer is named
-@samp{*vc-dir*}. Its contents are described
+@file{*vc-dir*}. Its contents are described
@iftex
below.
@end iftex
(@code{vc-dir-mark-all-files}). With a prefix argument, mark all
listed files and directories.
+@kindex q @r{(VC Directory)}
+@findex quit-window
+@item q
+Bury the VC Directory buffer, and delete its window if the window was
+created just for that buffer.
+
@item u
Unmark the file or directory on the current line. If the region is
active, unmark all the files in the region (@code{vc-dir-unmark}).
@subsubsection Pulling Changes into a Branch
@table @kbd
-@itemx C-x v +
+@item C-x v +
On a decentralized version control system, update the current branch
by ``pulling in'' changes from another location.
@cindex merging changes
@table @kbd
-@itemx C-x v m
+@item C-x v m
On a decentralized version control system, merge changes from another
branch into the current one.
@code{bidule}.
@item
-In assembler code, labels appearing at the beginning of a line,
+In assembler code, labels appearing at the start of a line,
followed by a colon, are tags.
@item