-@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2012
-@c Free Software Foundation, Inc.
+@c This is part of the Emacs manual., Abbrevs, This is part of the Emacs manual., Top
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2014 Free Software
+@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Maintaining
@chapter Maintaining Large Programs
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,
* Old Revisions:: Examining and comparing old versions.
* VC Change Log:: Viewing the VC Change Log.
* VC Undo:: Canceling changes before or after committing.
+* VC Ignore:: Ignore files under version control system.
* VC Directory Mode:: Listing files managed by version control.
* Branches:: Multiple lines of development.
@ifnottex
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.
modification log for the entire system, which makes change log files
somewhat redundant. One advantage that they retain is that it is
sometimes useful to be able to view the transaction history of a
-single directory separately from those of other directories.
+single directory separately from those of other directories. Another
+advantage is that commit logs can't be fixed in many version control
+systems.
A project maintained with version control can use just the version
control log, or it can use both kinds of logs. It can handle some
that the work file is unmodified, and @samp{:} indicates that it has
been modified. @samp{!} indicates that the file contains conflicts as
result of a recent merge operation (@pxref{Merging}), or that the file
-was removed from the version control. Finally, @samp{?} means that
+was removed from the version control. Finally, @samp{?} means that
the file is under version control, but is missing from the working
tree.
@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.
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 Log Edit mode
@cindex mode, Log Edit
@vindex vc-log-mode-hook
+@c FIXME: Mention log-edit-mode-hook here? --xfq
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}
Edit buffer.
@end ifnottex
- To abort a commit, just @strong{don't} type @kbd{C-c C-c} in that
+ To abort a commit, just @emph{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 @file{*vc-log*} buffer, and you can go back to that buffer at
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
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
@kbd{C-x v u} to unlock a file if you lock it and then decide not to
change it.
+@node VC Ignore
+@subsection Ignore Version Control Files
+
+@table @kbd
+@item C-x v G
+Ignore a file under current version control system. (@code{vc-ignore}).
+@end table
+
+@kindex C-x v G
+@findex vc-ignore
+ Many source trees contain some files that do not need to be
+versioned, such as editor backups, object or bytecode files, and built
+programs. You can simply not add them, but then they'll always crop
+up as unknown files. You can also tell the version control system to
+ignore these files by adding them to the ignore file at the top of the
+tree. @kbd{C-x v G} (@code{vc-ignore}) can help you do this. When
+called with a prefix argument, you can remove a file from the ignored
+file list.
+
@node VC Directory Mode
@subsection VC Directory Mode
@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
@item x
Hide files with @samp{up-to-date} status
-(@code{vc-dir-hide-up-to-date}).
+(@code{vc-dir-hide-up-to-date}). With a prefix argument, hide items
+whose state is that of the item at point.
@end table
@findex vc-dir-mark
The VC Directory buffer also defines some single-key shortcuts for
VC commands with the @kbd{C-x v} prefix: @kbd{=}, @kbd{+}, @kbd{l},
-@kbd{i}, and @kbd{v}.
+@kbd{i}, @kbd{D}, @kbd{L}, @kbd{G}, @kbd{I} and @kbd{v}.
For example, you can commit a set of edited files by opening a VC
Directory buffer, where the files are listed with the @samp{edited}
@cindex branch (version control)
One use of version control is to support multiple independent lines
-of development, which are called @dfn{branches}. Branches are used
-for maintaining separate ``stable'' and ``development'' versions of a
-program, and for developing unrelated features in isolation from one
-another.
+of development, which are called @dfn{branches}. Amongst other
+things, branches can be used for maintaining separate ``stable'' and
+``development'' versions of a program, and for developing unrelated
+features in isolation from one another.
VC's support for branch operations is currently fairly limited. For
decentralized version control systems, it provides commands for
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.
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
@item
In Lisp code, any function defined with @code{defun}, any variable
-defined with @code{defvar} or @code{defconst}, and in general the first
-argument of any expression that starts with @samp{(def} in column zero is
-a tag.
+defined with @code{defvar} or @code{defconst}, and in general the
+first argument of any expression that starts with @samp{(def} in
+column zero is a tag. As an exception, expressions of the form
+@code{(defvar @var{foo})} are treated as declarations, and are only
+tagged if the @samp{--declarations} option is given.
@item
In Scheme code, tags include anything defined with @code{def} or with a
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:
@item
In Perl code, the tags are the packages, subroutines and variables
-defined by the @code{package}, @code{sub}, @code{my} and @code{local}
-keywords. Use @samp{--globals} if you want to tag global variables.
-Tags for subroutines are named @samp{@var{package}::@var{sub}}. The
-name for subroutines defined in the default package is
-@samp{main::@var{sub}}.
+defined by the @code{package}, @code{sub}, @code{use constant},
+@code{my}, and @code{local} keywords. Use @samp{--globals} if you
+want to tag global variables. Tags for subroutines are named
+@samp{@var{package}::@var{sub}}. The name for subroutines defined in
+the default package is @samp{main::@var{sub}}.
@item
In PHP code, tags are functions, classes and defines. Vars are tags
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