@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.
* VC Directory Mode:: Listing files managed by version control.
* Branches:: Multiple lines of development.
@ifnottex
-* Remote Repositories:: Efficient access to remote CVS servers.
-* Revision Tags:: Symbolic names for revisions.
* Miscellaneous VC:: Various other commands and features of VC.
* Customizing VC:: Variables that change VC's behavior.
@end ifnottex
@cindex GNU Arch
@cindex Arch
@item
-GNU Arch is one of the earliest @dfn{distributed} version control
+GNU Arch is one of the earliest @dfn{decentralized} version control
systems (the other being Monotone). @xref{VCS Concepts}, for a
-description of distributed version control systems. It is no longer
+description of decentralized version control systems. It is no longer
under active development, and has been deprecated in favor of Bazaar.
@cindex git
@item
-Git is a distributed version control system originally invented by
+Git is a decentralized version control system originally invented by
Linus Torvalds to support development of Linux (his kernel). VC
supports many common Git operations, but others, such as repository
syncing, must be done from the command line.
@cindex hg
@cindex Mercurial
@item
-Mercurial (hg) is a distributed version control system broadly
+Mercurial (hg) is a decentralized version control system broadly
resembling Git. VC supports most Mercurial commands, with the
exception of repository sync operations.
@cindex bzr
@cindex Bazaar
@item
-Bazaar (bzr) is a distributed version control system that supports
-both repository-based and distributed versioning. VC supports most
+Bazaar (bzr) is a decentralized version control system that supports
+both repository-based and decentralized versioning. VC supports most
basic editing operations under Bazaar.
@end itemize
may @dfn{commit} (or @dfn{check in}) the changes; this records the
changes in the repository, along with a descriptive log entry.
+@cindex working tree
+ A directory tree of work files is called a @dfn{working tree}.
+
@cindex revision
@cindex revision ID
Each commit creates a new @dfn{revision} in the repository. The
SCCS always uses locking. RCS is lock-based by default but can be
told to operate in a merging style. CVS and Subversion are
merge-based by default but can be told to operate in a locking mode.
-Distributed version control systems, such as GNU Arch, Git, and
+Decentralized version control systems, such as GNU Arch, Git, and
Mercurial, are exclusively merging-based.
VC mode supports both locking and merging version control. The
@cindex centralized version control
@cindex decentralized version control
+@cindex distributed version control
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. One of its drawbacks is that the repository is a choke
point for reliability and efficiency.
- GNU Arch pioneered the concept of @dfn{decentralized} version
-control, later implemented in Git, Mercurial, and Bazaar. 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. In effect, there is one repository for each
-developer, and repository merges take the place of commit operations.
+ GNU Arch pioneered the concept of @dfn{distributed} or
+@dfn{decentralized} version control, later implemented in Git,
+Mercurial, and Bazaar. 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. In
+effect, there is one repository for each developer, and repository
+merges take the place of commit operations.
VC helps you manage the traffic between your personal workfiles and
a repository. Whether the repository is a single master, or one of a
Directory buffer, and some files in it are marked, the VC fileset
consists of the marked files (@pxref{VC Directory Mode}).
- On Subversion and on decentralized version control systems,
-multi-file VC filesets are handled as a single group by the relevant
-version control commands. For example, committing a multi-file VC
-fileset generates a single revision, consisting of all the changes to
-those files. But on older version control systems which lack support
-for group operations, such as CVS, the files in a multi-file VC
-fileset are passed individually to version control commands (e.g.@: a
-commit generates one revision for each changed file).
+ On modern changeset-based version control systems (@pxref{VCS
+Changesets}), VC commands handle multi-file VC filesets as a group.
+For example, committing a multi-file VC fileset generates a single
+revision, containing the changes to all those files. On older
+file-based version control systems like CVS, each file in a multi-file
+VC fileset is handled individually; for example, a commit generates
+one revision for each changed file.
@table @kbd
@itemx C-x v v
@findex vc-next-action
@kindex C-x v v
- The principal VC command is an all-purpose command, @kbd{C-x v v}
+ The principal VC command is a multi-purpose command, @kbd{C-x v v}
(@code{vc-next-action}), which performs the ``most appropriate''
action on the current VC fileset: either registering it with a version
control system, or committing it, or unlocking it, or merging changes
@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}.
If committing to a shared repository, the commit may fail if the
repository that has been changed since your last update. In that
-case, you must perform an update before trying again. If using a
-decentralized version control system, use @kbd{C-x v +} or @kbd{C-x v
-m} (@pxref{Merging}). If using a centralized version control system,
-type @kbd{C-x v v} again to merge in the repository changes.
+case, you must perform an update before trying again. On a
+decentralized version control system, use @kbd{C-x v +} (@pxref{VC
+Pull}) or @kbd{C-x v m} (@pxref{Merging}). On a centralized version
+control system, type @kbd{C-x v v} again to merge in the repository
+changes.
@item
Finally, if you are using a centralized version control system, check
@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}).
@itemize @bullet
@item
-If the file is modified (or locked), you can specify the revision ID
-to use for the new version that you commit. This is one way to create
-a new branch (@pxref{Branches}).
+@cindex specific version control system
+You can specify the name of a version control system. This is useful
+if the fileset can be managed by more than one version control system,
+and Emacs fails to detect the correct one.
@item
-If the file is not modified (and unlocked), you can specify the
-revision to select; this lets you start working from an older
-revision, or on another branch. If you do not enter any revision,
-that takes you to the highest (``head'') revision 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.
+Otherwise, if using CVS or RCS, you can specify a revision ID.
-@item
-@cindex specific version control system
-Instead of the revision ID, 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
-@iftex
-(@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs
-Features}).
-@end iftex
-@ifnottex
-(@pxref{Local Version Control}).
-@end ifnottex
+If the fileset is modified (or locked), this makes Emacs commit with
+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}})
+checks out the latest (``head'') revision on the current branch.
+This signals an error on a decentralized version control system.
+Those systems do not let you specify your own revision IDs, nor do
+they use the concept of ``checking out'' individual files.
@end itemize
@node 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}).
- While in the @samp{*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 treated as the start of the log entry. For example, the
-following header line states that the present change was not written
-by you, but by another developer:
+ 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
+treated as the start of the log entry. For example, the following
+header line states that the present change was not written by you, but
+by another developer:
@smallexample
Author: J. R. Hacker <jrh@@example.com>
reference to a bug fixed by the change). Not all version control
systems recognize all headers: Bazaar recognizes all three headers,
while Git, Mercurial, and Monotone recognize only @samp{Author} and
-@samp{Date}. If you specify a header for a version control that does
-not support it, the header is treated as part of the log entry.
+@samp{Date}. If you specify a header for a system that does not
+support it, the header is treated as part of the log entry.
@kindex C-c C-f @r{(Log Edit mode)}
@findex log-edit-show-files
- Type @kbd{C-c C-f} (@code{log-edit-show-files}) in the
-@samp{*vc-log*} buffer to view a list of files for the VC fileset that
-is to be committed. If you called @kbd{C-x v v} directly from a work
-file, the fileset consists of that single file. If you called
-@kbd{C-x v v} from a VC directory buffer (@pxref{VC Directory Mode}),
-the fileset may consist of multiple files; in that case, @kbd{C-c C-c}
-will commit those files together, as a single revision, if that is
-supported by the version control system (on older version control
-systems, such as CVS, each file in a multi-file VC fileset is
-committed as an individual revision).
-
@kindex C-c C-d @r{(Log Edit mode)}
@findex log-edit-show-diff
- Type @kbd{C-c C-d} (@code{log-edit-show-diff}) to show a @dfn{diff}
-of the changes between the current VC fileset and the repository
-revision from which you started editing. @xref{Old Revisions}.
+ 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
+of changes between the VC fileset and the version from which you
+started editing (@pxref{Old Revisions}), type @kbd{C-c C-d}
+(@code{log-edit-show-diff}).
@kindex C-c C-a @r{(Log Edit mode)}
@findex log-edit-insert-changelog
- If the VC fileset that is to be committed includes one or more
-@file{ChangeLog} files (@pxref{Change Log}), type @kbd{C-c C-a}
+ 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.
@ifnottex
-@xref{Change Logs and VC}, for the opposite way of
-working---generating ChangeLog entries from the revision control log.
+If you are using CVS or RCS, see @ref{Change Logs and VC}, for the
+opposite way of working---generating ChangeLog entries from the Log
+Edit buffer.
@end ifnottex
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)}
repository. Such files are labeled as @samp{added} in the VC
Directory buffer, and show a revision ID of @samp{@@@@} in the mode
line. To make the registration take effect in the repository, you
-must perform a commit (@pxref{Basic VC Editing}). Note that on
-changeset-based version control systems, commits can consist of both
-file additions and modifications.
+must perform a commit (@pxref{Basic VC Editing}). Note that a single
+commit can include both file additions and edits to existing files.
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 an Ediff session. @xref{Top, Ediff,
-ediff, The Ediff Manual}.
+Like @kbd{C-x v =}, but using Ediff. @xref{Top,, Ediff, ediff, The
+Ediff Manual}.
@end ifnottex
@item C-x v D
-Compare all work files in the current version controlled directory
-tree to the tree you started from (@code{vc-root-diff}). With a
-prefix argument, prompt for two revisions and compare their trees.
+Compare the entire working tree to the revision you started from
+(@code{vc-root-diff}). With a prefix argument, prompt for two
+revisions and compare their trees.
@item C-x v ~
Prompt for a revision of the current file, and visit it in a separate
@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
@kindex C-x v D
@kbd{C-x v D} (@code{vc-root-diff}) is similar to @kbd{C-x v =}, but
-it displays a comparison between the entire current version controlled
-tree (i.e.@: the tree controlled by the version control system
-associated with the current VC fileset, which may include files that
-are not part of that fileset) and the tree you started with. If you
-invoke this command from a Dired buffer, it applies to the entire
-version controlled tree containing the directory.
+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.
@vindex vc-diff-switches
You can customize the @command{diff} options that @kbd{C-x v =} and
from the first non-@code{nil} value amongst the variables
@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 current version control system,
+@var{backend} stands for the relevant version control system,
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},
-but some default to @code{t}; these are for version control systems,
-such as Subversion, whose @code{diff} implementations do not accept
-common diff options.
+but some default to @code{t}; these are for version control systems
+whose @code{diff} implementations do not accept common diff options,
+such as Subversion.
@findex vc-revision-other-window
@kindex C-x v ~
(@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
+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 @samp{*vc-log*} buffer; @pxref{Log Buffer}). Point is
+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 distributed version control system, the @kbd{C-x v I}
+ On a decentralized version control system, the @kbd{C-x v I}
(@code{vc-log-incoming}) command displays a log buffer showing the
changes that will be applied, the next time you run the version
control system's ``pull'' command to get new revisions from another
-repository. This other repository is the default one from which
-changes are pulled, as defined by the version control system; with a
-prefix argument, @code{vc-log-incoming} prompts for a specific
-repository. Similarly, @kbd{C-x v O} (@code{vc-log-outgoing}) shows
-the changes that will be sent to 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
+repository (@pxref{VC Pull}). This other repository is the default
+one from which changes are pulled, as defined by the version control
+system; with a prefix argument, @code{vc-log-incoming} prompts for a
+specific repository. Similarly, @kbd{C-x v O}
+(@code{vc-log-outgoing}) shows the changes that will be sent to
+another repository, the next time you run the ``push'' command; with a
+prefix argument, it prompts for a specific destination repository.
+
+ 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
@vindex vc-directory-exclusion-list
The VC Directory buffer omits subdirectories listed in the variable
-@code{vc-directory-exclusion-list}. The default value of this
-variable contains directories that are used internally by version
-control systems.
+@code{vc-directory-exclusion-list}. Its default value contains
+directories that are used internally by version control systems.
@node VC Directory Commands
@subsubsection VC Directory Commands
(@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}).
@item U
-If point is on a file entry, umark all files with the same status; if
+If point is on a file entry, unmark all files with the same status; if
point is on a directory entry, unmark all files in that directory tree
(@code{vc-dir-unmark-all-files}). With a prefix argument, unmark all
files and directories.
bring them back at a later time).
@node Branches
-@subsection Multiple Branches of a File
+@subsection Version Control Branches
@cindex branch (version control)
-@cindex trunk (version control)
-
- One use of version control is to maintain multiple ``current''
-revisions of a file. For example, you might have different revisions of a
-program in which you are gradually adding various unfinished new
-features. Each such independent line of development is called a
-@dfn{branch}. 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}.
-You can create multiple branches from the trunk. How the difference
-between trunk and branch is made visible is dependent on whether the
-VCS uses dot-pair or monotonic version IDs.
-
- In VCSes with dot-pair revision IDs, the revisions on the trunk are
-normally IDed 1.1, 1.2, 1.3, etc. At any such revision, you can
-start an independent branch. A branch starting at revision 1.2 would
-have revision ID 1.2.1.1, and consecutive revisions on this branch
-would have IDs 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on. If there is
-a second branch also starting at revision 1.2, it would consist of
-revisions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc.
-
- In VCSes with monotonic revision IDs, trunk revisions are IDed as
-1, 2, 3, etc. A branch from (say) revision 2 might start with 2.1 and
-continue through 2.2, 2.3, etc. But naming conventions for branches
-and subbranches vary widely on these systems, and some (like
-Mercurial) never depart from the monotonic integer sequence at all.
-Consult the documentation of the VCS you are using.
-
-@cindex head revision
- If you omit the final component of a dot-pair revision ID, that is called a
-@dfn{branch ID}. It refers to the highest existing revision on that
-branch---the @dfn{head revision} of that branch. The branches in the
-dot-pair example above have branch IDs 1.2.1 and 1.2.2.
+
+ 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.
+
+ VC's support for branch operations is currently fairly limited. For
+decentralized version control systems, it provides commands for
+@dfn{updating} one branch with the contents of another, and for
+@dfn{merging} the changes made to two different branches
+(@pxref{Merging}). For centralized version control systems, it
+supports checking out different branches and committing into new or
+different branches.
@menu
* Switching Branches:: How to get to another existing branch.
-* Creating Branches:: How to start a new branch.
+* VC Pull:: Updating the contents of a branch.
* Merging:: Transferring changes between branches.
-* Multi-User Branching:: Multiple users working at multiple branches
- in parallel.
+* Creating Branches:: How to start a new branch.
@end menu
@node Switching Branches
@subsubsection Switching between Branches
- To switch between branches, type @kbd{C-u C-x v v} and specify the
-revision ID you want to select. On a locking-based system, this
-version is then visited @emph{unlocked} (write-protected), so you can
-examine it before locking it. Switching branches in this way is allowed
-only when the file is not locked.
+ The various version control systems differ in how branches are
+implemented, and these differences cannot be entirely concealed by VC.
+
+ On some decentralized version control systems, including Bazaar and
+Mercurial in its normal mode of operation, each branch has its own
+working directory tree, so switching between branches just involves
+switching directories. On Git, switching between branches is done
+using the @command{git branch} command, which changes the contents of
+the working tree itself.
+
+ On centralized version control systems, you can switch between
+branches by typing @kbd{C-u C-x v v} in an up-to-date work file
+(@pxref{Advanced C-x v v}), and entering the revision ID for a
+revision on another branch. On CVS, for instance, revisions on the
+@dfn{trunk} (the main line of development) normally have IDs of the
+form 1.1, 1.2, 1.3, @dots{}, while the first branch created from (say)
+revision 1.2 has revision IDs 1.2.1.1, 1.2.1.2, @dots{}, the second
+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.
+
+ On a locking-based system, switching to a different branch also
+unlocks (write-protects) the working tree.
+
+ Once you have switched to a branch, VC commands will apply to that
+branch until you switch away; for instance, any VC filesets that you
+commit will be committed to that specific branch.
+
+@node VC Pull
+@subsubsection Pulling Changes into a Branch
- On a VCS with dot-pair IDs, you can omit the minor part, thus giving
-only the branch ID; 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.
+@table @kbd
+@itemx C-x v +
+On a decentralized version control system, update the current branch
+by ``pulling in'' changes from another location.
-@node Creating Branches
-@subsubsection Creating New Branches
+On a centralized version control system, update the current VC
+fileset.
+@end table
- To create a new branch from a head revision (one that is the latest
-in the branch that contains it), first select that revision if
-necessary, lock it with @kbd{C-x v v}, and make whatever changes you
-want. Then, when you commit the changes, use @kbd{C-u C-x v v}. This
-lets you specify the revision ID for the new revision. You should
-specify a suitable branch ID for a branch starting at the current
-revision. For example, if the current revision is 2.5, the branch ID
-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 revision (one that is no longer the
-head of a branch), first select that revision (@pxref{Switching
-Branches}). Your procedure will then differ depending on whether you
-are using a locking or merging-based VCS.
+@kindex C-x v +
+@findex vc-pull
+ On a decentralized version control system, the command @kbd{C-x v +}
+(@code{vc-pull}) updates the current branch and working tree. It is
+typically used to update a copy of a remote branch. If you supply a
+prefix argument, the command prompts for the exact version control
+command to use, which lets you specify where to pull changes from.
+Otherwise, it pulls from a default location determined by the version
+control system.
- On a locking VCS, you will need to lock the old revision branch with
-@kbd{C-x v v}. You'll be asked to confirm, when you lock the old
-revision, that you really mean to create a new branch---if you say no,
-you'll be offered a chance to lock the latest revision instead. On
-a merging-based VCS you will skip this step.
+ Amongst decentralized version control systems, @kbd{C-x v +} is
+currently supported only by Bazaar, Git, and Mercurial. On Bazaar, it
+calls @command{bzr pull} for ordinary branches (to pull from a master
+branch into a mirroring branch), and @command{bzr update} for a bound
+branch (to pull from a central repository). On Git, it calls
+@command{git pull} to fetch changes from a remote repository and merge
+it into the current branch. On Mercurial, it calls @command{hg pull
+-u} to fetch changesets from the default remote repository and update
+the working directory.
- Then make your changes and type @kbd{C-x v v} again to commit a new
-revision. This automatically creates a new branch starting from the
-selected revision. You need not specially request a new branch,
-because that's the only way to add a new revision at a point that is
-not the head of a branch.
+ Prior to pulling, you can use @kbd{C-x v I} (@code{vc-log-incoming})
+to view a log buffer of the changes to be applied. @xref{VC Change
+Log}.
- After the branch is created, you ``stay'' on it. That means that
-subsequent commits create new revisions on that branch. To leave the
-branch, you must explicitly select a different revision 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.
+ On a centralized version control system like CVS, @kbd{C-x v +}
+updates the current VC fileset from the repository.
@node Merging
@subsubsection Merging Branches
-
@cindex 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.
@table @kbd
-@item C-x v m (vc-merge)
-Merge changes into the work file.
+@itemx C-x v m
+On a decentralized version control system, merge changes from another
+branch into the current one.
+
+On a centralized version control system, merge changes from another
+branch into the current VC fileset.
@end table
-@kindex C-x v m
-@findex 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
-@key{RET}, 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 ID or a pair of revision IDs in
-the minibuffer. Then @kbd{C-x v m} finds the changes from that
-branch, or the differences between the two revisions you specified, and
-merges them into the current revision 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 revision 1.5. To merge the changes from the branch to the trunk,
-first go to the head revision of the trunk, by typing @kbd{C-u C-x v v
-@key{RET}}. Revision 1.5 is now current. If locking is used for the file,
-type @kbd{C-x v v} to lock revision 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 revision 1.3, where the branch started, up to
-the last revision on the branch) and merges it into the current revision
-of the work file. You can now commit the changed file, thus creating
-revision 1.6 containing the changes from the branch.
-
- It is possible to do further editing after merging the branch, before
-the next commit. But it is usually wiser to commit the merged
-revision, then lock it and make the further changes. This will keep
-a better record of the history of changes.
+ While developing a branch, you may sometimes need to @dfn{merge} in
+changes that have already been made in another branch. This is not a
+trivial operation, as overlapping changes may have been made to the
+two branches.
+
+ On a decentralized version control system, merging is done with the
+command @kbd{C-x v m} (@code{vc-merge}). On Bazaar, this prompts for
+the exact arguments to pass to @command{bzr merge}, offering a
+sensible default if possible. On Git, this prompts for the name of a
+branch to merge from, with completion (based on the branch names known
+to the current repository). The output from running the merge command
+is shown in a separate buffer.
+
+ On a centralized version control system like CVS, @kbd{C-x v m}
+prompts for a branch ID, or a pair of revision IDs (@pxref{Switching
+Branches}); then it finds the changes from that branch, or the changes
+between the two revisions you specified, and merges those changes into
+the current VC fileset. If you just type @key{RET}, Emacs simply
+merges any changes that were made on the same branch since you checked
+the file out.
@cindex conflicts
@cindex 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 revision with user B's changes in it is 1.11.
-
-@c @w here is so CVS won't think this is a conflict.
-@smallexample
-@group
-@w{<}<<<<<< name
- @var{User A's version}
-=======
- @var{User B's version}
-@w{>}>>>>>> 1.11
-@end group
-@end smallexample
+ Immediately after performing a merge, only the working tree is
+modified, and you can review the changes produced by the merge with
+@kbd{C-x v D} and related commands (@pxref{Old Revisions}). If the
+two branches contained overlapping changes, merging produces a
+@dfn{conflict}; a warning appears in the output of the merge command,
+and @dfn{conflict markers} are inserted into each affected work file,
+surrounding the two sets of conflicting changes. You must then
+resolve the conflict by editing the conflicted files. Once you are
+done, the modified files must be committed in the usual way for the
+merge to take effect (@pxref{Basic VC Editing}).
-@findex 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
-commit the merged version afterwards.
-
-@findex vc-find-conflicted-file
- If there is more than one conflicted file in a merge, type @kbd{M-x
-vc-find-conflicted-file} after resolving the conflicts in each file.
-This command visits the next conflicted file, and moves point to the
-first conflict marker in that file.
-
-@node Multi-User Branching
-@subsubsection Multi-User Branching
-
- It is often useful for multiple developers to work simultaneously on
-different branches of a file. CVS and later systems allow 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
-revisions, but all share the same common RCS records.
-
- This technique works reliably and automatically, provided that the
-source files contain RCS version headers
-@iftex
-(@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}).
-@end iftex
-@ifnottex
-(@pxref{Version Headers}).
-@end ifnottex
-The headers enable Emacs to be sure, at all times, which revision
-ID is present in the work file.
+@node Creating Branches
+@subsubsection Creating New Branches
+
+ On centralized version control systems like CVS, Emacs supports
+creating new branches as part of a commit operation. When committing
+a modified VC fileset, type @kbd{C-u C-x v v} (@code{vc-next-action}
+with a prefix argument; @pxref{Advanced C-x v v}). Then Emacs prompts
+for a revision ID for the new revision. You should specify a suitable
+branch ID for a branch starting at the current revision. For example,
+if the current revision is 2.5, the branch ID 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 revision (one that is no longer
+the head of a branch), first select that revision (@pxref{Switching
+Branches}). Your procedure will then differ depending on whether you
+are using a locking or merging-based VCS.
- 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 ID. This ensures that Emacs knows which branch it is using
-during this particular editing session.
+ On a locking VCS, you will need to lock the old revision branch with
+@kbd{C-x v v}. You'll be asked to confirm, when you lock the old
+revision, that you really mean to create a new branch---if you say no,
+you'll be offered a chance to lock the latest revision instead. On a
+merging-based VCS you will skip this step.
+
+ Then make your changes and type @kbd{C-x v v} again to commit a new
+revision. This creates a new branch starting from the selected
+revision.
+
+ After the branch is created, subsequent commits create new revisions
+on that branch. To leave the branch, you must explicitly select a
+different revision with @kbd{C-u C-x v v}.
@ifnottex
@include vc1-xtra.texi
@section Change Logs
@cindex change log
- A change log file contains a chronological record of when and why you
-have changed a program, consisting of a sequence of entries describing
-individual changes. Normally it is kept in a file called
-@file{ChangeLog} in the same directory as the file you are editing, or
-one of its parent directories. A single @file{ChangeLog} file can
-record changes for all the files in its directory and all its
-subdirectories.
+ Many software projects keep a @dfn{change log}. This is a file,
+normally named @file{ChangeLog}, containing a chronological record of
+when and how the program was changed. Sometimes, there are several
+change log files, each recording the changes in one directory or
+directory tree.
@menu
* Change Log Commands:: Commands for editing change log files.
You can combine multiple changes of the same nature. If you don't
enter any text after the initial @kbd{C-x 4 a}, any subsequent
-@kbd{C-x 4 a} adds another symbol to the change.
+@kbd{C-x 4 a} adds another symbol to the change log entry.
@vindex add-log-always-start-new-record
If @code{add-log-always-start-new-record} is non-@code{nil},
Version control systems are another way to keep track of changes in
your program and keep a change log. In the VC log buffer, typing
@kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant
-Change Log entry, if one exists (@pxref{Log Buffer}). You can also
-insert a VC log entry into a Change Log buffer by typing @kbd{C-x v a}
-(@code{vc-update-change-log}) in the Change Log buffer
-@iftex
-(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
-@end iftex
-@ifnottex
-(@pxref{Change Logs and VC}).
-@end ifnottex
+Change Log entry, if one exists. @xref{Log Buffer}.
@node Format of ChangeLog
@subsection Format of ChangeLog
@cindex tags and tag tables
A @dfn{tag} is a reference to a subunit in a program or in a
-document. In program source code, tags reference syntactic elements
-of the program: functions, subroutines, data types, macros, etc. In a
+document. In source code, tags reference syntactic elements of the
+program: functions, subroutines, data types, macros, etc. In a
document, tags reference chapters, sections, appendices, etc. Each
tag specifies the name of the file where the corresponding subunit is
defined, and the position of the subunit's definition in that file.
C files; and Fortran files produced by preprocessing @file{.fpp}
source files.
- To produce a tags table, you use the @samp{etags} command,
-submitting it a document or the source code of a program.
-@samp{etags} 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}.
+@cindex etags
+ 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}.
+@xref{Create Tags Table}.
- Emacs uses the information recorded in tags tables in commands that
-search or replace through multiple source files: these commands use
-the names of the source files recorded in the tags table to know which
-files to search. Other commands, such as @kbd{M-.}, which finds the
-definition of a function, use the recorded information about the
-function names and positions to find the source file and the position
-within that file where the function is defined.
+ Emacs provides many commands for searching and replacing using the
+information recorded in tags tables. For instance, the @kbd{M-.}
+(@code{find-tag}) jumps to the location of a specified function
+definition in its source file. @xref{Find Tag}.
@cindex C++ class browser, tags
@cindex tags, C++
@cindex class browser, C++
@cindex Ebrowse
- See also the Ebrowse facility, which is tailored for C++.
-@xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}.
+ The Ebrowse facility is similar to @command{etags} but specifically
+tailored for C++. @xref{Top,, Ebrowse, ebrowse, Ebrowse User's
+Manual}. The Semantic package provides another way to generate and
+use tags, separate from the @command{etags} facility.
+@xref{Semantic}.
@menu
* Tag Syntax:: Tag syntax for various types of code and text files.
-* Create Tags Table:: Creating a tags table with @code{etags}.
+* Create Tags Table:: Creating a tags table with @command{etags}.
* Etags Regexps:: Create arbitrary tags using regular expressions.
* Select Tags Table:: How to visit a tags table.
* Find Tag:: Commands to find the definition of a specific tag.
* Tags Search:: Using a tags table for searching and replacing.
-* List Tags:: Listing and finding tags defined in a file.
+* List Tags:: Using tags for completion, and listing them.
@end menu
@node Tag Syntax
You can tag function declarations and external variables in addition
to function definitions by giving the @samp{--declarations} option to
-@code{etags}.
+@command{etags}.
@item
In C++ code, in addition to all the tag constructs of C code, member
@samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
@item
-In La@TeX{} text, the argument of any of the commands @code{\chapter},
+In La@TeX{} 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},
@code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},
-@code{\newenvironment} or @code{\renewenvironment} is a tag.@refill
+@code{\newenvironment} and @code{\renewenvironment} are tags.
Other commands can make tags as well, if you specify them in the
-environment variable @env{TEXTAGS} before invoking @code{etags}. The
+environment variable @env{TEXTAGS} before invoking @command{etags}. The
value of this environment variable should be a colon-separated list of
command names. For example,
@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
@node Create Tags Table
@subsection Creating Tags Tables
-@cindex @code{etags} program
+@cindex @command{etags} program
- The @code{etags} program is used to create a tags table file. It knows
+ The @command{etags} program is used to create a tags table file. It knows
the syntax of several languages, as described in
@iftex
the previous section.
@ifnottex
@ref{Tag Syntax}.
@end ifnottex
-Here is how to run @code{etags}:
+Here is how to run @command{etags}:
@example
etags @var{inputfiles}@dots{}
@end example
@noindent
-The @code{etags} program reads the specified files, and writes a tags
+The @command{etags} program reads the specified files, and writes a tags
table named @file{TAGS} in the current working directory. You can
optionally specify a different file name for the tags table by using the
@samp{--output=@var{file}} option; specifying @file{-} as a file name
prints the tags table to standard output.
- If the specified files don't exist, @code{etags} looks for
+ If the specified files don't exist, @command{etags} looks for
compressed versions of them and uncompresses them to read them. Under
-MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz}
+MS-DOS, @command{etags} also looks for file names like @file{mycode.cgz}
if it is given @samp{mycode.c} on the command line and @file{mycode.c}
does not exist.
- @code{etags} recognizes the language used in an input file based on
-its file name and contents. You can specify the language with the
-@samp{--language=@var{name}} option, described below.
-
- If the tags table data become outdated due to changes in the files
-described in the table, the way to update the tags table is the same
-way it was made in the first place. If the tags table fails to record
-a tag, or records it for the wrong file, then Emacs cannot possibly
-find its definition until you update the tags table. However, if the
-position recorded in the tags table becomes a little bit wrong (due to
-other editing), the worst consequence is a slight delay in finding the
-tag. Even if the stored position is very far wrong, Emacs will still
-find the tag, after searching most of the file for it. That delay is
-hardly noticeable with today's computers.
+ If the tags table becomes outdated due to changes in the files
+described in it, you can update it by running the @command{etags}
+program again. If the tags table does not record a tag, or records it
+for the wrong file, then Emacs will not be able to find that
+definition until you update the tags table. But if the position
+recorded in the tags table becomes a little bit wrong (due to other
+editing), Emacs will still be able to find the right position, with a
+slight delay.
Thus, there is no need to update the tags table after each edit.
You should update a tags table when you define new tags that you want
to have listed, or when you move tag definitions from one file to
another, or when changes become substantial.
- One tags table can virtually include another. Specify the included
-tags file name with the @samp{--include=@var{file}} option when
-creating the file that is to include it. The latter file then acts as
-if it covered all the source files specified in the included file, as
-well as the files it directly contains.
+ You can make a tags table @dfn{include} another tags table, by
+passing the @samp{--include=@var{file}} option to @command{etags}. It
+then covers all the files covered by the included tags file, as well
+as its own.
If you specify the source files with relative file names when you run
-@code{etags}, the tags file will contain file names relative to the
+@command{etags}, the tags file will contain file names relative to the
directory where the tags file was initially written. This way, you can
move an entire directory tree containing both the tags file and the
source files, and the tags file will still refer correctly to the source
pointing to a tags file in a different directory, because this would
generally render the file names invalid.
- If you specify absolute file names as arguments to @code{etags}, then
+ If you specify absolute file names as arguments to @command{etags}, then
the tags file will contain absolute file names. This way, the tags file
will still refer to the same files even if you move it, as long as the
source files remain in the same place. Absolute file names start with
@samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
- When you want to make a tags table from a great number of files, you
-may have problems listing them on the command line, because some systems
-have a limit on its length. The simplest way to circumvent this limit
-is to tell @code{etags} to read the file names from its standard input,
-by typing a dash in place of the file names, like this:
+ When you want to make a tags table from a great number of files,
+you may have problems listing them on the command line, because some
+systems have a limit on its length. You can circumvent this limit by
+telling @command{etags} to read the file names from its standard
+input, by typing a dash in place of the file names, like this:
@smallexample
find . -name "*.[chCH]" -print | etags -
@end smallexample
- Use the option @samp{--language=@var{name}} to specify the language
-explicitly. You can intermix these options with file names; each one
-applies to the file names that follow it. Specify
-@samp{--language=auto} to tell @code{etags} to resume guessing the
-language from the file names and file contents. Specify
-@samp{--language=none} to turn off language-specific processing
-entirely; then @code{etags} recognizes tags by regexp matching alone
-(@pxref{Etags Regexps}).
+ @command{etags} recognizes the language used in an input file based
+on its file name and contents. You can specify the language
+explicitly with the @samp{--language=@var{name}} option. You can
+intermix these options with file names; each one applies to the file
+names that follow it. Specify @samp{--language=auto} to tell
+@command{etags} to resume guessing the language from the file names
+and file contents. Specify @samp{--language=none} to turn off
+language-specific processing entirely; then @command{etags} recognizes
+tags by regexp matching alone (@pxref{Etags Regexps}).
The option @samp{--parse-stdin=@var{file}} is mostly useful when
-calling @code{etags} from programs. It can be used (only once) in
-place of a file name on the command line. @code{Etags} will read from
+calling @command{etags} from programs. It can be used (only once) in
+place of a file name on the command line. @command{etags} will read from
standard input and mark the produced tags as belonging to the file
@var{file}.
- @samp{etags --help} outputs the list of the languages @code{etags}
+ @samp{etags --help} outputs the list of the languages @command{etags}
knows, and the file name rules for guessing the language. It also prints
-a list of all the available @code{etags} options, together with a short
+a list of all the available @command{etags} options, together with a short
explanation. If followed by one or more @samp{--language=@var{lang}}
options, it outputs detailed information about how tags are generated for
@var{lang}.
@node Etags Regexps
@subsection Etags Regexps
- The @samp{--regex} option provides a general way of recognizing tags
-based on regexp matching. You can freely intermix this option with
-file names, and each one applies to the source files that follow it.
-If you specify multiple @samp{--regex} options, all of them are used
-in parallel. The syntax is:
+ The @samp{--regex} option to @command{etags} allows tags to be
+recognized by regular expression matching. You can intermix this
+option with file names; each one applies to the source files that
+follow it. If you specify multiple @samp{--regex} options, all of
+them are used in parallel. The syntax is:
@smallexample
--regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}
@end smallexample
- The essential part of the option value is @var{tagregexp}, the
-regexp for matching tags. It is always used anchored, that is, it
-only matches at the beginning of a line. If you want to allow
-indented tags, use a regexp that matches initial whitespace; start it
-with @samp{[ \t]*}.
+@noindent
+The essential part of the option value is @var{tagregexp}, the regexp
+for matching tags. It is always used anchored, that is, it only
+matches at the beginning of a line. If you want to allow indented
+tags, use a regexp that matches initial whitespace; start it with
+@samp{[ \t]*}.
In these regular expressions, @samp{\} quotes the next character, and
all the GCC character escape sequences are supported (@samp{\a} for
below.
The @var{modifiers} are a sequence of zero or more characters that
-modify the way @code{etags} does the matching. A regexp with no
+modify the way @command{etags} does the matching. A regexp with no
modifiers is applied sequentially to each line of the input file, in a
case-sensitive way. The modifiers and their meanings are:
@end smallexample
@noindent
-Here @code{etags} chooses the parsing language for @file{voo.doo} and
-@file{bar.ber} according to their contents. @code{etags} also uses
+Here @command{etags} chooses the parsing language for @file{voo.doo} and
+@file{bar.ber} according to their contents. @command{etags} also uses
@var{reg1} to recognize additional tags in @file{voo.doo}, and both
@var{reg1} and @var{reg2} to recognize additional tags in
@file{bar.ber}. @var{reg1} is checked against each line of
@file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while
@var{reg2} is checked against the whole @file{bar.ber} file,
-permitting multi-line matches, in a case-sensitive way. @code{etags}
+permitting multi-line matches, in a case-sensitive way. @command{etags}
uses only the Lisp tags rules, with no user-specified regexp matching,
to recognize tags in @file{los.er}.
You can restrict a @samp{--regex} option to match only files of a
given language by using the optional prefix @var{@{language@}}.
(@samp{etags --help} prints the list of languages recognized by
-@code{etags}.) This is particularly useful when storing many
-predefined regular expressions for @code{etags} in a file. The
+@command{etags}.) This is particularly useful when storing many
+predefined regular expressions for @command{etags} in a file. The
following example tags the @code{DEFVAR} macros in the Emacs source
files, for the C language only:
@noindent
When you have complex regular expressions, you can store the list of
-them in a file. The following option syntax instructs @code{etags} to
+them in a file. The following option syntax instructs @command{etags} to
read two files of regular expressions. The regular expressions
contained in the second file are matched without regard to case.
@end smallexample
@noindent
-A regex file for @code{etags} contains one regular expression per
+A regex file for @command{etags} contains one regular expression per
line. Empty lines, and lines beginning with space or tab are ignored.
-When the first character in a line is @samp{@@}, @code{etags} assumes
+When the first character in a line is @samp{@@}, @command{etags} assumes
that the rest of the line is the name of another file of regular
expressions; thus, one such file can include another file. All the
other lines are taken to be regular expressions. If the first
@node Select Tags Table
@subsection Selecting a Tags Table
-@vindex tags-file-name
@findex visit-tags-table
- Emacs has at any time one @dfn{selected} tags table, and all the
+ Emacs has at any time one @dfn{selected} tags table. All the
commands for working with tags tables use the selected one. To select
a tags table, type @kbd{M-x visit-tags-table}, which reads the tags
table file name as an argument, with @file{TAGS} in the default
directory as the default.
+@vindex tags-file-name
Emacs does not actually read in the tags table contents until you
try to use them; all @code{visit-tags-table} does is store the file
name in the variable @code{tags-file-name}, and setting the variable
@kindex M-.
@findex find-tag
- @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of
-a specified tag. It searches through the tags table for that tag, as a
-string, and then uses the tags table info to determine the file that the
-definition is in and the approximate character position in the file of
-the definition. Then @code{find-tag} visits that file, moves point to
-the approximate character position, and searches ever-increasing
-distances away to find the tag definition.
-
- If an empty argument is given (just type @key{RET}), the balanced
-expression in the buffer before or around point is used as the
-@var{tag} argument. @xref{Expressions}.
+ @kbd{M-.}@: (@code{find-tag}) prompts for a tag name and jumps to
+its source definition. It works by searching through the tags table
+for that tag's file and approximate character position, visiting that
+file, and searching for the tag definition at ever-increasing
+distances away from the recorded approximate position.
+
+ When entering the tag argument to @kbd{M-.}, the usual minibuffer
+completion commands can be used (@pxref{Completion}), with the tag
+names in the selected tags table as completion candidates. If you
+specify an empty argument, the balanced expression in the buffer
+before or around point is the default argument. @xref{Expressions}.
You don't need to give @kbd{M-.} the full name of the tag; a part
-will do. This is because @kbd{M-.} finds tags in the table which
-contain @var{tag} as a substring. However, it prefers an exact match
-to a substring match. To find other tags that match the same
-substring, give @code{find-tag} a numeric argument, as in @kbd{C-u
-M-.}; this does not read a tag name, but continues searching the tags
-table's text for another tag containing the same substring last used.
-If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier
-alternative to @kbd{C-u M-.}.
+will do. @kbd{M-.} finds tags which contain that argument as a
+substring. However, it prefers an exact match to a substring match.
+To find other tags that match the same substring, give @code{find-tag}
+a numeric argument, as in @kbd{C-u M-.} or @kbd{M-0 M-.}; this does
+not read a tag name, but continues searching the tags table's text for
+another tag containing the same substring last used.
@kindex C-x 4 .
@findex find-tag-other-window
@findex find-tag-other-frame
Like most commands that can switch buffers, @code{find-tag} has a
variant that displays the new buffer in another window, and one that
-makes a new frame for it. The former is @w{@kbd{C-x 4 .}}, which invokes
-the command @code{find-tag-other-window}. The latter is @w{@kbd{C-x 5 .}},
-which invokes @code{find-tag-other-frame}.
+makes a new frame for it. The former is @w{@kbd{C-x 4 .}}
+(@code{find-tag-other-window}), and the latter is @w{@kbd{C-x 5 .}}
+(@code{find-tag-other-frame}).
- To move back to places you've found tags recently, use @kbd{C-u -
-M-.}; more generally, @kbd{M-.} with a negative numeric argument. This
-command can take you to another buffer. @w{@kbd{C-x 4 .}} with a negative
-argument finds the previous tag location in another window.
+ To move back to previous tag definitions, use @kbd{C-u - M-.}; more
+generally, @kbd{M-.} with a negative numeric argument. Similarly,
+@w{@kbd{C-x 4 .}} with a negative argument finds the previous tag
+location in another window.
@kindex M-*
@findex pop-tag-mark
@vindex find-tag-marker-ring-length
- As well as going back to places you've found tags recently, you can go
-back to places @emph{from where} you found them. Use @kbd{M-*}, which
-invokes the command @code{pop-tag-mark}, for this. Typically you would
-find and study the definition of something with @kbd{M-.} and then
-return to where you were with @kbd{M-*}.
+ As well as going back to places you've found tags recently, you can
+go back to places @emph{from where} you found them, using @kbd{M-*}
+(@code{pop-tag-mark}). Thus you can find and examine the definition
+of something with @kbd{M-.} and then return to where you were with
+@kbd{M-*}.
Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to
a depth determined by the variable @code{find-tag-marker-ring-length}.
@kindex M-,
@findex tags-loop-continue
- Having found one match, you probably want to find all the rest. To find
-one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the
-@code{tags-search}. This searches the rest of the current buffer, followed
-by the remaining files of the tags table.@refill
+ Having found one match, you probably want to find all the rest.
+Type @kbd{M-,} (@code{tags-loop-continue}) to resume the
+@code{tags-search}, finding one more match. This searches the rest of
+the current buffer, followed by the remaining files of the tags table.
@findex tags-query-replace
@kbd{M-x tags-query-replace} performs a single
Buffers in which no match is found are quickly killed; the others
continue to exist.
- It may have struck you that @code{tags-search} is a lot like
-@code{grep}. You can also run @code{grep} itself as an inferior of
-Emacs and have Emacs show you the matching lines one by one.
+ As an alternative to @code{tags-search}, you can run @command{grep}
+as a subprocess and have Emacs show you the matching lines one by one.
@xref{Grep Searching}.
@node List Tags
@subsection Tags Table Inquiries
@table @kbd
+@item C-M-i
+@itemx M-@key{TAB}
+Perform completion on the text around point, using the selected tags
+table if one is loaded (@code{completion-at-point}).
@item M-x list-tags @key{RET} @var{file} @key{RET}
Display a list of the tags defined in the program file @var{file}.
@item M-x tags-apropos @key{RET} @var{regexp} @key{RET}
Display a list of all tags matching @var{regexp}.
@end table
+@cindex completion (symbol names)
+ In most programming language modes, you can type @kbd{C-M-i} or
+@kbd{M-@key{TAB}} (@code{completion-at-point}) to complete the symbol
+at point. If there is a selected tags table, this command can use it
+to generate completion candidates. @xref{Symbol Completion}.
+
@findex list-tags
- @kbd{M-x list-tags} reads the name of one of the files described by
-the selected tags table, and displays a list of all the tags defined in
-that file. The ``file name'' argument is really just a string to
-compare against the file names recorded in the tags table; it is read as
-a string rather than as a file name. Therefore, completion and
-defaulting are not available, and you must enter the file name the same
-way it appears in the tags table. Do not include a directory as part of
-the file name unless the file name recorded in the tags table includes a
-directory.
+ @kbd{M-x list-tags} reads the name of one of the files covered by
+the selected tags table, and displays a list of tags defined in that
+file. Do not include a directory as part of the file name unless the
+file name recorded in the tags table includes a directory.
@findex tags-apropos
@vindex tags-apropos-verbose
- @kbd{M-x tags-apropos} is like @code{apropos} for tags
-(@pxref{Apropos}). It finds all the tags in the selected tags table
-whose entries match @var{regexp}, and displays them. If the variable
-@code{tags-apropos-verbose} is non-@code{nil}, it displays the names
-of the tags files together with the tag names.
-
@vindex tags-tag-face
@vindex tags-apropos-additional-actions
- You can customize the appearance of the output by setting the
-variable @code{tags-tag-face} to a face. You can display additional
-output with @kbd{M-x tags-apropos} by customizing the variable
-@code{tags-apropos-additional-actions}---see its documentation for
-details.
-
- You can also use the collection of tag names to complete a symbol
-name in the buffer. @xref{Symbol Completion}.
-
- You can use @kbd{M-x next-file} to visit the files in the selected
-tags table. The first time this command is called, it visits the
-first file in the tags table. Each subsequent call visits the next
-file in the table, unless a prefix argument is supplied, in which case
-it returns to the first file.
+ @kbd{M-x tags-apropos} is like @code{apropos} for tags
+(@pxref{Apropos}). It displays a list of tags in the selected tags
+table whose entries match @var{regexp}. If the variable
+@code{tags-apropos-verbose} is non-@code{nil}, it displays the names
+of the tags files together with the tag names. You can customize the
+appearance of the output by setting the variable @code{tags-tag-face}
+to a face. You can display additional output by customizing the
+variable @code{tags-apropos-additional-actions}; see its documentation
+for details.
+
+@findex next-file
+ @kbd{M-x next-file} visits files covered by the selected tags table.
+The first time it is called, it visits the first file covered by the
+table. Each subsequent call visits the next covered file, unless a
+prefix argument is supplied, in which case it returns to the first
+file.
@node EDE
@section Emacs Development Environment