@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2013 Free Software
+@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Maintaining, Abbrevs, Building, Top
+@node Maintaining
@chapter Maintaining Large Programs
This chapter describes Emacs features for maintaining large
time of each version, who made it, and a description of what was
changed.
- The Emacs version control interface is called @dfn{VC}. VC commands
+ The Emacs version control interface is called @dfn{VC}@. VC commands
work with several different version control systems; currently, it
supports GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS,
SCCS/CSSC, and Subversion. Of these, the GNU project distributes CVS,
control operations.
Some uncommon or intricate version control operations, such as
-altering repository settings, are not supported in VC. You should
-perform such tasks outside Emacs, e.g.@: via the command line.
+altering repository settings, are not supported in VC@. You should
+perform such tasks outside Emacs, e.g., via the command line.
This section provides a general overview of version control, and
describes the version control systems that VC supports. You can skip
@item
SCCS was the first version control system ever built, and was long ago
superseded by more advanced ones. VC compensates for certain features
-missing in SCCS (e.g.@: tag names for releases) by implementing them
+missing in SCCS (e.g., tag names for releases) by implementing them
itself. Other VC features, such as multiple branches, are simply
unavailable. Since SCCS is non-free, we recommend avoiding it.
@cindex CSSC
@item
-CSSC is a free replacement for SCCS. You should use CSSC only if, for
+CSSC is a free replacement for SCCS@. You should use CSSC only if, for
some reason, you cannot use a more recent and better-designed version
control system.
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
@node VC With A Merging VCS
@subsubsection Basic Version Control with Merging
- On a merging-based version control system (i.e.@: most modern ones;
+ On a merging-based version control system (i.e., most modern ones;
@pxref{VCS Merging}), @kbd{C-x v v} does the following:
@itemize @bullet
@item
If none of the files in the VC fileset are registered with a version
-control system, register the VC fileset, i.e.@: place it under version
+control system, register the VC fileset, i.e., place it under version
control. @xref{Registering}. If Emacs cannot find a system to
register under, it prompts for a repository type, creates a new
repository, and registers the VC fileset with it.
@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}).
Otherwise, if using CVS or RCS, you can specify a revision ID.
If the fileset is modified (or locked), this makes Emacs commit with
-that revision ID. You can create a new branch by supplying an
+that revision ID@. You can create a new branch by supplying an
appropriate revision ID (@pxref{Branches}).
If the fileset is unmodified (and unlocked), this checks the specified
revision into the working tree. You can also specify a revision on
another branch by giving its revision or branch ID (@pxref{Switching
-Branches}). An empty argument (i.e.@: @kbd{C-u C-x v v @key{RET}})
+Branches}). An empty argument (i.e., @kbd{C-u C-x v v @key{RET}})
checks out the latest (``head'') revision on the current branch.
This signals an error on a decentralized version control system.
@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
prompts for two revision IDs (@pxref{VCS Concepts}), and displays a
diff between those versions of the fileset. This will not work
reliably for multi-file VC filesets, if the version control system is
-file-based rather than changeset-based (e.g.@: CVS), since then
+file-based rather than changeset-based (e.g., CVS), since then
revision IDs for different files would not be related in any
meaningful way.
@findex vc-root-diff
@kindex C-x v D
@kbd{C-x v D} (@code{vc-root-diff}) is similar to @kbd{C-x v =}, but
-it displays the changes in the entire current working tree (i.e.@: the
+it displays the changes in the entire current working tree (i.e., the
working tree containing the current VC fileset). If you invoke this
command from a Dired buffer, it applies to the working tree containing
the directory.
@code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, and
@code{diff-switches} (@pxref{Comparing Files}), in that order. Here,
@var{backend} stands for the relevant version control system,
-e.g.@: @code{bzr} for Bazaar. Since @code{nil} means to check the
+e.g., @code{bzr} for Bazaar. Since @code{nil} means to check the
next variable in the sequence, either of the first two may use the
value @code{t} to mean no switches at all. Most of the
@code{vc-@var{backend}-diff-switches} variables default to @code{nil},
@table @kbd
@item p
-Annotate the previous revision, i.e.@: the revision before the one
+Annotate the previous revision, i.e., 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.
@item n
-Annotate the next revision, i.e.@: the revision after the one
+Annotate the next revision, i.e., the revision after the one
currently annotated. A numeric prefix argument is a repeat count.
@item j
(@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}):
revision.
@item @key{RET}
-In a compact-style log buffer (e.g.@: the one created by @kbd{C-x v
+In a compact-style log buffer (e.g., the one created by @kbd{C-x v
L}), toggle between showing and hiding the full log entry for the
revision at point.
@end table
@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
@pindex cvs
@cindex CVS directory mode
In addition to the VC Directory buffer, Emacs has a similar facility
-called PCL-CVS which is specialized for CVS. @xref{Top, , About
-PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs Front-End to CVS}.
+called PCL-CVS which is specialized for CVS@. @xref{Top, , About
+PCL-CVS, pcl-cvs, PCL-CVS---The Emacs Front-End to CVS}.
@end ifnottex
@menu
and their version control statuses. It lists files in the current
directory (the one specified when you called @kbd{C-x v d}) and its
subdirectories, but only those with a ``noteworthy'' status. Files
-that are up-to-date (i.e.@: the same as in the repository) are
+that are up-to-date (i.e., the same as in the repository) are
omitted. If all the files in a subdirectory are up-to-date, the
subdirectory is not listed either. As an exception, if a file has
become up-to-date as a direct result of a VC command, it is listed.
@code{vc-cvs-stay-local} (for CVS) to @code{nil} (@pxref{CVS
Options}), then Emacs avoids contacting a remote repository when
generating the VC Directory buffer (it will still contact it when
-necessary, e.g.@: when doing a commit). This may be desirable if you
+necessary, e.g., when doing a commit). This may be desirable if you
are working offline or the network is slow.
@end ifnottex
(@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.
+Quit the VC Directory buffer, and bury it (@code{quit-window}).
@item u
Unmark the file or directory on the current line. If the region is
@item x
Hide files with @samp{up-to-date} status
(@code{vc-dir-hide-up-to-date}).
-
-@item q
-Quit the VC Directory buffer, and bury it (@code{quit-window}).
@end table
@findex vc-dir-mark
branch created from revision 1.2 has revision IDs 1.2.2.1, 1.2.2.2,
@dots{}, and so forth. You can also specify the @dfn{branch ID},
which is a branch revision ID omitting its final component
-(e.g.@: 1.2.1), to switch to the latest revision on that branch.
+(e.g., 1.2.1), to switch to the latest revision on that branch.
On a locking-based system, switching to a different branch also
unlocks (write-protects) the working tree.
@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.
To produce a tags table, you run the @command{etags} shell command
on a document or the source code file. The @samp{etags} program
writes the tags to a @dfn{tags table file}, or @dfn{tags file} in
-short. The conventional name for a tags file is @file{TAGS}.
+short. The conventional name for a tags file is @file{TAGS}@.
@xref{Create Tags Table}.
Emacs provides many commands for searching and replacing using the
@samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
@item
-In La@TeX{} documents, the arguments for @code{\chapter},
+In @LaTeX{} documents, the arguments for @code{\chapter},
@code{\section}, @code{\subsection}, @code{\subsubsection},
@code{\eqno}, @code{\label}, @code{\ref}, @code{\cite},
@code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry},
packages only.
In Ada, the same name can be used for different kinds of entity
-(e.g.@:, for a procedure and for a function). Also, for things like
-packages, procedures and functions, there is the spec (i.e.@: the
-interface) and the body (i.e.@: the implementation). To make it
+(e.g., for a procedure and for a function). Also, for things like
+packages, procedures and functions, there is the spec (i.e., the
+interface) and the body (i.e., the implementation). To make it
easier to pick the definition you want, Ada tag name have suffixes
indicating the type of entity:
@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
reads a regexp to search for and a string to replace with, just like
ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x
tags-search}, but repeatedly, processing matches according to your
-input. @xref{Replace}, for more information on query replace.
+input. @xref{Query Replace}, for more information on query replace.
@vindex tags-case-fold-search
@cindex case-sensitivity and tags search
project. To define a new project, visit a file in the desired project
root and type @kbd{M-x ede-new}. This command prompts for a
@dfn{project type}, which refers to the underlying method that EDE
-will use to manage the project (@pxref{Creating a Project, EDE,, ede,
+will use to manage the project (@pxref{Creating a project, EDE,, ede,
Emacs Development Environment}). The most common project types are
@samp{Make}, which uses Makefiles, and @samp{Automake}, which uses GNU
Automake (@pxref{Top, Automake,, automake, Automake}). In both cases,
HCoop / bpt / emacs.git / blobdiff