3513 lines
144 KiB
Plaintext
3513 lines
144 KiB
Plaintext
@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--2024 Free Software
|
|
@c Foundation, Inc.
|
|
@c See file emacs.texi for copying conditions.
|
|
@node Maintaining
|
|
@chapter Maintaining Large Programs
|
|
@cindex maintaining large programs
|
|
@cindex large programming projects, maintaining
|
|
|
|
This chapter describes Emacs features for maintaining medium- to
|
|
large-size programs and packages. These features include:
|
|
|
|
@itemize @minus
|
|
@item
|
|
Unified interface to Support for Version Control Systems
|
|
(@acronym{VCS}) that record the history of changes to source files.
|
|
|
|
@item
|
|
Commands for handling programming projects.
|
|
|
|
@item
|
|
A specialized mode for maintaining @file{ChangeLog} files that provide
|
|
a chronological log of program changes.
|
|
|
|
@item
|
|
@acronym{Xref}, a set of commands for displaying definitions of
|
|
symbols (a.k.a.@: ``identifiers'') and their references.
|
|
|
|
@item
|
|
@acronym{EDE}, the Emacs's own IDE.
|
|
|
|
@ifnottex
|
|
@item
|
|
A mode for merging changes to program sources made on separate
|
|
branches of development.
|
|
@end ifnottex
|
|
|
|
@item
|
|
A minor-mode for highlighting bug references and visiting the
|
|
referenced bug reports in their issue tracker.
|
|
@end itemize
|
|
|
|
If you are maintaining a large Lisp program, then in addition to the
|
|
features described here, you may find the Emacs Lisp Regression
|
|
Testing (@acronym{ERT}) library useful (@pxref{Top,,ERT,ert, Emacs
|
|
Lisp Regression Testing}).
|
|
|
|
@menu
|
|
* Version Control:: Using version control systems.
|
|
* Projects:: Commands for handling source files in a project.
|
|
* Change Log:: Maintaining a change history for your program.
|
|
* Xref:: Find definitions and references of any function,
|
|
method, struct, macro, @dots{} in your program.
|
|
* EDE:: An integrated development environment for Emacs.
|
|
@ifnottex
|
|
* Emerge:: A convenient way of merging two versions of a program.
|
|
@end ifnottex
|
|
* Bug Reference:: Highlighting references to bug reports and browsing
|
|
them in their issue trackers.
|
|
@end menu
|
|
|
|
@node Version Control
|
|
@section Version Control
|
|
@cindex version control
|
|
|
|
A @dfn{version control system} is a program that can record multiple
|
|
versions of a source file, storing information such as the creation
|
|
time of each version, who made it, and a description of what was
|
|
changed.
|
|
|
|
@cindex VC
|
|
The Emacs version control interface is called @dfn{VC}@. VC
|
|
commands work with several different version control systems;
|
|
currently, it supports Bazaar, CVS, Git, Mercurial, Monotone, RCS,
|
|
SRC, SCCS/CSSC, and Subversion. Of these, the GNU project distributes
|
|
CVS, RCS, and Bazaar.
|
|
|
|
VC is enabled automatically whenever you visit a file governed by a
|
|
version control system. To disable VC entirely, set the customizable
|
|
variable @code{vc-handled-backends} to @code{nil}
|
|
@iftex
|
|
(@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
|
|
@end iftex
|
|
@ifnottex
|
|
(@pxref{Customizing VC}).
|
|
@end ifnottex
|
|
|
|
@findex vc-refresh-state
|
|
@findex vc-state-refresh
|
|
To update the VC state information for the file visited in the
|
|
current buffer, use the command @code{vc-refresh-state}. This command
|
|
is useful when you perform version control commands outside Emacs
|
|
(e.g., from the shell prompt), or if you put the buffer's file under a
|
|
different version control system, or remove it from version control
|
|
entirely.
|
|
|
|
@cindex VC commands, in Dired buffers
|
|
@cindex filesets, VC, in Dired buffers
|
|
VC is also enabled automatically in Dired buffers (@pxref{Dired})
|
|
showing directories whose files are controlled by a VCS@. All VC
|
|
commands described in this section can be invoked from any Dired
|
|
buffer showing a directory with VC-controlled files; any files that
|
|
are marked in a Dired buffer (@pxref{Marks vs Flags}) are considered
|
|
to belong to the current fileset, and VC commands operate on the files
|
|
in this fileset. This allows you to construct VC filesets including
|
|
any files you want, regardless of their VC state. (If no files are
|
|
marked when a VC command is invoked from a Dired buffer, the file
|
|
shown on the current line in the buffer is considered the only file in
|
|
the fileset.)
|
|
|
|
@menu
|
|
* Introduction to VC:: How version control works in general.
|
|
* VC Mode Line:: How the mode line shows version control status.
|
|
* Basic VC Editing:: How to edit a file under version control.
|
|
* Log Buffer:: Features available in log entry buffers.
|
|
* Registering:: Putting a file under version control.
|
|
* 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
|
|
* Miscellaneous VC:: Various other commands and features of VC.
|
|
* Customizing VC:: Variables that change VC's behavior.
|
|
@end ifnottex
|
|
@end menu
|
|
|
|
@node Introduction to VC
|
|
@subsection Introduction to Version Control
|
|
|
|
VC allows you to use a version control system from within Emacs,
|
|
integrating the version control operations smoothly with editing. It
|
|
provides a uniform interface for common operations in many version
|
|
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 VC, 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
|
|
this section if you are already familiar with the version control system
|
|
you want to use.
|
|
|
|
@menu
|
|
* Why Version Control?:: Understanding the problems it addresses.
|
|
* Version Control Systems:: Supported version control back-end systems.
|
|
* VCS Concepts:: Words and concepts related to version control.
|
|
* VCS Merging:: How file conflicts are handled.
|
|
* VCS Changesets:: How changes are grouped.
|
|
* VCS Repositories:: Where version control repositories are stored.
|
|
* Types of Log File:: The VCS log in contrast to the ChangeLog.
|
|
@end menu
|
|
|
|
@node Why Version Control?
|
|
@subsubsection Understanding the Problems it Addresses
|
|
|
|
Version control systems provide you with three important
|
|
capabilities:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@dfn{Reversibility}: the ability to back up to a previous state if you
|
|
discover that some modification you did was a mistake or a bad idea.
|
|
|
|
@item
|
|
@dfn{Concurrency}: the ability to have many people modifying the same
|
|
collection of files knowing that conflicting modifications can be
|
|
detected and resolved.
|
|
|
|
@item
|
|
@dfn{History}: the ability to attach historical data to your data,
|
|
such as explanatory comments about the intention behind each change.
|
|
Even for a programmer working solo, change histories are an important
|
|
aid to memory; for a multi-person project, they are a vitally
|
|
important form of communication among developers.
|
|
@end itemize
|
|
|
|
@node Version Control Systems
|
|
@subsubsection Supported Version Control Systems
|
|
|
|
@cindex back end (version control)
|
|
VC currently works with many different version control systems,
|
|
which it refers to as @dfn{back ends}:
|
|
|
|
@itemize @bullet
|
|
|
|
@cindex git
|
|
@item
|
|
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 CVS
|
|
@item
|
|
CVS is the free version control system that was, until circa 2008,
|
|
used by the majority of free software projects. Since then, it has
|
|
been superseded by newer systems. CVS allows concurrent multi-user
|
|
development either locally or over the network. Unlike newer systems,
|
|
it lacks support for atomic commits and file moving/renaming. VC
|
|
supports all basic editing operations under CVS.
|
|
|
|
@cindex SVN
|
|
@cindex Subversion
|
|
@item
|
|
Subversion (svn) is a free version control system designed to be
|
|
similar to CVS but without its problems (e.g., it supports atomic
|
|
commits of filesets, and versioning of directories, symbolic links,
|
|
meta-data, renames, copies, and deletes).
|
|
|
|
@cindex SCCS
|
|
@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
|
|
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
|
|
some reason, you cannot use a more recent and better-designed version
|
|
control system.
|
|
|
|
@cindex RCS
|
|
@item
|
|
RCS is the free version control system around which VC was initially
|
|
built. It is relatively primitive: it cannot be used over the
|
|
network, and works at the level of individual files. Almost
|
|
everything you can do with RCS can be done through VC.
|
|
|
|
@cindex hg
|
|
@cindex Mercurial
|
|
@item
|
|
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 decentralized version control system that supports
|
|
both repository-based and decentralized versioning. VC supports most
|
|
basic editing operations under Bazaar.
|
|
|
|
@cindex SRC
|
|
@cindex src
|
|
@item
|
|
SRC (src) is RCS, reloaded---a specialized version-control system
|
|
designed for single-file projects worked on by only one person. It
|
|
allows multiple files with independent version-control histories to
|
|
exist in one directory, and is thus particularly well suited for
|
|
maintaining small documents, scripts, and dotfiles. While it uses RCS
|
|
for revision storage, it presents a modern user interface featuring
|
|
lockless operation and integer sequential version numbers. VC
|
|
supports almost all SRC operations.
|
|
@end itemize
|
|
|
|
@node VCS Concepts
|
|
@subsubsection Concepts of Version Control
|
|
|
|
@cindex repository
|
|
@cindex registered file
|
|
When a file is under version control, we say that it is
|
|
@dfn{registered} in the version control system. The system has a
|
|
@dfn{repository} which stores both the file's present state and its
|
|
change history---enough to reconstruct the current version or any
|
|
earlier version. The repository also contains other information, such
|
|
as @dfn{log entries} that describe the changes made to each file.
|
|
|
|
@cindex work file
|
|
@cindex checking out files
|
|
The copy of a version-controlled file that you actually edit is
|
|
called the @dfn{work file}. You can change each work file as you
|
|
would an ordinary file. After you are done with a set of changes, you
|
|
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
|
|
version control system keeps track of all past revisions and the
|
|
changes that were made in each revision. Each revision is named by a
|
|
@dfn{revision ID}, whose format depends on the version control system;
|
|
in the simplest case, it is just an integer.
|
|
|
|
To go beyond these basic concepts, you will need to understand three
|
|
aspects in which version control systems differ. As explained in the
|
|
next three sections, they can be lock-based or merge-based; file-based
|
|
or changeset-based; and centralized or decentralized. VC handles all
|
|
these modes of operation, but it cannot hide the differences.
|
|
|
|
@node VCS Merging
|
|
@subsubsection Merge-based vs Lock-based Version Control
|
|
|
|
A version control system typically has some mechanism to coordinate
|
|
between users who want to change the same file. There are two ways to
|
|
do this: merging and locking.
|
|
|
|
@cindex merging-based version
|
|
In a version control system that uses merging, each user may modify
|
|
a work file at any time. The system lets you @dfn{merge} your work
|
|
file, which may contain changes that have not been committed, with the
|
|
latest changes that others have committed.
|
|
|
|
@cindex locking-based version
|
|
Older version control systems use a @dfn{locking} scheme instead.
|
|
Here, work files are normally read-only. To edit a file, you ask the
|
|
version control system to make it writable for you by @dfn{locking}
|
|
it; only one user can lock a given file at any given time. This
|
|
procedure is analogous to, but different from, the locking that Emacs
|
|
uses to detect simultaneous editing of ordinary files
|
|
(@pxref{Interlocking}). When you commit your changes, that unlocks
|
|
the file, and the work file becomes read-only again. Other users may
|
|
then lock the file to make their own changes.
|
|
|
|
Both locking and merging systems can have problems when multiple
|
|
users try to modify the same file at the same time. Locking systems
|
|
have @dfn{lock conflicts}; a user may try to check a file out and be
|
|
unable to because it is locked. In merging systems, @dfn{merge
|
|
conflicts} happen when you commit a change to a file that conflicts
|
|
with a change committed by someone else after your checkout. Both
|
|
kinds of conflict have to be resolved by human judgment and
|
|
communication. Experience has shown that merging is superior to
|
|
locking, both in convenience to developers and in minimizing the
|
|
number and severity of conflicts that actually occur.
|
|
|
|
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.
|
|
Decentralized version control systems, such as Git and Mercurial, are
|
|
exclusively merging-based.
|
|
|
|
VC mode supports both locking and merging version control. The
|
|
terms ``commit'' and ``update'' are used in newer version control
|
|
systems; older lock-based systems use the terms ``check in'' and
|
|
``check out''. VC hides the differences between them as much as
|
|
possible.
|
|
|
|
@node VCS Changesets
|
|
@subsubsection Changeset-based vs File-based Version Control
|
|
|
|
@cindex file-based version control
|
|
On SCCS, RCS, CVS, and other early version control systems (and also
|
|
in SRC), version control operations are @dfn{file-based}: each file
|
|
has its own comment and revision history separate from that of all
|
|
other files. Newer systems, beginning with Subversion, are
|
|
@dfn{changeset-based}: a commit may include changes to several files,
|
|
and the entire set of changes is handled as a unit. Any comment
|
|
associated with the change does not belong to a single file, but to
|
|
the changeset itself.
|
|
|
|
@cindex changeset-based version control
|
|
Changeset-based version control is more flexible and powerful than
|
|
file-based version control; usually, when a change to multiple files
|
|
has to be reversed, it's good to be able to easily identify and remove
|
|
all of it.
|
|
|
|
@node VCS Repositories
|
|
@subsubsection Decentralized vs Centralized Repositories
|
|
|
|
@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, Subversion, and SRC 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{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
|
|
network of peer repositories, is not something VC has to care about.
|
|
|
|
@node Types of Log File
|
|
@subsubsection Types of Log File
|
|
@cindex types of log file
|
|
@cindex log File, types of
|
|
@cindex version control log
|
|
|
|
Projects that use a version control system can have two types of log
|
|
for changes. One is the log maintained by the version control system:
|
|
each time you commit a change, you fill out a @dfn{log entry} for the
|
|
change (@pxref{Log Buffer}). This is called the @dfn{version control
|
|
log}.
|
|
|
|
The other kind of log is the file @file{ChangeLog} (@pxref{Change
|
|
Log}). It provides a chronological record of all changes to a large
|
|
portion of a program---typically one directory and its subdirectories.
|
|
A small program would use one @file{ChangeLog} file; a large program
|
|
may have a @file{ChangeLog} file in each major directory.
|
|
@xref{Change Log}. Programmers have used change logs since long
|
|
before version control systems.
|
|
|
|
Changeset-based version systems typically maintain a changeset-based
|
|
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. 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
|
|
files one way and some files the other way. Each project has its
|
|
policy, which you should follow.
|
|
|
|
When the policy is to use both, you typically want to write an entry
|
|
for each change just once, then put it into both logs. You can write
|
|
the entry in @file{ChangeLog}, then copy it to the log buffer with
|
|
@kbd{C-c C-a} when committing the change (@pxref{Log Buffer}). Or you
|
|
can write the entry in the log buffer while committing the change
|
|
(with the help of @kbd{C-c C-w}), and later use the @kbd{C-x v a}
|
|
command to copy it to @file{ChangeLog}
|
|
@iftex
|
|
(@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
|
|
@end iftex
|
|
@ifnottex
|
|
(@pxref{Change Logs and VC}).
|
|
@end ifnottex
|
|
|
|
@node VC Mode Line
|
|
@subsection Version Control and the Mode Line
|
|
@cindex VC mode line indicator
|
|
|
|
When you visit a file that is under version control, Emacs indicates
|
|
this on the mode line. For example, @samp{Bzr-1223} says that Bazaar
|
|
is used for that file, and the current revision ID is 1223.
|
|
|
|
@cindex version control status
|
|
The character between the back-end name and the revision ID
|
|
indicates the @dfn{version control status} of the work file. In a
|
|
merge-based version control system, a @samp{-} character indicates
|
|
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, or that it is versioned but also
|
|
@dfn{ignored}, something that usually should not happen (@pxref{VC
|
|
Ignore}). Finally, @samp{?} means that the file is under version
|
|
control, but is missing from the working tree.
|
|
|
|
In a lock-based system, @samp{-} indicates an unlocked file, and
|
|
@samp{:} a locked file; if the file is locked by another user (for
|
|
instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
|
|
@samp{@@} means that the file was locally added, but not yet committed
|
|
to the master repository.
|
|
|
|
On a graphical display, you can move the mouse over this mode line
|
|
indicator to pop up a tool-tip, which displays a more verbose
|
|
description of the version control status. Pressing @kbd{mouse-1}
|
|
over the indicator pops up a menu of VC commands, identical to
|
|
@samp{Tools / Version Control} on the menu bar.
|
|
|
|
@vindex auto-revert-check-vc-info
|
|
When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is
|
|
under version control, it updates the version control information in
|
|
the mode line. However, Auto Revert mode may not properly update this
|
|
information if the version control status changes without changes to
|
|
the work file, from outside the current Emacs session. If you set
|
|
@code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates
|
|
the version control status information every
|
|
@code{auto-revert-interval} seconds, even if the work file itself is
|
|
unchanged. The resulting CPU usage depends on the version control
|
|
system, but is usually not excessive.
|
|
|
|
@node Basic VC Editing
|
|
@subsection Basic Editing under Version Control
|
|
|
|
@cindex filesets, VC
|
|
@cindex VC filesets
|
|
Most VC commands operate on @dfn{VC filesets}. A VC fileset is a
|
|
collection of one or more files that a VC operation acts upon. When
|
|
you type VC commands in a buffer visiting a version-controlled file,
|
|
the VC fileset is simply that one file. When you type them in a VC
|
|
Directory buffer, and some files in it are marked, the VC fileset
|
|
consists of the marked files (@pxref{VC Directory Mode}). Likewise,
|
|
when you invoke a VC command from a Dired buffer, the VC fileset
|
|
consists of the marked files (@pxref{Marks vs Flags}), defaulting to
|
|
the file shown on the current line if no files are marked.
|
|
|
|
With modern changeset-based version control systems (@pxref{VCS
|
|
Changesets}), such as Git, Mercurial, and Bazaar, 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; thus, committing a fileset generates one revision for
|
|
each changed file in the fileset.
|
|
|
|
@table @kbd
|
|
@item C-x v v
|
|
Perform the next appropriate version control operation on the current
|
|
VC fileset.
|
|
@end table
|
|
|
|
@findex vc-next-action
|
|
@kindex 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 into it.
|
|
The precise actions for each situation are described in detail in the
|
|
following subsections. You can use @kbd{C-x v v} either in a
|
|
file-visiting buffer, in a Dired buffer, or in a VC Directory buffer;
|
|
in the latter two cases the command operates on the fileset consisting
|
|
of the marked files. You can also use @kbd{C-x v v}, in a buffer with
|
|
patches under Diff Mode (@pxref{Diff Mode}), in which case the command
|
|
operates on the files whose diffs are shown in the buffer.
|
|
|
|
Note that VC filesets are distinct from the named filesets used
|
|
for viewing and visiting files in functional groups
|
|
(@pxref{Filesets}). Unlike named filesets, VC filesets are not named
|
|
and don't persist across sessions.
|
|
|
|
@menu
|
|
* VC With A Merging VCS:: Without locking: default mode for Git, Hg, SVN, CVS.
|
|
* VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS.
|
|
* Advanced C-x v v:: Advanced features available with a prefix argument.
|
|
@end menu
|
|
|
|
@node VC With A Merging VCS
|
|
@subsubsection Basic Version Control with Merging
|
|
|
|
With a modern merging-based version control system (such as Git and Hg;
|
|
@pxref{VCS Merging}), @kbd{C-x v v} does the following when invoked
|
|
from a buffer that visits a version-controlled file or a VC Directory
|
|
or Dired buffer:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
If there is more than one file in the VC fileset and the files have
|
|
inconsistent version control statuses, signal an error. (Note,
|
|
however, that a fileset is allowed to include both newly-added files
|
|
and modified files; @pxref{Registering}.) Also signal an error if the
|
|
files in the fileset are missing (removed from the filesystem, but
|
|
still tracked by version control), or are ignored by version control.
|
|
|
|
@item
|
|
If every file in the VC fileset is registered and unchanged with
|
|
respect to the last revision, do nothing.
|
|
|
|
@item
|
|
If none of the files in the VC fileset are registered with a version
|
|
control system, register the newly-added files in the VC fileset,
|
|
i.e., place them 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.
|
|
You can also specify the system explicitly, see @ref{Advanced C-x v
|
|
v}. Note that registering the files doesn't commit them; you must
|
|
invoke @w{@kbd{C-x v v}} again to commit, see below.
|
|
|
|
@item
|
|
If every file in the VC fileset has been either newly-added or
|
|
modified, commit the changed files. To do this, Emacs pops up a
|
|
@file{*vc-log*} buffer; type the desired log entry for the changes,
|
|
followed by @kbd{C-c C-c} to commit. @xref{Log Buffer}.
|
|
|
|
With modern decentralized version control systems (Git, Mercurial,
|
|
etc.), the changes are committed locally and not automatically
|
|
propagated to the upstream repository (which is usually on a remote
|
|
host). In these cases, if the repository has been changed since your
|
|
last update, the commit may fail. In that case, you must update from
|
|
upstream and then try again. Use @kbd{C-x v +} (@pxref{Pulling /
|
|
Pushing}) or @kbd{C-x v m} (@pxref{Merging}) for that.
|
|
|
|
With a centralized version control system, if the commit fails due to
|
|
upstream changes, type @kbd{C-x v v} again to merge in the upstream
|
|
repository changes.
|
|
|
|
@item
|
|
Finally, if you are using a centralized version control system, if any
|
|
file in the VC fileset is outdated with respect to the upstream
|
|
repository, offer to update the fileset from the repository.
|
|
@end itemize
|
|
|
|
These rules also apply when you use RCS in its non-locking mode,
|
|
except that changes are not automatically merged from the repository.
|
|
Nothing informs you if another user has committed changes in the same
|
|
file since you began editing it; when you commit your revision, that
|
|
other user's changes are removed (however, they remain in the
|
|
repository and are thus not irrevocably lost). Therefore, you must
|
|
verify that the current revision is unchanged before committing your
|
|
changes. In addition, locking is possible with RCS even in this mode:
|
|
@kbd{C-x v v} with an unmodified file locks the file, just as it does
|
|
with RCS in its normal locking mode (@pxref{VC With A Locking VCS}).
|
|
|
|
If @kbd{C-x v v} is invoked from a buffer under Diff Mode, the
|
|
command assumes the buffer holds a set of patches for one or more
|
|
files. It then applies the changes to the respective files and
|
|
commits the changes after popping up the @file{*vc-log*} buffer to
|
|
allow you to type a suitable commit log message.
|
|
|
|
@node VC With A Locking VCS
|
|
@subsubsection Basic Version Control with Locking
|
|
|
|
With a locking-based version control system (such as SCCS, and RCS in
|
|
its default mode), @kbd{C-x v v} does the following:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
If there is more than one file in the VC fileset and the files have
|
|
inconsistent version control statuses, signal an error. Also signal
|
|
an error if the files in the fileset are missing (removed from the
|
|
filesystem, but still tracked by version control).
|
|
|
|
@item
|
|
If each file in the VC fileset is not registered with a version
|
|
control system, register the newly-added files in the fileset.
|
|
@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. You can also specify the system
|
|
explicitly, see @ref{Advanced C-x v v}.
|
|
|
|
@item
|
|
If each file is registered and unlocked, check the files out: lock
|
|
each one and make it writable, so that you can begin to edit it.
|
|
|
|
@item
|
|
If each file is locked by you and contains changes, commit (a.k.a.@:
|
|
``check-in'') 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}).
|
|
|
|
@item
|
|
If each file is locked by you, but you have not changed it, release
|
|
the lock and make the file read-only again. This undoes previous
|
|
check-out operation for files that were not changed since the
|
|
checkout.
|
|
|
|
@item
|
|
If each file is locked by another user, ask whether you want to
|
|
steal the lock. If you say yes, the file becomes locked by you,
|
|
and a warning message is sent to the user who had formerly locked the
|
|
file.
|
|
|
|
@item
|
|
If files in the fileset are unlocked, but have changes with respect to
|
|
their last revision, offer to claim the lock for each such file or to
|
|
revert the file to the last checked-in revision. (This situation is
|
|
exceptional and should not normally happen.)
|
|
@end itemize
|
|
|
|
These rules also apply when you use CVS in locking mode, except
|
|
that CVS does not support stealing locks.
|
|
|
|
@node Advanced C-x v v
|
|
@subsubsection Advanced Control in @kbd{C-x v v}
|
|
|
|
@cindex revision ID in version control
|
|
When you give a prefix argument to @code{vc-next-action} (@kbd{C-u
|
|
C-x v v}), it still performs the next logical version control
|
|
operation, but accepts additional arguments to specify precisely how
|
|
to do the operation.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@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
|
|
Otherwise, if using CVS, RCS or SRC, you can specify a revision ID.
|
|
|
|
If the fileset is modified (or locked), this makes Emacs commit the
|
|
files 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 out 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 (a.k.a.@: ``head'') revision on
|
|
the current branch.
|
|
|
|
Specifying revision ID in this manner is silently ignored by 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
|
|
@subsection Features of the Log Entry Buffer
|
|
|
|
@kindex 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
|
|
@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
|
|
@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}
|
|
(@pxref{Hooks}).
|
|
|
|
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>
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Apart from the @samp{Author} header, Emacs recognizes the headers
|
|
@samp{Summary} (a one-line summary of the changeset), @samp{Date} (a
|
|
manually-specified commit time), and @samp{Fixes} (a reference to a
|
|
bug fixed by the change). Not all version control systems recognize
|
|
all headers. 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
|
|
@kindex C-c C-d @r{(Log Edit mode)}
|
|
@findex log-edit-show-diff
|
|
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-w @r{(Log Edit mode)}
|
|
@findex log-edit-generate-changelog-from-diff
|
|
@vindex diff-add-log-use-relative-names
|
|
To help generate ChangeLog entries, type @kbd{C-c C-w}
|
|
(@code{log-edit-generate-changelog-from-diff}), to generate skeleton
|
|
ChangeLog entries, listing all changed file and function names based
|
|
on the diff of the VC fileset. Consecutive entries left empty will be
|
|
combined by @kbd{M-q} (@code{fill-paragraph}). By default the
|
|
skeleton will just include the file name, without any leading
|
|
directories. If you wish to prepend the leading directories up to the
|
|
VC root, customize @code{diff-add-log-use-relative-names}.
|
|
|
|
@kindex C-c C-a @r{(Log Edit mode)}
|
|
@findex log-edit-insert-changelog
|
|
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 @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
|
|
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 @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
|
|
any time to complete the commit.
|
|
|
|
@kindex M-n @r{(Log Edit mode)}
|
|
@kindex M-p @r{(Log Edit mode)}
|
|
@kindex M-s @r{(Log Edit mode)}
|
|
@kindex M-r @r{(Log Edit mode)}
|
|
You can also browse the history of previous log entries to duplicate
|
|
a commit comment. This can be useful when you want to make several
|
|
commits with similar comments. The commands @kbd{M-n}, @kbd{M-p},
|
|
@kbd{M-s} and @kbd{M-r} for doing this work just like the minibuffer
|
|
history commands (@pxref{Minibuffer History}), except that they are
|
|
used outside the minibuffer.
|
|
|
|
@node Registering
|
|
@subsection Registering a File for Version Control
|
|
|
|
@table @kbd
|
|
@item C-x v i
|
|
Register the visited file for version control.
|
|
@end table
|
|
|
|
@kindex C-x v i
|
|
@findex vc-register
|
|
The command @kbd{C-x v i} (@code{vc-register}) @dfn{registers} each
|
|
file in the current VC fileset, placing it under version control.
|
|
This is essentially equivalent to the action of @kbd{C-x v v} on an
|
|
unregistered VC fileset (@pxref{Basic VC Editing}), except that if the
|
|
VC fileset is already registered, @kbd{C-x v i} signals an error
|
|
whereas @kbd{C-x v v} performs some other action.
|
|
|
|
To register a file, Emacs must choose a version control system. For
|
|
a multi-file VC fileset, the VC Directory buffer specifies the system
|
|
to use (@pxref{VC Directory Mode}). For a single-file VC fileset, if
|
|
the file's directory already contains files registered in a version
|
|
control system, or if the directory is part of a directory tree
|
|
controlled by a version control system, Emacs chooses that system. In
|
|
the event that more than one version control system is applicable,
|
|
Emacs uses the one that appears first in the variable
|
|
@iftex
|
|
@code{vc-handled-backends}.
|
|
@end iftex
|
|
@ifnottex
|
|
@code{vc-handled-backends} (@pxref{Customizing VC}).
|
|
@end ifnottex
|
|
If Emacs cannot find a version control system to register the file
|
|
under, it prompts for a repository type, creates a new repository, and
|
|
registers the file into that repository.
|
|
|
|
@cindex added files, VC
|
|
@cindex files added to VCS
|
|
With most version control systems, registering a file with
|
|
@w{@kbd{C-x v i}} or @w{@kbd{C-x v v}} adds it to the working tree,
|
|
but does not commit it, i.e., doesn't add it to the repository. Such
|
|
files are labeled as @dfn{added} in the VC Directory buffer, and the
|
|
mode line of the buffers visiting such files shows a revision ID of
|
|
@samp{@@@@}. To make the registration take effect in the repository,
|
|
you must commit the newly-added files (@pxref{Basic VC Editing}).
|
|
Note that a single commit can include both file additions and edits to
|
|
files already known to the VCS.
|
|
|
|
With a locking-based version control system (@pxref{VCS Merging}),
|
|
registering a file leaves it unlocked and read-only. Type @kbd{C-x v
|
|
v} to check-out the file and start editing it.
|
|
|
|
@node Old Revisions
|
|
@subsection Examining And Comparing Old Revisions
|
|
|
|
@table @kbd
|
|
@item C-x v =
|
|
Compare the work files in the current VC fileset with the versions you
|
|
started from (@code{vc-diff}). With a prefix argument, prompt for two
|
|
revisions of the current VC fileset and compare them. You can also
|
|
call this command from a Dired buffer (@pxref{Dired}).
|
|
|
|
@ifnottex
|
|
@item M-x vc-ediff
|
|
Like @kbd{C-x v =}, but using Ediff. @xref{Top,, Ediff, ediff, The
|
|
Ediff Manual}.
|
|
@end ifnottex
|
|
|
|
@item C-x v D
|
|
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
|
|
buffer (@code{vc-revision-other-window}).
|
|
|
|
@item C-x v g
|
|
Display an annotated version of the current file: for each line, show
|
|
the latest revision in which it was modified (@code{vc-annotate}).
|
|
@end table
|
|
|
|
@findex vc-diff
|
|
@kindex C-x v =
|
|
@kbd{C-x v =} (@code{vc-diff}) displays a @dfn{diff} which compares
|
|
each work file in the current VC fileset to the version(s) from which
|
|
you started editing. The diff is displayed in another window, in a
|
|
Diff mode buffer (@pxref{Diff Mode}) named @file{*vc-diff*}. The
|
|
usual Diff mode commands are available in this buffer. In particular,
|
|
the @kbd{g} (@code{revert-buffer}) command performs the file
|
|
comparison again, generating a new diff.
|
|
|
|
@kindex C-u C-x v =
|
|
To compare two arbitrary revisions of the current VC fileset, call
|
|
@code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}. This
|
|
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
|
|
revision IDs for different files would not be related in any
|
|
meaningful way.
|
|
|
|
Instead of the revision ID, some version control systems let you
|
|
specify revisions in other formats. For instance, under Bazaar you
|
|
can enter @samp{date:yesterday} for the argument to @kbd{C-u C-x v =}
|
|
(and related commands) to specify the first revision committed after
|
|
yesterday. See the documentation of the version control system for
|
|
details.
|
|
|
|
If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a Dired buffer
|
|
(@pxref{Dired}), the file listed on the current line is treated as the
|
|
current VC fileset. The VC fileset can also include several marked files.
|
|
|
|
@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}.
|
|
@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 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.
|
|
|
|
@findex vc-root-version-diff
|
|
@kindex C-u C-x v D
|
|
To compare two arbitrary revisions of the whole trees, call
|
|
@code{vc-root-diff} with a prefix argument: @kbd{C-u C-x v D}. This
|
|
prompts for two revision IDs (@pxref{VCS Concepts}), and displays a
|
|
diff between those versions of the entire version-controlled directory
|
|
trees (RCS, SCCS, CVS, and SRC do not support this feature).
|
|
|
|
@vindex vc-diff-switches
|
|
You can customize the @command{diff} options that @kbd{C-x v =} and
|
|
@kbd{C-x v D} use for generating diffs. The options used are taken
|
|
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 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
|
|
whose @code{diff} implementations do not accept common diff options,
|
|
such as Subversion.
|
|
|
|
@findex vc-revision-other-window
|
|
@kindex C-x v ~
|
|
To directly examine an older version of a file, visit the work file
|
|
and type @kbd{C-x v ~ @var{revision} @key{RET}}
|
|
(@code{vc-revision-other-window}). This retrieves the file version
|
|
corresponding to @var{revision}, saves it to
|
|
@file{@var{filename}.~@var{revision}~}, and visits it in a separate
|
|
window.
|
|
|
|
@findex vc-annotate
|
|
@vindex vc-annotate-background-mode
|
|
@kindex C-x v g
|
|
Many version control systems allow you to view files @dfn{annotated}
|
|
with per-line revision information, by typing @kbd{C-x v g}
|
|
(@code{vc-annotate}). This creates a new ``annotate'' buffer
|
|
displaying the file's text, with each line colored to show how old it
|
|
is. Red text is new, blue is old, and intermediate colors indicate
|
|
intermediate ages. By default, the color is scaled over the full
|
|
range of ages, such that the oldest changes are blue, and the newest
|
|
changes are red. If the variable @code{vc-annotate-background-mode}
|
|
is non-@code{nil}, the colors expressing the age of each line are
|
|
applied to the background color, leaving the foreground at its default
|
|
color.
|
|
|
|
@vindex vc-annotate-switches
|
|
You can customize the @code{annotate} options that @kbd{C-x v g}
|
|
uses by customizing @code{vc-@var{backend}-annotate-switches} and
|
|
@code{vc-annotate-switches}. They function similarly to
|
|
@code{vc-@var{backend}-diff-switches} and @code{vc-diff-switches},
|
|
described above.
|
|
|
|
When you give a prefix argument to @kbd{C-x v g}, Emacs reads two
|
|
arguments using the minibuffer: the revision to display and annotate
|
|
(instead of the current file contents), and the time span in days the
|
|
color range should cover.
|
|
|
|
From the ``annotate'' buffer, these and other color scaling options are
|
|
available from the @samp{VC-Annotate} menu. In this buffer, you can
|
|
also use the following keys to browse the annotations of past revisions,
|
|
view diffs, or view log entries:
|
|
|
|
@table @kbd
|
|
@item p
|
|
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
|
|
currently annotated. A numeric prefix argument is a repeat count.
|
|
|
|
@item j
|
|
Annotate the revision indicated by the current line.
|
|
|
|
@item a
|
|
Annotate the revision before the one indicated by the current line.
|
|
This is useful to see the state the file was in before the change on
|
|
the current line was made.
|
|
|
|
@item f
|
|
Show in a buffer the file revision indicated by the current line.
|
|
|
|
@item d
|
|
Display the diff between the current line's revision and the previous
|
|
revision. This is useful to see what the current line's revision
|
|
actually changed in the file.
|
|
|
|
@item D
|
|
Display the diff between the current line's revision and the previous
|
|
revision for all files in the changeset (for VC systems that support
|
|
changesets). This is useful to see what the current line's revision
|
|
actually changed in the tree.
|
|
|
|
@item l
|
|
Show the log of the current line's revision. This is useful to see
|
|
the author's description of the changes in the revision on the current
|
|
line.
|
|
|
|
@item w
|
|
Annotate the working revision---the one you are editing. If you used
|
|
@kbd{p} and @kbd{n} to browse to other revisions, use this key to
|
|
return to your working revision.
|
|
|
|
@item v
|
|
Toggle the annotation visibility. This is useful for looking just at
|
|
the file contents without distraction from the annotations.
|
|
@end table
|
|
|
|
@node VC Change Log
|
|
@subsection VC Change Log
|
|
@cindex VC change log
|
|
|
|
@table @kbd
|
|
@item C-x v l
|
|
Display the change history for the current fileset
|
|
(@code{vc-print-log}).
|
|
|
|
@item C-x v L
|
|
Display the change history for the current repository
|
|
(@code{vc-print-root-log}).
|
|
|
|
@item C-x v b l
|
|
Display the change history for another branch
|
|
(@code{vc-print-branch-log}).
|
|
|
|
@item C-x v I
|
|
Display the changes that a ``pull'' operation will retrieve
|
|
(@code{vc-log-incoming}).
|
|
|
|
@item C-x v O
|
|
Display the changes that will be sent by the next ``push'' operation
|
|
(@code{vc-log-outgoing}).
|
|
|
|
@item C-x v h
|
|
Display the history of changes made in the region of file visited by
|
|
the current buffer (@code{vc-region-history}).
|
|
|
|
@item M-x vc-log-search @key{RET}
|
|
Search the change history for a specified pattern.
|
|
@end table
|
|
|
|
@kindex C-x v l
|
|
@findex vc-print-log
|
|
@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 fileset in the long form, 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}). When invoked from a buffer visiting a file, the current
|
|
fileset consists of that single file, and point in the displayed
|
|
@file{*vc-change-log*} buffer is centered at the revision of that
|
|
file. When invoked from a VC Directory buffer (@pxref{VC Directory
|
|
Mode}) or from a Dired buffer (@pxref{Dired}), the fileset consists of
|
|
all the marked files, defaulting to the file shown on the current line
|
|
in the directory buffer if no file is marked.
|
|
|
|
If the fileset includes one or more directories, the resulting
|
|
@file{*vc-change-log*} buffer shows a short log of changes (one line
|
|
for each change), if the VC backend supports that; otherwise it shows
|
|
the log in the long form.
|
|
|
|
With a prefix argument, the command prompts for the revision to
|
|
center on in the @file{*vc-change-log*} buffer and for the maximum
|
|
number of revisions to display.
|
|
|
|
@kindex C-x v L
|
|
@findex vc-print-root-log
|
|
@findex log-view-toggle-entry-display
|
|
@kbd{C-x v L} (@code{vc-print-root-log}) displays a
|
|
@file{*vc-change-log*} buffer showing the history of the entire
|
|
version-controlled directory tree (RCS, SCCS, CVS, and SRC do not
|
|
support this feature). With a prefix argument, the command prompts
|
|
for the maximum number of revisions to display. A numeric prefix
|
|
argument specifies the maximum number of revisions without prompting.
|
|
When the numeric prefix argument is 1, as in @w{@kbd{C-1 C-x v L}} or
|
|
@w{@kbd{C-u 1 C-x v L}}, the command prompts for the revision ID, and
|
|
displays the log entry of that revision together with the changes
|
|
(diffs) it introduced. (Some less capable version control systems,
|
|
such as RCS and CVS, don't have commands to show a revision log with
|
|
its diffs; for them the command displays only the log entry, and you
|
|
can request to show the diffs by typing @kbd{d} or @kbd{D}, see
|
|
below.)
|
|
|
|
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
|
|
@file{*vc-change-log*} buffer to reveal the entire log entry for the
|
|
revision at point. A second @key{RET} hides it again.
|
|
|
|
@kindex C-x v b l
|
|
@findex vc-print-branch-log
|
|
@kbd{C-x v b l @var{branch-name} @key{RET}} (@code{vc-print-branch-log})
|
|
displays a @file{*vc-change-log*} buffer showing the history of the
|
|
version-controlled directory tree, like @code{vc-print-root-log} does,
|
|
but it shows the history of a branch other than the current one; it
|
|
prompts for the branch whose history to display.
|
|
|
|
@kindex C-x v I
|
|
@kindex C-x v O
|
|
@findex vc-log-incoming
|
|
@findex vc-log-outgoing
|
|
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
|
|
remote location (@pxref{Pulling / Pushing}). This other remote location 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 remote location. Similarly, @kbd{C-x v O}
|
|
(@code{vc-log-outgoing}) shows the changes that will be sent to
|
|
another remote location, the next time you run the push command; with a
|
|
prefix argument, it prompts for a specific destination that
|
|
in case of some version control system can be a branch name.
|
|
|
|
@cindex VC log buffer, commands in
|
|
@cindex vc-log buffer
|
|
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}):
|
|
|
|
@table @kbd
|
|
@item p
|
|
Move to the previous revision entry. (Revision entries in the log
|
|
buffer are usually in reverse-chronological order, so the previous
|
|
revision-item usually corresponds to a newer revision.) A numeric
|
|
prefix argument is a repeat count.
|
|
|
|
@item n
|
|
Move to the next revision entry. A numeric prefix argument is a
|
|
repeat count.
|
|
|
|
@item a
|
|
Annotate the revision on the current line (@pxref{Old Revisions}).
|
|
|
|
@item e
|
|
Modify the change comment displayed at point. Note that not all VC
|
|
systems support modifying change comments.
|
|
|
|
@item f
|
|
Visit the revision indicated at the current line.
|
|
|
|
@item d
|
|
Display a diff between the revision at point and the next earlier
|
|
revision, for the specific file.
|
|
|
|
@item D
|
|
Display the changeset diff between the revision at point and the next
|
|
earlier revision. This shows the changes to all files made in that
|
|
revision.
|
|
|
|
@item @key{RET}
|
|
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
|
|
@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
|
|
@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, CVS, and SRC do not support this feature.
|
|
|
|
@kindex C-x v h
|
|
@findex vc-region-history
|
|
A useful variant of examining history of changes is provided by the command
|
|
@kbd{vc-region-history} (by default bound to @kbd{C-x v h}), which shows
|
|
a @file{*VC-history*} buffer with the history of changes made in the region
|
|
of the current buffer's file between point and the mark (@pxref{Mark}). The
|
|
history of changes includes the commit log messages and also the
|
|
changes themselves in the Diff format.
|
|
|
|
Invoke this command after marking in the current buffer the region in
|
|
whose changes you are interested. In the @file{*VC-history*} buffer
|
|
it pops up, you can use all of the commands available in the
|
|
@file{*vc-change-log*} buffer described above, and also the commands
|
|
defined by Diff mode (@pxref{Diff Mode}).
|
|
|
|
This command is currently available only with Git and Mercurial (hg).
|
|
|
|
@findex vc-log-search
|
|
The command @code{vc-log-search} allows searching for a pattern in the
|
|
log of changes. It prompts for a pattern (a regular expression), and
|
|
displays all entries in the change history whose log messages match
|
|
the pattern. When invoked with a prefix argument, the command will
|
|
also prompt for a specific VCS shell command to run for this purpose.
|
|
|
|
@node VC Undo
|
|
@subsection Undoing Version Control Actions
|
|
|
|
@table @kbd
|
|
@item C-x v u
|
|
Revert the work file(s) in the current VC fileset to the last revision
|
|
(@code{vc-revert}).
|
|
@end table
|
|
|
|
@kindex C-x v u
|
|
@findex vc-revert
|
|
@vindex vc-revert-show-diff
|
|
If you want to discard all the changes you have made to the current
|
|
VC fileset, type @kbd{C-x v u} (@code{vc-revert}). This will ask you
|
|
for confirmation before discarding the changes. If you agree, the
|
|
fileset is reverted.
|
|
|
|
If @code{vc-revert-show-diff} is non-@code{nil}, this command will
|
|
show you a diff between the work file(s) and the revision from which
|
|
you started editing. Afterwards, the diff buffer will either be
|
|
killed (if this variable is @code{kill}), or the buffer will be buried
|
|
(any other non-@code{nil} value). If you don't want @kbd{C-x v u} to
|
|
show a diff, set this variable to @code{nil} (you can still view the
|
|
diff directly with @kbd{C-x v =}; @pxref{Old Revisions}).
|
|
|
|
On locking-based version control systems, @kbd{C-x v u} leaves files
|
|
unlocked; you must lock again to resume editing. You can also use
|
|
@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
|
|
|
|
@cindex VC Directory buffer
|
|
The @dfn{VC Directory buffer} is a specialized buffer for viewing
|
|
the version control statuses of the files in a directory tree, and
|
|
performing version control operations on those files. In particular,
|
|
it is used to specify multi-file VC filesets for commands like
|
|
@w{@kbd{C-x v v}} to act on (@pxref{VC Directory Commands}).
|
|
|
|
@kindex C-x v d
|
|
@findex vc-dir
|
|
To use the VC Directory buffer, type @kbd{C-x v d} (@code{vc-dir}).
|
|
This reads a directory's name using the minibuffer, and switches to a VC
|
|
Directory buffer for that directory. By default, the buffer is named
|
|
@file{*vc-dir*}. Its contents are described
|
|
@iftex
|
|
below.
|
|
@end iftex
|
|
@ifnottex
|
|
in @ref{VC Directory Buffer}.
|
|
@end ifnottex
|
|
|
|
The @code{vc-dir} command automatically detects the version control
|
|
system to be used in the specified directory. In the event that more
|
|
than one system is being used in the directory, you should invoke the
|
|
command with a prefix argument, @kbd{C-u C-x v d}; this prompts for
|
|
the version control system which the VC Directory buffer should use.
|
|
|
|
@ifnottex
|
|
@cindex PCL-CVS
|
|
@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}.
|
|
@end ifnottex
|
|
|
|
You can also invoke VC commands from Dired buffers (@pxref{Dired}).
|
|
In that case, any VC command you invoke considers the marked files as
|
|
the current fileset (@pxref{Basic VC Editing}), defaulting to the file
|
|
on the current line if no files are marked.
|
|
|
|
@menu
|
|
* Buffer: VC Directory Buffer. What the buffer looks like and means.
|
|
* Commands: VC Directory Commands. Commands to use in a VC directory buffer.
|
|
@end menu
|
|
|
|
@node VC Directory Buffer
|
|
@subsubsection The VC Directory Buffer
|
|
|
|
The VC Directory buffer contains a list of version-controlled files
|
|
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
|
|
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.
|
|
|
|
Here is an example of a VC Directory buffer listing:
|
|
|
|
@smallexample
|
|
@group
|
|
./
|
|
edited configure.ac
|
|
* added README
|
|
unregistered temp.txt
|
|
src/
|
|
* edited src/main.c
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Two work files have been modified but not committed:
|
|
@file{configure.ac} in the current directory, and @file{main.c} in the
|
|
@file{src/} subdirectory. The file named @file{README} has been added
|
|
but is not yet committed, while @file{temp.txt} is not under version
|
|
control (@pxref{Registering}).
|
|
|
|
The @samp{*} characters next to the entries for @file{README} and
|
|
@file{src/main.c} indicate that the user has marked these files as
|
|
the current VC fileset
|
|
@iftex
|
|
(see below).
|
|
@end iftex
|
|
@ifnottex
|
|
(@pxref{VC Directory Commands}).
|
|
@end ifnottex
|
|
|
|
The above example is typical for a decentralized version control
|
|
system like Bazaar, Git, or Mercurial. Other systems can show other
|
|
statuses. For instance, CVS shows the @samp{needs-update} status if
|
|
the repository has changes that have not been applied to the work
|
|
file. RCS and SCCS show the name of the user locking a file as its
|
|
status.
|
|
|
|
@ifnottex
|
|
On CVS, the @code{vc-dir} command normally contacts the repository,
|
|
which may be on a remote machine, to check for updates. If you change
|
|
the variable @code{vc-cvs-stay-local} 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
|
|
are working offline or the network is slow.
|
|
@end ifnottex
|
|
|
|
@vindex vc-directory-exclusion-list
|
|
The VC Directory buffer omits subdirectories listed in the variable
|
|
@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
|
|
|
|
Emacs provides several commands for navigating the VC Directory
|
|
buffer, and for marking files as belonging to the current VC
|
|
fileset.
|
|
|
|
@table @kbd
|
|
@item n
|
|
@itemx @key{SPC}
|
|
Move point to the next entry (@code{vc-dir-next-line}).
|
|
|
|
@item p
|
|
Move point to the previous entry (@code{vc-dir-previous-line}).
|
|
|
|
@item @key{TAB}
|
|
Move to the next directory entry (@code{vc-dir-next-directory}).
|
|
|
|
@item S-@key{TAB}
|
|
Move to the previous directory entry
|
|
(@code{vc-dir-previous-directory}).
|
|
|
|
@item @key{RET}
|
|
@itemx f
|
|
Visit the file or directory listed on the current line
|
|
(@code{vc-dir-find-file}).
|
|
|
|
@item o
|
|
Visit the file or directory on the current line, in a separate window
|
|
(@code{vc-dir-find-file-other-window}).
|
|
|
|
@item m
|
|
Mark the file or directory on the current line (@code{vc-dir-mark}),
|
|
putting it in the current VC fileset. If the region is active, mark
|
|
all files in the region.
|
|
|
|
A file cannot be marked with this command if it is already in a marked
|
|
directory, or one of its subdirectories. Similarly, a directory
|
|
cannot be marked with this command if any file in its tree is marked.
|
|
|
|
@item M
|
|
If point is on a file entry, mark all files with the same status; if
|
|
point is on a directory entry, mark all files in that directory tree
|
|
(@code{vc-dir-mark-all-files}). With a prefix argument, mark all
|
|
listed files and directories.
|
|
|
|
@findex vc-dir-mark-by-regexp
|
|
@item % m
|
|
@itemx * %
|
|
You can use this command to mark files by regexp
|
|
(@code{vc-dir-mark-by-regexp}). If given a prefix, unmark files
|
|
instead.
|
|
|
|
@findex vc-dir-mark-registered-files
|
|
@item * r
|
|
You can use this command to mark files that are in one of registered
|
|
states, including edited, added or removed.
|
|
(@code{vc-dir-mark-registered-files}).
|
|
|
|
@item G
|
|
Add the file under point to the list of files that the VC should
|
|
ignore (@code{vc-dir-ignore}). For instance, if the VC is Git, it
|
|
will append this file to the @file{.gitignore} file. If given a
|
|
prefix, do this with all the marked files.
|
|
|
|
@item q
|
|
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
|
|
active, unmark all the files in the region (@code{vc-dir-unmark}).
|
|
|
|
@item U
|
|
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.
|
|
|
|
@item x
|
|
Hide files with @samp{up-to-date} or @samp{ignored} status
|
|
(@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
|
|
@findex vc-dir-mark-all-files
|
|
While in the VC Directory buffer, all the files that you mark with
|
|
@kbd{m} (@code{vc-dir-mark}) or @kbd{M} (@code{vc-dir-mark-all-files})
|
|
are in the current VC fileset. If you mark a directory entry with
|
|
@kbd{m}, all the listed files in that directory tree are in the
|
|
current VC fileset. The files and directories that belong to the
|
|
current VC fileset are indicated with a @samp{*} character in the VC
|
|
Directory buffer, next to their VC status. In this way, you can set
|
|
up a multi-file VC fileset to be acted on by VC commands like
|
|
@w{@kbd{C-x v v}} (@pxref{Basic VC Editing}), @w{@kbd{C-x v =}}
|
|
(@pxref{Old Revisions}), and @w{@kbd{C-x v u}} (@pxref{VC Undo}).
|
|
|
|
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}, @kbd{D}, @kbd{L}, @kbd{G}, @kbd{I}, @kbd{O}, 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}
|
|
status; marking the files; and typing @kbd{v} or @kbd{C-x v v}
|
|
(@code{vc-next-action}). If the version control system is
|
|
changeset-based, Emacs will commit the files in a single revision.
|
|
|
|
While in the VC Directory buffer, you can also perform search and
|
|
replace on the current VC fileset, with the following commands:
|
|
|
|
@table @kbd
|
|
@item S
|
|
Search the fileset (@code{vc-dir-search}).
|
|
|
|
@item Q
|
|
Do a regular expression query replace on the fileset
|
|
(@code{vc-dir-query-replace-regexp}).
|
|
|
|
@item M-s a C-s
|
|
Do an incremental search on the fileset (@code{vc-dir-isearch}).
|
|
|
|
@item M-s a C-M-s
|
|
Do an incremental regular expression search on the fileset
|
|
(@code{vc-dir-isearch-regexp}).
|
|
@end table
|
|
|
|
@noindent
|
|
Apart from acting on multiple files, these commands behave much like
|
|
their single-buffer counterparts (@pxref{Search}).
|
|
|
|
The VC Directory buffer additionally defines some branch-related
|
|
commands starting with the prefix @kbd{b}:
|
|
|
|
@table @kbd
|
|
@item b c
|
|
Create a new branch (@code{vc-create-branch}). @xref{Creating
|
|
Branches}.
|
|
|
|
@item b l
|
|
Prompt for the name of a branch and display the change history of that
|
|
branch (@code{vc-print-branch-log}).
|
|
|
|
@item b s
|
|
Switch to a branch (@code{vc-switch-branch}). @xref{Switching
|
|
Branches}.
|
|
|
|
@item d
|
|
Delete the marked files, or the current file if no marks
|
|
(@code{vc-dir-clean-delete)}. The files will not be marked as
|
|
deleted in the version control system, so this function is mostly
|
|
useful for unregistered files.
|
|
@end table
|
|
|
|
@cindex stashes in version control
|
|
@cindex shelves in version control
|
|
The above commands are also available via the menu bar, and via a
|
|
context menu invoked by @kbd{mouse-2}. Furthermore, some VC backends
|
|
use the menu to provide extra backend-specific commands. For example,
|
|
Git and Bazaar allow you to manipulate @dfn{stashes} and @dfn{shelves}
|
|
(which are a way to temporarily put aside uncommitted changes, and
|
|
bring them back at a later time).
|
|
|
|
@node Branches
|
|
@subsection Version Control Branches
|
|
@cindex branch (version control)
|
|
|
|
One use of version control is to support multiple independent lines
|
|
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
|
|
@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.
|
|
* Pulling / Pushing:: Receiving/sending changes from/to elsewhere.
|
|
* Merging:: Transferring changes between branches.
|
|
* Creating Branches:: How to start a new branch.
|
|
@end menu
|
|
|
|
@node Switching Branches
|
|
@subsubsection Switching between Branches
|
|
|
|
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, branches are normally @dfn{co-located}
|
|
in the same directory, and switching between branches is done using
|
|
the @kbd{git checkout} command, which changes the contents of the
|
|
working tree to match the branch you switch to. Bazaar also supports
|
|
co-located branches, in which case the @kbd{bzr switch} command
|
|
will switch branches in the current directory. With Subversion, you
|
|
switch to another branch using the @kbd{svn switch} command. With
|
|
Mercurial, command @kbd{hg update} is used to switch to another
|
|
branch.
|
|
|
|
@kindex C-x v b s
|
|
@findex vc-switch-branch
|
|
The VC command to switch to another branch in the current directory
|
|
is @kbd{C-x v b s @var{branch-name} @key{RET}} (@code{vc-switch-branch}).
|
|
|
|
On centralized version control systems, you can also 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 Pulling / Pushing
|
|
@subsubsection Pulling/Pushing Changes into/from a Branch
|
|
|
|
@table @kbd
|
|
@cindex push changes to upstream (VC)
|
|
@item C-x v P
|
|
With a decentralized version control system, update another repository
|
|
with locally-committed changes from the current branch (a.k.a.@:
|
|
@dfn{push} changes). This concept does not exist for centralized
|
|
version control systems
|
|
|
|
@cindex pull changes from upstream (VC)
|
|
@item C-x v +
|
|
With a decentralized version control system, update the current branch
|
|
of the local repository by @dfn{pulling in} changes from another
|
|
repository.
|
|
|
|
With a centralized version control system, update the current VC
|
|
fileset from the repository.
|
|
@end table
|
|
|
|
@kindex C-x v P
|
|
@findex vc-push
|
|
@cindex upstream repository
|
|
On a decentralized version control system, the command @kbd{C-x v P}
|
|
(@code{vc-push}) updates another location, commonly known as the
|
|
@dfn{upstream repository}, with locally-committed changes from the
|
|
current branch. With a prefix argument, it prompts for the exact
|
|
version control command to run, which lets you specify where to push
|
|
changes; the default is @kbd{bzr push} with Bazaar, @kbd{git push}
|
|
with Git, and @kbd{hg push} with Mercurial. The default commands
|
|
always push to the repository in the default location determined by
|
|
the version control system from your branch configuration.
|
|
|
|
Prior to pushing, you can use @kbd{C-x v O} (@code{vc-log-outgoing})
|
|
to view a log buffer of the changes to be sent upstream. @xref{VC
|
|
Change Log}.
|
|
|
|
@cindex bound branch (Bazaar VCS)
|
|
This command is currently supported only by Bazaar, Git, and Mercurial.
|
|
The concept of ``pushing'' does not exist for centralized version
|
|
control systems, where this operation is a part of committing a
|
|
changeset, so invoking this command on a centralized VCS signals an
|
|
error. This command also signals an error when attempted in a Bazaar
|
|
@dfn{bound branch}, where committing a changeset automatically pushes
|
|
the changes to the remote repository to which the local branch is
|
|
bound.
|
|
|
|
@kindex C-x v +
|
|
@findex vc-pull
|
|
With a decentralized version control system, the command @kbd{C-x v
|
|
+} (@code{vc-pull}) updates the current branch of the local repository
|
|
and it working tree with changes made in the upstream repository. It
|
|
is typically used to update a copy (a.k.a.@: @dfn{clone}) 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 the repository in the
|
|
default location determined by the version control system from your
|
|
branch configuration.
|
|
|
|
Amongst decentralized version control systems, @kbd{C-x v +} is
|
|
currently supported only by Bazaar, Git, and Mercurial. With Bazaar,
|
|
it calls @kbd{bzr pull} for ordinary branches (to pull from a
|
|
master branch into a mirroring branch), and @kbd{bzr update} for a
|
|
bound branch (to pull from a central repository). With Git, it calls
|
|
@kbd{git pull} to fetch changes from a remote repository and merge
|
|
it into the current branch. With Mercurial, it calls @kbd{hg pull
|
|
-u} to fetch changesets from the default remote repository and update
|
|
the working directory.
|
|
|
|
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}.
|
|
|
|
With 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
|
|
|
|
@table @kbd
|
|
@item C-x v m
|
|
With a decentralized version control system, merge changes from another
|
|
branch into the current one.
|
|
|
|
With a centralized version control system, merge changes from another
|
|
branch into the current VC fileset.
|
|
@end table
|
|
|
|
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 and conflicting changes may have
|
|
been made to the two branches.
|
|
|
|
With a decentralized version control system, you merge changes with
|
|
the command @kbd{C-x v m} (@code{vc-merge}). With Bazaar, this
|
|
prompts for the exact arguments to pass to the @command{bzr merge}
|
|
command, offering a sensible default if possible. With Git, this
|
|
prompts for the name of a branch to merge from, with completion (based
|
|
on the branch names known to the current repository). With Mercurial,
|
|
this prompts for argument to pass to @command{hg merge}. The output
|
|
from running the merge command is shown in a separate buffer.
|
|
|
|
With 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 @kbd{@key{RET}} at the
|
|
prompt, Emacs simply merges any changes that were made on the same
|
|
branch since you checked the file out.
|
|
|
|
@cindex conflicts, VC
|
|
@cindex resolving conflicts
|
|
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; by default,
|
|
Emacs will place buffers with VC conflicts in the special Smerge mode,
|
|
which provides special commands for resolving the merge conflicts.
|
|
Once you are done with resolving the conflicts and have saved the
|
|
files with resolved conflicts, those files must be committed in the
|
|
usual way for the merge to take effect (@pxref{Basic VC Editing}).
|
|
|
|
@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.
|
|
|
|
@kindex C-x v b c
|
|
@findex vc-create-branch
|
|
This procedure will not work for distributed version control systems
|
|
like git or Mercurial. For those systems you should use the command
|
|
@code{vc-create-branch} (@w{@kbd{C-x v b c @var{branch-name} @key{RET}}})
|
|
instead.
|
|
|
|
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.
|
|
|
|
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
|
|
@end ifnottex
|
|
|
|
@node Projects
|
|
@section Working with Projects
|
|
@cindex projects
|
|
|
|
@cindex project root
|
|
A @dfn{project} is a collection of files used for producing one or
|
|
more programs. Files that belong to a project are typically stored in
|
|
a hierarchy of directories; the top-level directory of the hierarchy
|
|
is known as the @dfn{project root}.
|
|
|
|
@cindex project back-end
|
|
Whether a given directory is a root of some project is determined by
|
|
the project-specific infrastructure, known as @dfn{project back-end}.
|
|
Emacs currently supports two such back-ends: VC-aware (@pxref{Version
|
|
Control}), whereby a VCS repository is considered a project; and EDE
|
|
(@pxref{EDE}). This is expected to be extended in the future to
|
|
support additional types of projects.
|
|
|
|
Which files do or don't belong to a project is also determined by
|
|
the project back-end. For example, the VC-aware back-end doesn't
|
|
consider ``ignored'' files (@pxref{VC Ignore}) to be part of the
|
|
project. Also, the VC-aware Project back-end considers ``untracked''
|
|
files by default. That behavior is controllable with the variable
|
|
@code{project-vc-include-untracked}.
|
|
|
|
@cindex current project name on mode line
|
|
@defopt project-mode-line
|
|
If this user option is non-@code{nil}, Emacs displays the name of the
|
|
current project (if any) on the mode line; clicking @kbd{mouse-1} on
|
|
the project name pops up the menu with the project-related commands.
|
|
The default value is @code{nil}.
|
|
@end defopt
|
|
|
|
@menu
|
|
* Project File Commands:: Commands for handling project files.
|
|
* Project Buffer Commands:: Commands for handling project buffers.
|
|
* Switching Projects:: Switching between projects.
|
|
* Managing Projects:: Managing the project list file.
|
|
@end menu
|
|
|
|
@node Project File Commands
|
|
@subsection Project Commands That Operate on Files
|
|
|
|
@table @kbd
|
|
@item C-x p f
|
|
Visit a file that belongs to the current project
|
|
(@code{project-find-file}).
|
|
@item C-x p g
|
|
Find matches for a regexp in all files that belong to the current
|
|
project (@code{project-find-regexp}).
|
|
@item M-x project-search
|
|
Interactively search for regexp matches in all files that belong to
|
|
the current project.
|
|
@item C-x p r
|
|
Perform query-replace for a regexp in all files that belong to the
|
|
current project (@code{project-query-replace-regexp}).
|
|
@item C-x p d
|
|
Run Dired in the current project's root directory
|
|
(@code{project-dired}).
|
|
@item C-x p v
|
|
Run @code{vc-dir} in the current project's root directory
|
|
(@code{project-vc-dir}).
|
|
@item C-x p s
|
|
Start an inferior shell in the current project's root directory
|
|
(@code{project-shell}).
|
|
@item C-x p e
|
|
Start Eshell in the current project's root directory
|
|
(@code{project-eshell}).
|
|
@item C-x p c
|
|
Run compilation in the current project's root directory
|
|
(@code{project-compile}).
|
|
@item C-x p !
|
|
Run shell command in the current project's root directory
|
|
(@code{project-shell-command}).
|
|
@item C-x p &
|
|
Run shell command asynchronously in the current project's root
|
|
directory (@code{project-async-shell-command}).
|
|
@end table
|
|
|
|
Emacs provides commands for handling project files conveniently.
|
|
This subsection describes these commands.
|
|
|
|
@cindex current project
|
|
All of the commands described here share the notion of the
|
|
@dfn{current project}. The current project is determined by the
|
|
@code{default-directory} (@pxref{File Names}) of the buffer that is
|
|
the current buffer when the command is invoked. If that directory
|
|
doesn't seem to belong to a recognizable project, these commands
|
|
prompt you for the project directory.
|
|
|
|
@findex project-find-file
|
|
@vindex vc-directory-exclusion-list
|
|
The command @kbd{C-x p f} (@code{project-find-file}) is a convenient
|
|
way of visiting files (@pxref{Visiting}) that belong to the current
|
|
project. Unlike @kbd{C-x C-f}, this command doesn't require typing
|
|
the full file name of the file to visit, you can type only the file's
|
|
base name (i.e., omit the leading directories). In addition, the
|
|
completion candidates considered by the command include only the files
|
|
belonging to the current project, and nothing else. If there's a file
|
|
name at point, this command offers that file as the first element of
|
|
the ``future history''. If given a prefix, include all files under
|
|
the project root, except for @acronym{VCS} directories listed in
|
|
@code{vc-directory-exclusion-list}.
|
|
|
|
@findex project-find-regexp
|
|
The command @kbd{C-x p g} (@code{project-find-regexp}) is similar to
|
|
@code{rgrep} (@pxref{Grep Searching}), but it searches only the files
|
|
that belong to the current project. The command prompts for the
|
|
regular expression to search, and pops up an Xref mode buffer with the
|
|
search results, where you can select a match using the Xref mode
|
|
commands (@pxref{Xref Commands}). When invoked with a prefix
|
|
argument, this command additionally prompts for the base directory
|
|
from which to start the search; this allows, for example, to limit the
|
|
search only to project files under a certain subdirectory of the
|
|
project root. The way this command displays the matches is affected
|
|
by the value of @code{xref-auto-jump-to-first-xref} (@pxref{Identifier
|
|
Search}).
|
|
|
|
@findex project-search
|
|
@kbd{M-x project-search} is a sequential variant of
|
|
@code{project-find-regexp}. It prompts for a regular expression to
|
|
search in the current project's files, but instead of finding all the
|
|
matches and displaying them, it stops when it finds a match and visits
|
|
the matched file at the locus of the match, allowing you to edit the
|
|
matched file. To find the rest of the matches, type @w{@kbd{M-x
|
|
fileloop-continue @key{RET}}}.
|
|
|
|
@findex project-query-replace-regexp
|
|
@kbd{C-x p r} (@code{project-query-replace-regexp}) is similar to
|
|
@code{project-search}, but it prompts you for whether to replace each
|
|
match it finds, like @code{query-replace} does (@pxref{Query
|
|
Replace}), and continues to the next match after you respond. If your
|
|
response causes Emacs to exit the query-replace loop, you can later
|
|
continue with @w{@kbd{M-x fileloop-continue @key{RET}}}.
|
|
|
|
@findex project-find-dir
|
|
The command @kbd{C-x p d} (@code{project-find-dir}) prompts you to
|
|
choose a directory inside the current project, with completion.
|
|
And opens a Dired buffer (@pxref{Dired}) listing the files in it.
|
|
|
|
@findex project-dired
|
|
The command @kbd{C-x p D} (@code{project-dired}) opens a Dired
|
|
buffer (@pxref{Dired}) listing the files in the current project's root
|
|
directory.
|
|
|
|
@findex project-vc-dir
|
|
The command @kbd{C-x p v} (@code{project-vc-dir}) opens a VC
|
|
Directory buffer (@pxref{VC Directory Mode}) listing the version
|
|
control statuses of the files in a directory tree under the current
|
|
project's root directory.
|
|
|
|
@findex project-shell
|
|
The command @kbd{C-x p s} (@code{project-shell}) starts a shell
|
|
session (@pxref{Shell}) in a new buffer with the current project's
|
|
root as the working directory.
|
|
|
|
@findex project-eshell
|
|
The command @kbd{C-x p e} (@code{project-eshell}) starts an Eshell
|
|
session in a new buffer with the current project's root as the working
|
|
directory. @xref{Top,Eshell,Eshell, eshell, Eshell: The Emacs Shell}.
|
|
|
|
@findex project-compile
|
|
The command @kbd{C-x p c} (@code{project-compile}) runs compilation
|
|
(@pxref{Compilation}) in the current project's root directory.
|
|
|
|
@findex project-shell-command
|
|
The command @kbd{C-x p !} (@code{project-shell-command}) runs
|
|
@code{shell-command} in the current project's root directory.
|
|
|
|
@findex project-async-shell-command
|
|
The command @kbd{C-x p &} (@code{project-async-shell-command}) runs
|
|
@code{async-shell-command} in the current project's root directory.
|
|
|
|
@node Project Buffer Commands
|
|
@subsection Project Commands That Operate on Buffers
|
|
|
|
@table @kbd
|
|
@item C-x p b
|
|
Switch to another buffer belonging to the current project
|
|
(@code{project-switch-to-buffer}).
|
|
@item C-x p C-b
|
|
List the project buffers (@code{project-list-buffers}).
|
|
@item C-x p k
|
|
Kill all live buffers that belong to the current project
|
|
(@code{project-kill-buffers}).
|
|
@end table
|
|
|
|
@findex project-switch-to-buffer
|
|
Working on a project could potentially involve having many buffers
|
|
visiting files that belong to the project, and also buffers that
|
|
belong to the project, but don't visit any files (like the
|
|
@file{*compilation*} buffer created by @code{project-compile}). The
|
|
command @kbd{C-x p b} (@code{project-switch-to-buffer}) helps you
|
|
switch between buffers that belong to the current project by prompting
|
|
for a buffer to switch and considering only the current project's
|
|
buffers as candidates for completion.
|
|
|
|
@findex project-list-buffers
|
|
Like the command @code{list-buffers} (@pxref{List Buffers}), the
|
|
command @kbd{C-x p C-b} (@code{project-list-buffers}) displays a list
|
|
of existing buffers, but only belonging to the current project.
|
|
|
|
@findex project-kill-buffers
|
|
@vindex project-kill-buffer-conditions
|
|
@vindex project-kill-buffers-display-buffer-list
|
|
When you finish working on the project, you may wish to kill all the
|
|
buffers that belong to the project, to keep your Emacs session
|
|
smaller. The command @kbd{C-x p k} (@code{project-kill-buffers})
|
|
accomplishes that: it kills all the buffers that belong to the current
|
|
project that satisfy any of @code{project-kill-buffer-conditions}. If
|
|
@code{project-kill-buffers-display-buffer-list} is non-@code{nil}, the
|
|
buffers to be killed will be displayed first.
|
|
|
|
@node Switching Projects
|
|
@subsection Switching Projects
|
|
|
|
@table @kbd
|
|
@item C-x p p
|
|
Run an Emacs command for another project (@code{project-switch-project}).
|
|
@end table
|
|
|
|
@findex project-switch-project
|
|
@vindex project-switch-commands
|
|
Commands that operate on project files (@pxref{Project File
|
|
Commands}) will conveniently prompt you for a project directory when
|
|
no project is current. When you are inside some project, but you want
|
|
to operate on a different project, use the @kbd{C-x p p} command
|
|
(@code{project-switch-project}). This command prompts you to choose a
|
|
directory among known project roots, and then displays the menu of
|
|
available commands to operate on the project you choose. The variable
|
|
@code{project-switch-commands} controls which commands are available
|
|
in the menu, and which key invokes each command.
|
|
|
|
@vindex project-list-file
|
|
The variable @code{project-list-file} names the file in which Emacs
|
|
records the list of known projects. It defaults to the file
|
|
@file{projects} in @code{user-emacs-directory} (@pxref{Find Init}).
|
|
|
|
@node Managing Projects
|
|
@subsection Managing the Project List File
|
|
|
|
@table @kbd
|
|
@item M-x project-forget-project
|
|
Remove a known project from the @code{project-list-file}.
|
|
@end table
|
|
|
|
@findex project-forget-project
|
|
Normally Emacs automatically adds and removes projects to and from the
|
|
@code{project-list-file}, but sometimes you may want to manually edit
|
|
the available projects. @kbd{M-x project-forget-project}
|
|
prompts you to choose one of the available projects, and then removes
|
|
it from the file.
|
|
|
|
@node Change Log
|
|
@section Change Logs
|
|
|
|
@cindex change log
|
|
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, these files are
|
|
automatically generated from the change log entries stored in version
|
|
control systems, or are used to generate these change log entries.
|
|
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.
|
|
* Format of ChangeLog:: What the change log file looks like.
|
|
@end menu
|
|
|
|
@node Change Log Commands
|
|
@subsection Change Log Commands
|
|
|
|
@kindex C-x 4 a
|
|
@findex add-change-log-entry-other-window
|
|
The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
|
|
file for the file you are editing
|
|
(@code{add-change-log-entry-other-window}). If that file is actually
|
|
a backup file, it makes an entry appropriate for the file's
|
|
parent---that is useful for making log entries for functions that
|
|
have been deleted in the current version.
|
|
|
|
@kbd{C-x 4 a} visits the change log file and creates a new entry
|
|
unless the most recent entry is for today's date and your name. It
|
|
also creates a new item for the current file. For many languages, it
|
|
can even guess the name of the function or other object that was
|
|
changed.
|
|
|
|
@c Not worth it.
|
|
@c @vindex change-log-directory-files
|
|
To find the change log file, Emacs searches up the directory tree from
|
|
the file you are editing. By default, it stops if it finds a
|
|
directory that seems to be the root of a version-control repository.
|
|
To change this, customize @code{change-log-directory-files}.
|
|
|
|
@vindex add-log-keep-changes-together
|
|
When the variable @code{add-log-keep-changes-together} is
|
|
non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file,
|
|
rather than starting a new item.
|
|
|
|
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 log entry.
|
|
|
|
@vindex add-log-always-start-new-record
|
|
If @code{add-log-always-start-new-record} is non-@code{nil},
|
|
@kbd{C-x 4 a} always makes a new entry, even if the last entry
|
|
was made by you and on the same date.
|
|
|
|
@vindex change-log-version-info-enabled
|
|
@vindex change-log-version-number-regexp-list
|
|
@cindex file version in change log entries
|
|
If the value of the variable @code{change-log-version-info-enabled}
|
|
is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the
|
|
change log entry. It finds the version number by searching the first
|
|
ten percent of the file, using regular expressions from the variable
|
|
@code{change-log-version-number-regexp-list}.
|
|
|
|
@cindex Change Log mode
|
|
@findex change-log-mode
|
|
The change log file is visited in Change Log mode. In this major
|
|
mode, each bunch of grouped items counts as one paragraph, and each
|
|
entry is considered a page. This facilitates editing the entries.
|
|
@kbd{C-j} and auto-fill indent each new line like the previous line;
|
|
this is convenient for entering the contents of an entry.
|
|
|
|
@findex change-log-goto-source
|
|
You can use the command @code{change-log-goto-source} (by default
|
|
bound to @kbd{C-c C-c}) to go to the source location of the change log
|
|
entry near point, when Change Log mode is on. Then subsequent
|
|
invocations of the @code{next-error} command (by default bound to
|
|
@kbd{M-g M-n} and @kbd{C-x `}) will move between entries in the change
|
|
log. You will jump to the actual site in the file that was changed,
|
|
not just to the next change log entry. You can also use
|
|
@code{previous-error} to move back through the change log entries.
|
|
|
|
@findex change-log-merge
|
|
You can use the command @kbd{M-x change-log-merge} to merge other
|
|
log files into a buffer in Change Log Mode, preserving the date
|
|
ordering of entries.
|
|
|
|
@vindex add-log-dont-create-changelog-file
|
|
Version control systems are another way to keep track of changes in
|
|
your program and keep a change log. Many projects that use a VCS don't
|
|
keep a separate versioned change log file nowadays, so you may wish to
|
|
avoid having such a file in the repository. If the value of
|
|
@code{add-log-dont-create-changelog-file} is non-@code{nil}, commands
|
|
like @kbd{C-x 4 a} (@code{add-change-log-entry-other-window}) will
|
|
record changes in a suitably named temporary buffer instead of a file,
|
|
if such a file does not already exist.
|
|
|
|
Whether you have a change log file or use a temporary buffer for
|
|
change logs, you can type @kbd{C-c C-a}
|
|
(@code{log-edit-insert-changelog}) in the VC Log buffer to insert the
|
|
relevant change log entries, if they exist. @xref{Log Buffer}.
|
|
|
|
@node Format of ChangeLog
|
|
@subsection Format of ChangeLog
|
|
|
|
A change log entry starts with a header line that contains the
|
|
current date, your name (taken from the variable
|
|
@code{add-log-full-name}), and your email address (taken from the
|
|
variable @code{add-log-mailing-address}). Aside from these header
|
|
lines, every line in the change log starts with a space or a tab. The
|
|
bulk of the entry consists of @dfn{items}, each of which starts with a
|
|
line starting with whitespace and a star. Here are two entries, both
|
|
dated in May 1993, with two items and one item respectively.
|
|
|
|
@iftex
|
|
@medbreak
|
|
@end iftex
|
|
@smallexample
|
|
1993-05-25 Richard Stallman <rms@@gnu.org>
|
|
|
|
* man.el: Rename symbols 'man-*' to 'Man-*'.
|
|
(manual-entry): Make prompt string clearer.
|
|
|
|
* simple.el (blink-matching-paren-distance):
|
|
Change default to 12,000.
|
|
|
|
1993-05-24 Richard Stallman <rms@@gnu.org>
|
|
|
|
* vc.el (minor-mode-map-alist): Don't use it if it's void.
|
|
(vc-cancel-version): Doc fix.
|
|
@end smallexample
|
|
|
|
One entry can describe several changes; each change should have its
|
|
own item, or its own line in an item. Normally there should be a
|
|
blank line between items. When items are related (parts of the same
|
|
change, in different places), group them by leaving no blank line
|
|
between them.
|
|
|
|
You should put a copyright notice and permission notice at the
|
|
end of the change log file. Here is an example:
|
|
|
|
@smallexample
|
|
Copyright 1997, 1998 Free Software Foundation, Inc.
|
|
Copying and distribution of this file, with or without modification, are
|
|
permitted provided the copyright notice and this notice are preserved.
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Of course, you should substitute the proper years and copyright holder.
|
|
|
|
@node Xref
|
|
@section Find Identifier References
|
|
@cindex xref
|
|
|
|
@cindex tag
|
|
An @dfn{identifier} is a name of a syntactical subunit of the
|
|
program: a function, a subroutine, a method, a class, a data type, a
|
|
macro, etc. In a programming language, each identifier is a symbol in
|
|
the language's syntax. Identifiers are also known as @dfn{tags}.
|
|
|
|
Program development and maintenance requires capabilities to quickly
|
|
find where each identifier was defined and referenced, to rename
|
|
identifiers across the entire project, etc. These capabilities are
|
|
also useful for finding references in major modes other than those
|
|
defined to support programming languages. For example, chapters,
|
|
sections, appendices, etc.@: of a text or a @TeX{} document can be
|
|
treated as subunits as well, and their names can be used as
|
|
identifiers. In this chapter, we use the term ``identifiers'' to
|
|
collectively refer to the names of any kind of subunits, in program
|
|
source and in other kinds of text alike.
|
|
|
|
Emacs provides a unified interface to these capabilities, called
|
|
@samp{xref}.
|
|
|
|
@cindex xref backend
|
|
To do its job, @code{xref} needs to make use of information and to
|
|
employ methods specific to the major mode. What files to search for
|
|
identifiers, how to find references to identifiers, how to complete on
|
|
identifiers---all this and more is mode-specific knowledge.
|
|
@code{xref} delegates the mode-specific parts of its job to a
|
|
@dfn{backend} provided by the mode; it also includes defaults for some
|
|
of its commands, for those modes that don't provide their own.
|
|
|
|
A backend can implement its capabilities in a variety of ways. Here
|
|
are a few examples:
|
|
|
|
@enumerate a
|
|
@item
|
|
Some major modes provide built-in means for looking up the language
|
|
symbols. For example, Emacs Lisp symbols can be identified by
|
|
searching the package load history, maintained by the Emacs Lisp
|
|
interpreter, and by consulting the built-in documentation strings; the
|
|
Emacs Lisp mode uses these facilities in its backend to allow finding
|
|
definitions of symbols. (One disadvantage of this kind of backend is
|
|
that it only knows about subunits that were loaded into the
|
|
interpreter.)
|
|
|
|
@item
|
|
If Eglot is activated for the current buffer's project
|
|
(@pxref{Projects}) and the current buffer's major mode, Eglot consults
|
|
an external language server program and provides the data supplied by
|
|
the server regarding the definitions of the identifiers in the
|
|
project. @xref{Eglot Features,,, eglot, Eglot: The Emacs LSP Client}.
|
|
|
|
@item
|
|
An external program can extract references by scanning the relevant
|
|
files, and build a database of these references. A backend can then
|
|
access this database whenever it needs to list or look up references.
|
|
The Emacs distribution includes @command{etags}, a command for tagging
|
|
identifier definitions in programs, which supports many programming
|
|
languages and other major modes, such as HTML, by extracting
|
|
references into @dfn{tags tables}. @xref{Create Tags Table}. Major
|
|
modes for languages supported by @command{etags} can use tags tables
|
|
as basis for their backend. (One disadvantage of this kind of backend
|
|
is that tags tables need to be kept reasonably up to date, by
|
|
rebuilding them from time to time.)
|
|
@end enumerate
|
|
|
|
@menu
|
|
* Find Identifiers:: Commands to find where an identifier is defined
|
|
or referenced, to list identifiers, etc.
|
|
* Tags Tables:: Tags table records which file defines a symbol.
|
|
* Select Tags Table:: How to visit a specific tags table.
|
|
@end menu
|
|
|
|
@node Find Identifiers
|
|
@subsection Find Identifiers
|
|
|
|
This subsection describes the commands that find references to
|
|
identifiers and perform various queries about identifiers. Each such
|
|
reference could @emph{define} an identifier, e.g., provide the
|
|
implementation of a program subunit or the text of a document section;
|
|
or it could @emph{use} the identifier, e.g., call a function or a
|
|
method, assign a value to a variable, mention a chapter in a
|
|
cross-reference, etc.
|
|
|
|
@menu
|
|
* Looking Up Identifiers:: Commands to find the definition of an identifier.
|
|
* Xref Commands:: Commands in the @file{*xref*} buffer.
|
|
* Identifier Search:: Searching and replacing identifiers.
|
|
* List Identifiers:: Listing identifiers and completing on them.
|
|
@end menu
|
|
|
|
@node Looking Up Identifiers
|
|
@subsubsection Looking Up Identifiers
|
|
@cindex find definition of symbols
|
|
@cindex identifier, finding definition of
|
|
@cindex find references to symbols
|
|
|
|
The most important thing that @code{xref} enables you to do is to find
|
|
the definition of a specific identifier.
|
|
|
|
@table @kbd
|
|
@item M-.@:
|
|
Find definitions of an identifier (@code{xref-find-definitions}).
|
|
@item C-M-. @var{pattern} @key{RET}
|
|
Find all identifiers whose name matches @var{pattern}
|
|
(@code{xref-find-apropos}).
|
|
@item C-x 4 .@: @key{RET}
|
|
Find definitions of identifier, but display it in another window
|
|
(@code{xref-find-definitions-other-window}).
|
|
@item C-x 5 .@: @key{RET}
|
|
Find definition of identifier, and display it in a new frame
|
|
(@code{xref-find-definitions-other-frame}).
|
|
@item M-x xref-find-definitions-at-mouse
|
|
Find definition of identifier at mouse click.
|
|
@item M-,
|
|
Go back to where you previously invoked @kbd{M-.} and friends
|
|
(@code{xref-go-back}).
|
|
@item C-M-,
|
|
Go forward to where you previously invoked @kbd{M-,}
|
|
(@code{xref-go-forward}).
|
|
@item M-x xref-etags-mode
|
|
Switch @code{xref} to use the @code{etags} backend.
|
|
@end table
|
|
|
|
@kindex M-.
|
|
@findex xref-find-definitions
|
|
@vindex xref-prompt-for-identifier
|
|
@kbd{M-.}@: (@code{xref-find-definitions}) shows the definition of
|
|
the identifier at point. With a prefix argument, or if there's no
|
|
identifier at point, it prompts for the identifier. (If you want it
|
|
to always prompt, customize @code{xref-prompt-for-identifier} to
|
|
@code{t}.)
|
|
|
|
When entering the identifier argument to @kbd{M-.}, you can use the
|
|
usual minibuffer completion commands (@pxref{Completion}), with the
|
|
known identifier names being the completion candidates.
|
|
|
|
@kindex C-x 4 .
|
|
@findex xref-find-definitions-other-window
|
|
@kindex C-x 5 .
|
|
@findex xref-find-definitions-other-frame
|
|
Like most commands that can switch buffers,
|
|
@code{xref-find-definitions} 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 .}}
|
|
(@code{xref-find-definitions-other-window}), and the latter is
|
|
@w{@kbd{C-x 5 .}} (@code{xref-find-definitions-other-frame}).
|
|
|
|
The command @code{xref-find-definitions-at-mouse} works like
|
|
@code{xref-find-definitions}, but it looks for the identifier name at
|
|
or around the place of a mouse event. This command is intended to be
|
|
bound to a mouse event, such as @kbd{C-M-mouse-1}, for example.
|
|
|
|
@kindex C-M-.
|
|
@findex xref-find-apropos
|
|
@vindex tags-apropos-additional-actions
|
|
The command @kbd{C-M-.}@: (@code{xref-find-apropos}) is like
|
|
@code{apropos} for tags (@pxref{Apropos}). It displays a list of
|
|
identifiers in the selected tags table whose names match the specified
|
|
@var{regexp}. This is just like @kbd{M-.}, except that it does regexp
|
|
matching of identifiers instead of matching symbol names as fixed
|
|
strings. By default, the command pops up the @file{*xref*} buffer,
|
|
like @kbd{M-.}, but you can display additional output by customizing
|
|
the variable @code{tags-apropos-additional-actions}; see its
|
|
documentation for details.
|
|
|
|
@vindex xref-auto-jump-to-first-definition
|
|
If any of the above commands finds more than one matching
|
|
definition, it by default pops up the @file{*xref*} buffer showing the
|
|
matching candidates and selects that buffer's window. (@kbd{C-M-.}@:
|
|
@emph{always} pops up the @file{*xref*} buffer if it finds at least
|
|
one match.) Each candidate is normally shown in that buffer as the
|
|
name of a file and the matching identifier(s) in that file. In that
|
|
buffer, you can select any of the candidates for display, and you have
|
|
several additional commands, described in @ref{Xref Commands}.
|
|
However, if the value of the variable
|
|
@code{xref-auto-jump-to-first-definition} is @code{move}, Emacs
|
|
automatically moves point to the first of these candidates in the
|
|
@file{*xref*} buffer, so just typing @key{RET} will display the
|
|
definition of that candidate. If the value of the variable is
|
|
@code{t} or @code{show}, the first candidate is automatically shown in
|
|
its own window; @code{t} also selects the window showing the first
|
|
candidate's definition, while @code{show} leaves the window of the
|
|
@file{*xfer*} buffer selected. The default value is @code{nil}, which
|
|
just shows the candidates in the @file{*xref*} buffer, but neither
|
|
selects any of them nor shows their definition, until you select a
|
|
candidate in the @file{*xref*} buffer.
|
|
|
|
@findex next-error, in @file{*xref*} buffer
|
|
@findex previous-error, in @file{*xref*} buffer
|
|
@kindex M-g M-n, for navigation in @file{*xref*} buffer
|
|
@kindex M-g M-p, for navigation in @file{*xref*} buffer
|
|
If you switch away of the window showing the @file{*xref*} buffer
|
|
which displays several candidates, you can move from one candidate to
|
|
another using the commands @w{@kbd{M-g M-n}} (@code{next-error}) and
|
|
@w{@kbd{M-g M-p}} (@code{previous-error}). @xref{Compilation Mode}.
|
|
|
|
@kindex M-,
|
|
@findex xref-go-back
|
|
To go back to places @emph{from where} you've displayed the
|
|
definition, use @kbd{M-,} (@code{xref-go-back}). It jumps back to the
|
|
point of the last invocation of @kbd{M-.}. Thus you can find and
|
|
examine the definition of something with @kbd{M-.} and then return to
|
|
where you were with @kbd{M-,}. @kbd{M-,} allows you to retrace the
|
|
steps you made forward in the history of places, all the way to the
|
|
first place in history, where you first invoked @kbd{M-.}, or to any
|
|
place in-between.
|
|
|
|
@kindex C-M-,
|
|
@findex xref-go-forward
|
|
If you previously went back too far with @kbd{M-,}, or want to
|
|
re-examine a place from which you went back, you can use @kbd{C-M-,}
|
|
(@code{xref-go-forward}) to go forward again. This is similar to
|
|
using @kbd{M-.}, except that you don't need on each step to move point
|
|
to the identifier whose definition you want to look up. @kbd{C-M-,}
|
|
allows you to retrace all the steps you made back in the history of
|
|
places, all the way to the last place in history, where you invoked
|
|
@kbd{M-,}, or to any place in-between.
|
|
|
|
@findex xref-etags-mode
|
|
Some major modes install @code{xref} support facilities that might
|
|
sometimes fail to find certain identifiers. For example, in Emacs
|
|
Lisp mode (@pxref{Lisp Eval}) @kbd{M-.} will by default find only
|
|
functions and variables from Lisp packages which are loaded into the
|
|
current Emacs session or are auto-loaded (@pxref{Autoload,,, elisp,
|
|
The Emacs Lisp Reference Manual}). If @kbd{M-.} fails to find some
|
|
identifiers, you can try forcing @code{xref} to use the @code{etags}
|
|
backend (@pxref{Xref}). To this end, turn on the Xref Etags minor
|
|
mode with @w{@kbd{M-x xref-etags-mode}}, then invoke @kbd{M-.} again.
|
|
(For this to work, be sure to run @command{etags} to create the tags
|
|
table in the directory tree of the source files, see @ref{Create Tags
|
|
Table}.)
|
|
|
|
@node Xref Commands
|
|
@subsubsection Commands Available in the @file{*xref*} Buffer
|
|
@cindex commands in @file{*xref*} buffers
|
|
@cindex XREF mode
|
|
|
|
The following commands are provided in the @file{*xref*} buffer by
|
|
the special XREF mode:
|
|
|
|
@table @kbd
|
|
@item @key{RET}
|
|
@itemx mouse-1
|
|
Display the reference on the current line (@code{xref-goto-xref}).
|
|
With prefix argument, also bury the @file{*xref*} buffer.
|
|
|
|
@item mouse-2
|
|
@findex xref-select-and-show-xref
|
|
The same as @code{mouse-1}, but make the window displaying the
|
|
@file{*xref*} buffer the selected window
|
|
(@code{xref-select-and-show-xref}).
|
|
|
|
@item n
|
|
@itemx .
|
|
@findex xref-next-line
|
|
Move to the next reference and display it in the other window
|
|
(@code{xref-next-line}).
|
|
|
|
@item N
|
|
@findex xref-next-group
|
|
Move to the first reference of the next reference group and display it
|
|
in the other window (@code{xref-next-group}).
|
|
|
|
@item p
|
|
@itemx ,
|
|
@findex xref-prev-line
|
|
Move to the previous reference and display it in the other window
|
|
(@code{xref-prev-line}).
|
|
|
|
@item P
|
|
@findex xref-prev-group
|
|
Move to the first reference of the previous reference group and
|
|
display it in the other window (@code{xref-prev-group}).
|
|
|
|
@item C-o
|
|
@findex xref-show-location-at-point
|
|
Display the reference on the current line in the other window
|
|
(@code{xref-show-location-at-point}).
|
|
|
|
@item r @var{pattern} @key{RET} @var{replacement} @key{RET}
|
|
Perform interactive query-replace on references that match
|
|
@var{pattern} (@code{xref-query-replace-in-results}), replacing
|
|
the match with @var{replacement}. This command can only be used in
|
|
@file{*xref*} buffers that show all the matches for an identifier in
|
|
all the relevant files. @xref{Identifier Search}.
|
|
|
|
@item g
|
|
@findex xref-revert-buffer
|
|
Refresh the contents of the @file{*xref*} buffer
|
|
(@code{xref-revert-buffer}).
|
|
|
|
@item M-,
|
|
@findex xref-quit-and-pop-marker-stack
|
|
Quit the window showing the @file{*xref*} buffer, and then jump to the
|
|
previous Xref stack location (@code{xref-quit-and-pop-marker-stack}).
|
|
|
|
@item q
|
|
@findex xref-quit
|
|
Quit the window showing the @file{*xref*} buffer (@code{xref-quit}).
|
|
@end table
|
|
|
|
In addition, the usual navigation commands, such as the arrow keys,
|
|
@kbd{C-n}, and @kbd{C-p} are available for moving around the buffer
|
|
without displaying the references.
|
|
|
|
@node Identifier Search
|
|
@subsubsection Searching and Replacing with Identifiers
|
|
@cindex search and replace in multiple source files
|
|
@cindex multiple source file search and replace
|
|
|
|
The commands in this section perform various search and replace
|
|
operations either on identifiers themselves or on files that reference
|
|
them.
|
|
|
|
@table @kbd
|
|
@item M-?
|
|
Find all the references for the identifier at point.
|
|
|
|
@item r
|
|
@itemx M-x xref-query-replace-in-results @key{RET} @var{replacement} @key{RET}
|
|
@itemx C-u M-x xref-query-replace-in-results @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
|
|
Interactively replace @var{regexp} with @var{replacement} in the names
|
|
of all the identifiers shown in the @file{*xref*} buffer.
|
|
|
|
@item M-x xref-find-references-and-replace @key{RET} @var{from} @key{RET} @var{to} @key{RET}
|
|
Interactively rename all instances of the identifier @var{from} to the
|
|
new name @var{to}.
|
|
|
|
@item M-x tags-search @key{RET} @var{regexp} @key{RET}
|
|
Search for @var{regexp} through the files in the selected tags
|
|
table.
|
|
|
|
@item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
|
|
Perform a @code{query-replace-regexp} on each file in the selected tags table.
|
|
|
|
@item M-x fileloop-continue
|
|
Restart one of the last 2 commands above, from the current location of point.
|
|
@end table
|
|
|
|
@kindex M-?
|
|
@findex xref-find-references
|
|
@kbd{M-?} finds all the references for the identifier at point,
|
|
prompting for the identifier as needed, with completion. Depending on
|
|
the current backend (@pxref{Xref}), the command may prompt even if it
|
|
finds a valid identifier at point. When invoked with a prefix
|
|
argument, it always prompts for the identifier. (If you want it to
|
|
prompt always, customize the value of the variable
|
|
@code{xref-prompt-for-identifier} to @code{t}; or set it to @code{nil}
|
|
to prompt only if there's no usable identifier at point.) The command
|
|
then presents the @file{*xref*} buffer with all the references to the
|
|
identifier, showing the file name and the line where the identifier is
|
|
referenced. The XREF mode commands are available in this buffer, see
|
|
@ref{Xref Commands}.
|
|
|
|
@vindex xref-auto-jump-to-first-xref
|
|
If the value of the variable @code{xref-auto-jump-to-first-xref} is
|
|
@code{t}, @code{xref-find-references} automatically jumps to the first
|
|
result in the @file{*xref*} buffer and selects the window where that
|
|
reference is displayed; you can select the other results with
|
|
@w{@kbd{M-g M-n}} (@code{next-error}) and @w{@kbd{M-g M-p}}
|
|
(@code{previous-error}) (@pxref{Compilation Mode}). If the value is
|
|
@code{show}, the first result is displayed, but the window showing the
|
|
@file{*xref*} buffer is left selected. If the value is @code{move},
|
|
the first result is selected in the @file{*xref*} buffer, but is not
|
|
displayed; you can then use @key{RET} to actually display the
|
|
reference. The default value is @code{nil}, which just shows the
|
|
results in the @file{*xref*} buffer, but doesn't select any of them,
|
|
and doesn't display the reference itself.
|
|
|
|
@findex xref-query-replace-in-results
|
|
@kbd{r} (@code{xref-query-replace-in-results}) reads a @var{replacement}
|
|
string, just like ordinary @kbd{M-x query-replace-regexp}. It then
|
|
renames the identifiers shown in the @file{*xref*} buffer in all the
|
|
places in all the files where these identifiers are referenced, such
|
|
that their new name is @var{replacement}. This is useful when you
|
|
rename your identifiers as part of refactoring. This command should
|
|
be invoked in the @file{*xref*} buffer generated by @kbd{M-?}. By
|
|
default, the command replaces the entire name of each identifier with
|
|
@var{replacement}, but if invoked with a prefix argument, the command
|
|
prompts for a regexp to match identifier names, and replaces only the
|
|
matches of that regexp in the names of the identifiers with
|
|
@var{replacement}.
|
|
|
|
@findex xref-find-references-and-replace
|
|
@kbd{M-x xref-find-references-and-replace} works similarly to
|
|
@code{xref-query-replace-in-results}, but is more convenient when you
|
|
want to rename a single identifier specified by its name @var{from}.
|
|
|
|
@findex tags-search
|
|
@kbd{M-x tags-search} reads a regexp using the minibuffer, then
|
|
searches for matches in all the files in the selected tags table, one
|
|
file at a time. It displays the name of the file being searched so
|
|
you can follow its progress. As soon as it finds an occurrence,
|
|
@code{tags-search} returns. This command requires tags tables to be
|
|
available (@pxref{Tags Tables}).
|
|
|
|
@findex fileloop-continue
|
|
Having found one match with @code{tags-search}, you probably want to
|
|
find all the rest. @kbd{M-x fileloop-continue} resumes 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
|
|
@code{query-replace-regexp} through all the files in the tags table. It
|
|
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{Query Replace}, for more information on query replace.
|
|
|
|
@vindex tags-case-fold-search
|
|
@cindex case-sensitivity and tags search
|
|
You can control the case-sensitivity of tags search commands by
|
|
customizing the value of the variable @code{tags-case-fold-search}. The
|
|
default is to use the same setting as the value of
|
|
@code{case-fold-search} (@pxref{Lax Search}).
|
|
|
|
It is possible to get through all the files in the tags table with a
|
|
single invocation of @kbd{M-x tags-query-replace}. But often it is
|
|
useful to exit temporarily, which you can do with any input event that
|
|
has no special query replace meaning. You can resume the query
|
|
replace subsequently by typing @kbd{M-x fileloop-continue}; this
|
|
command resumes the last tags search or replace command that you did.
|
|
For instance, to skip the rest of the current file, you can type
|
|
@w{@kbd{M-> M-x fileloop-continue}}.
|
|
|
|
Note that the commands described above carry out much broader
|
|
searches than the @code{xref-find-definitions} family. The
|
|
@code{xref-find-definitions} commands search only for definitions of
|
|
identifiers that match your string or regexp. The commands
|
|
@code{xref-find-references}, @code{tags-search}, and
|
|
@code{tags-query-replace} find every occurrence of the identifier or
|
|
regexp, as ordinary search commands and replace commands do in the
|
|
current buffer.
|
|
|
|
As an alternative to @code{xref-find-references} and
|
|
@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 Identifiers
|
|
@subsubsection Identifier Inquiries
|
|
|
|
@table @kbd
|
|
@item C-M-i
|
|
@itemx M-@key{TAB}
|
|
Perform completion on the text around point, possibly 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 identifiers defined in the program file
|
|
@var{file}.
|
|
|
|
@item C-M-. @var{regexp} @key{RET}
|
|
Display a list of all identifiers matching @var{regexp}
|
|
(@code{xref-find-apropos}). @xref{Looking Up Identifiers}.
|
|
|
|
@item M-x tags-next-file
|
|
Visit files recorded in the selected tags table.
|
|
@end table
|
|
|
|
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. Some modes provide specialized completion for this command
|
|
tailored to the mode; for those that don't, if there is a tags table
|
|
loaded, 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 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. This
|
|
command works only with the etags backend, and requires a tags table
|
|
for the project to be available. @xref{Tags Tables}. If used
|
|
interactively, the default tag is file name of the current buffer if
|
|
used interactively.
|
|
|
|
@findex tags-next-file
|
|
@kbd{M-x tags-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. This command requires a tags table to be selected.
|
|
|
|
@node Tags Tables
|
|
@subsection Tags Tables
|
|
@cindex tags and tag tables
|
|
|
|
A @dfn{tags table} records the tags@footnote{
|
|
A @dfn{tag} is a synonym for identifier reference. Commands and
|
|
features based on the @code{etags} package traditionally use ``tag''
|
|
with this meaning, and this subsection follows that tradition.
|
|
} extracted by scanning the source code of a certain program or a
|
|
certain document. Tags extracted from generated files reference the
|
|
original files, rather than the generated files that were scanned
|
|
during tag extraction. Examples of generated files include C files
|
|
generated from Cweb source files, from a Yacc parser, or from Lex
|
|
scanner definitions; @file{.i} preprocessed C files; and Fortran files
|
|
produced by preprocessing @file{.fpp} source files.
|
|
|
|
@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}. (It is also possible to create a tags table
|
|
by using one of the commands from other packages that can produce such
|
|
tables in the same format.)
|
|
|
|
Emacs uses the tags tables via the @code{etags} package as one of
|
|
the supported backends for @code{xref}. Because tags tables are
|
|
produced by the @command{etags} command that is part of an Emacs
|
|
distribution, we describe tags tables in more detail here.
|
|
|
|
@cindex C++ class browser, tags
|
|
@cindex tags, C++
|
|
@cindex class browser, C++
|
|
@cindex Ebrowse
|
|
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 and updating tags tables with @command{etags}.
|
|
* Etags Regexps:: Create arbitrary tags using regular expressions.
|
|
@end menu
|
|
|
|
@node Tag Syntax
|
|
@subsubsection Source File Tag Syntax
|
|
|
|
Here is how tag syntax is defined for the most popular languages:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
In C code, any C function or typedef is a tag, and so are definitions of
|
|
@code{struct}, @code{union} and @code{enum}.
|
|
@code{#define} macro definitions, @code{#undef} and @code{enum}
|
|
constants are also
|
|
tags, unless you specify @samp{--no-defines} when making the tags table.
|
|
Similarly, global variables are tags, unless you specify
|
|
@samp{--no-globals}, and so are struct members, unless you specify
|
|
@samp{--no-members}. Use of @samp{--no-globals}, @samp{--no-defines}
|
|
and @samp{--no-members} can make the tags table file much smaller.
|
|
|
|
You can tag function declarations and external variables in addition
|
|
to function definitions by giving the @samp{--declarations} option to
|
|
@command{etags}.
|
|
|
|
@item
|
|
In C++ code, in addition to all the tag constructs of C code, member
|
|
functions are also recognized; member variables are also recognized,
|
|
unless you use the @samp{--no-members} option. @code{operator}
|
|
definitions have tag names like @samp{operator+}. If you specify the
|
|
@samp{--class-qualify} option, tags for variables and functions in
|
|
classes are named @samp{@var{class}::@var{variable}} and
|
|
@samp{@var{class}::@var{function}}. By default, class methods and
|
|
members are not class-qualified, which facilitates identifying their
|
|
names in the sources more accurately.
|
|
|
|
@item
|
|
In Java code, tags include all the constructs recognized in C++, plus
|
|
the @code{interface}, @code{extends} and @code{implements} constructs.
|
|
Tags for variables and functions in classes are named
|
|
@samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
|
|
|
|
@item
|
|
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},
|
|
@code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},
|
|
@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 @command{etags}. The
|
|
value of this environment variable should be a colon-separated list of
|
|
command names. For example,
|
|
|
|
@example
|
|
TEXTAGS="mycommand:myothercommand"
|
|
export TEXTAGS
|
|
@end example
|
|
|
|
@noindent
|
|
specifies (using Bourne shell syntax) that the commands
|
|
@samp{\mycommand} and @samp{\myothercommand} also define tags.
|
|
|
|
@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. 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
|
|
construct whose name starts with @samp{def}. They also include variables
|
|
set with @code{set!} at top level in the file.
|
|
@end itemize
|
|
|
|
Several other languages are also supported:
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
In Ada code, functions, procedures, packages, tasks and types are
|
|
tags. Use the @samp{--packages-only} option to create tags for
|
|
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
|
|
easier to pick the definition you want, Ada tag names have suffixes
|
|
indicating the type of entity:
|
|
|
|
@table @samp
|
|
@item /b
|
|
package body.
|
|
@item /f
|
|
function.
|
|
@item /k
|
|
task.
|
|
@item /p
|
|
procedure.
|
|
@item /s
|
|
package spec.
|
|
@item /t
|
|
type.
|
|
@end table
|
|
|
|
Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
|
|
directly to the body of the package @code{bidule}, while @kbd{M-x
|
|
find-tag @key{RET} bidule @key{RET}} will just search for any tag
|
|
@code{bidule}.
|
|
|
|
@item
|
|
In assembler code, labels appearing at the start of a line,
|
|
followed by a colon, are tags.
|
|
|
|
@item
|
|
In Bison or Yacc input files, each rule defines as a tag the nonterminal
|
|
it constructs. The portions of the file that contain C code are parsed
|
|
as C code.
|
|
|
|
@item
|
|
In Cobol code, tags are paragraph names; that is, any word starting in
|
|
column 8 and followed by a period.
|
|
|
|
@item
|
|
In Erlang code, the tags are the functions, records and macros defined
|
|
in the file.
|
|
|
|
@item
|
|
In Fortran code, functions, subroutines and block data are tags.
|
|
|
|
@item
|
|
In Go code, packages, functions, and types are tags.
|
|
|
|
@item
|
|
In HTML input files, the tags are the @code{title} and the @code{h1},
|
|
@code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors
|
|
and all occurrences of @code{id=}.
|
|
|
|
@item
|
|
In Lua input files, all functions are tags.
|
|
|
|
@item
|
|
In makefiles, targets are tags; additionally, variables are tags
|
|
unless you specify @samp{--no-globals}.
|
|
|
|
@item
|
|
In Objective C code, tags include Objective C definitions for classes,
|
|
class categories, methods and protocols. Tags for variables and
|
|
functions in classes are named @samp{@var{class}::@var{variable}} and
|
|
@samp{@var{class}::@var{function}}.
|
|
|
|
@item
|
|
In Pascal code, the tags are the functions and procedures defined in
|
|
the file.
|
|
|
|
@item
|
|
In Perl code, the tags are the packages, subroutines and variables
|
|
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
|
|
too, unless you use the @samp{--no-members} option.
|
|
|
|
@item
|
|
In PostScript code, the tags are the functions.
|
|
|
|
@item
|
|
In Prolog code, tags are predicates and rules at the beginning of
|
|
line.
|
|
|
|
@item
|
|
In Python code, @code{def} or @code{class} at the beginning of a line
|
|
generate a tag.
|
|
|
|
@item
|
|
In Ruby code, @code{def} or @code{class} or @code{module} at the
|
|
beginning of a line generate a tag. Constants also generate tags.
|
|
|
|
@item
|
|
In Rust code, tags anything defined with @code{fn}, @code{enum},
|
|
@code{struct} or @code{macro_rules!}.
|
|
@end itemize
|
|
|
|
You can also generate tags based on regexp matching (@pxref{Etags
|
|
Regexps}) to handle other formats and languages.
|
|
|
|
@node Create Tags Table
|
|
@subsubsection Creating Tags Tables
|
|
@cindex @command{etags} program
|
|
|
|
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.
|
|
@end iftex
|
|
@ifnottex
|
|
@ref{Tag Syntax}.
|
|
@end ifnottex
|
|
Here is how to run @command{etags}:
|
|
|
|
@example
|
|
etags @var{inputfiles}@dots{}
|
|
@end example
|
|
|
|
@noindent
|
|
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. You can also append the
|
|
newly created tags table to an existing file by using the @samp{--append}
|
|
option.
|
|
|
|
If the specified files don't exist, @command{etags} looks for
|
|
compressed versions of them and uncompresses them to read them. Under
|
|
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.
|
|
|
|
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.
|
|
|
|
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
|
|
@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
|
|
files. If the tags file is @file{-} or is in the @file{/dev} directory,
|
|
however, the file names are
|
|
made relative to the current working directory. This is useful, for
|
|
example, when writing the tags to the standard output.
|
|
|
|
When using a relative file name, it should not be a symbolic link
|
|
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 @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. 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
|
|
|
|
@command{etags} recognizes the language used in an input file based on
|
|
its file name and contents. It first tries to match the file's name and
|
|
extension to the ones commonly used with certain languages. Some
|
|
languages have interpreters with known names (e.g., @command{perl} for
|
|
Perl or @command{pl} for Prolog), so @command{etags} next looks for an
|
|
interpreter specification of the form @samp{#!@var{interp}} on the first
|
|
line of an input file, and matches that against known interpreters. If
|
|
none of that works, or if you want to override the automatic detection of
|
|
the language, 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}). This comes in handy when an input file uses a
|
|
language not yet supported by @command{etags}, and you want to avoid
|
|
having @command{etags} fall back on Fortran and C as the default
|
|
languages.
|
|
|
|
The option @samp{--parse-stdin=@var{file}} is mostly useful when
|
|
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}.
|
|
|
|
For C and C++, if the source files don't observe the GNU Coding
|
|
Standards' convention if having braces (@samp{@{} and @samp{@}}) in
|
|
column zero only for top-level definitions, like functions and
|
|
@code{struct} definitions, we advise that you use the
|
|
@samp{--ignore-indentation} option, to prevent @command{etags} from
|
|
incorrectly interpreting closing braces in column zero.
|
|
|
|
@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 @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}.
|
|
|
|
@findex etags-regen-mode
|
|
Instead of creating and updating the tags table by manually invoking
|
|
@command{etags}, you can ask Emacs to do it for you automatically.
|
|
The global minor mode @code{etags-regen-mode}, if enabled, generates
|
|
tags tables automatically as needed, and takes care of updating them
|
|
when you edit any of the source files that contribute tags. This mode
|
|
uses the current project configuration (@pxref{Projects}) to determine
|
|
which files to submit to @command{etags} for regenerating the tags
|
|
table for the project. You can customize how this minor mode works
|
|
using the following user options:
|
|
|
|
@vtable @code
|
|
@item etags-regen-program
|
|
The program to regenerate tags table; defaults to @command{etags}.
|
|
|
|
@item etags-regen-program-options
|
|
Command-line options to pass to the program which regenerates tags
|
|
tables.
|
|
|
|
@item etags-regen-ignores
|
|
List of glob patterns which specify files to ignore when regenerating
|
|
tags tables.
|
|
@end vtable
|
|
|
|
@cindex tags-reset-tags-tables
|
|
If you select a tags table manually, with @kbd{M-x visit-tags-table}
|
|
(@pxref{Select Tags Table}), @code{etags-regen-mode} effectively
|
|
disables itself: it will no longer automatically create and update
|
|
tags tables, assuming that you prefer managing your tags tables
|
|
manually. You can cancel this effect of using @code{visit-tags-table}
|
|
by invoking the command @code{tags-reset-tags-tables}.
|
|
|
|
@node Etags Regexps
|
|
@subsubsection Etags Regexps
|
|
|
|
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
|
|
|
|
@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 C character escape sequences are supported: @samp{\a} for
|
|
bell, @samp{\b} for back space, @samp{\e} for escape, @samp{\f} for
|
|
formfeed, @samp{\n} for newline, @samp{\r} for carriage return,
|
|
@samp{\t} for tab, and @samp{\v} for vertical tab. In addition,
|
|
@samp{\d} stands for the @code{DEL} character.
|
|
|
|
Ideally, @var{tagregexp} should not match more characters than are
|
|
needed to recognize what you want to tag. If the syntax requires you
|
|
to write @var{tagregexp} so it matches more characters beyond the tag
|
|
itself, you should add a @var{nameregexp}, to pick out just the tag.
|
|
This will enable Emacs to find tags more accurately and to do
|
|
completion on tag names more reliably. In @var{nameregexp}, it is
|
|
frequently convenient to use ``back references'' (@pxref{Regexp
|
|
Backslash}) to parenthesized groupings @w{@samp{\( @dots{} \)}} in
|
|
@var{tagregexp}. For example, @samp{\1} refers to the first such
|
|
parenthesized grouping. You can find some examples of this below.
|
|
|
|
The @var{modifiers} are a sequence of zero or more characters that
|
|
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:
|
|
|
|
@table @samp
|
|
@item i
|
|
Ignore case when matching this regexp.
|
|
@item m
|
|
Match this regular expression against the whole file, so that
|
|
multi-line matches are possible.
|
|
@item s
|
|
Match this regular expression against the whole file, and allow
|
|
@samp{.} in @var{tagregexp} to match newlines.
|
|
@end table
|
|
|
|
The @samp{-R} option cancels all the regexps defined by preceding
|
|
@samp{--regex} options. It too applies to the file names following
|
|
it. Here's an example:
|
|
|
|
@smallexample
|
|
etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
|
|
bar.ber -R --lang=lisp los.er
|
|
@end smallexample
|
|
|
|
@noindent
|
|
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. @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
|
|
@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:
|
|
|
|
@smallexample
|
|
--regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/'
|
|
@end smallexample
|
|
|
|
@noindent
|
|
When you have complex regular expressions, you can store the list of
|
|
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.
|
|
|
|
@smallexample
|
|
--regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file}
|
|
@end smallexample
|
|
|
|
@noindent
|
|
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{@@}, @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
|
|
non-whitespace text on the line is @samp{--}, that line is a comment.
|
|
|
|
For example, we can create a file called @samp{emacs.tags} with the
|
|
following contents:
|
|
|
|
@smallexample
|
|
-- This is for GNU Emacs C source files
|
|
@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
|
|
@end smallexample
|
|
|
|
@noindent
|
|
and then use it like this:
|
|
|
|
@smallexample
|
|
etags --regex=@@emacs.tags *.[ch] */*.[ch]
|
|
@end smallexample
|
|
|
|
Here are some more examples. The regexps are quoted to protect them
|
|
from shell interpretation.
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
Tag Octave files:
|
|
|
|
@smallexample
|
|
etags --language=none \
|
|
--regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
|
|
--regex='/###key \(.*\)/\1/' \
|
|
--regex='/[ \t]*global[ \t].*/' \
|
|
*.m
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Note that tags are not generated for scripts, so that you have to add
|
|
a line by yourself of the form @samp{###key @var{scriptname}} if you
|
|
want to jump to it.
|
|
|
|
@item
|
|
Tag Tcl files:
|
|
|
|
@smallexample
|
|
etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
|
|
@end smallexample
|
|
|
|
@item
|
|
Tag VHDL files:
|
|
|
|
@smallexample
|
|
etags --language=none \
|
|
--regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
|
|
--regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
|
|
\( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
|
|
@end smallexample
|
|
@end itemize
|
|
|
|
@node Select Tags Table
|
|
@subsection Selecting a Tags Table
|
|
|
|
@findex visit-tags-table
|
|
Emacs has at any time at most one @dfn{selected} tags table. All
|
|
the commands for working with tags tables use the selected one first.
|
|
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} defaulting
|
|
to the first directory that contains a file named @file{TAGS}
|
|
encountered when recursively searching upward from the default
|
|
directory.
|
|
|
|
@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 not much more. The
|
|
variable's initial value is @code{nil}; that value tells all the
|
|
commands for working with tags tables that they must ask for a tags
|
|
table file name to use.
|
|
|
|
In addition to the selected tags table, Emacs maintains the list of
|
|
several tags tables that you use together. For example, if you are
|
|
working on a program that uses a library, you may wish to have the
|
|
tags tables of both the program and the library available, so that
|
|
Emacs could easily find identifiers from both. If the selected tags
|
|
table doesn't have the identifier or doesn't mention the source file a
|
|
tags command needs, the command will try using all the other tags
|
|
tables in the current list of tags tables.
|
|
|
|
Using @code{visit-tags-table} to load a new tags table when another
|
|
tags table is already loaded gives you a choice: you can add the new
|
|
tags table to the current list of tags tables, or discard the current
|
|
list and start a new list. If you start a new list, the new tags
|
|
table is used @emph{instead} of others. If you add the new table to
|
|
the current list, it is used @emph{as well as} the others.
|
|
|
|
@vindex tags-table-list
|
|
You can specify a precise list of tags tables by setting the variable
|
|
@code{tags-table-list} to a list of directory names, like this:
|
|
|
|
@c keep this on two lines for formatting in smallbook
|
|
@example
|
|
@group
|
|
(setq tags-table-list
|
|
'("~/.emacs.d" "/usr/local/lib/emacs/src"))
|
|
@end group
|
|
@end example
|
|
|
|
@noindent
|
|
This tells the tags commands to look at the @file{TAGS} files in your
|
|
@file{~/.emacs.d} directory and in the @file{/usr/local/lib/emacs/src}
|
|
directory. The order depends on which file you are in and which tags
|
|
table mentions that file.
|
|
|
|
Do not set both @code{tags-file-name} and @code{tags-table-list}.
|
|
|
|
@node EDE
|
|
@section Emacs Development Environment
|
|
@cindex EDE (Emacs Development Environment)
|
|
@cindex Emacs Development Environment
|
|
@cindex Integrated development environment
|
|
|
|
EDE (@dfn{Emacs Development Environment}) is a package that simplifies
|
|
the task of creating, building, and debugging large programs with
|
|
Emacs. It provides some of the features of an IDE, or @dfn{Integrated
|
|
Development Environment}, in Emacs.
|
|
|
|
This section provides a brief description of EDE usage.
|
|
@ifnottex
|
|
For full details, see @ref{Top, EDE,, ede, Emacs Development Environment}.
|
|
@end ifnottex
|
|
@iftex
|
|
For full details on Ede, type @kbd{C-h i} and then select the EDE
|
|
manual.
|
|
@end iftex
|
|
|
|
EDE is implemented as a global minor mode (@pxref{Minor Modes}). To
|
|
enable it, type @kbd{M-x global-ede-mode} or click on the
|
|
@samp{Project Support (EDE)} item in the @samp{Tools} menu. You can
|
|
also enable EDE each time you start Emacs, by adding the following
|
|
line to your initialization file:
|
|
|
|
@smallexample
|
|
(global-ede-mode t)
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Activating EDE adds a menu named @samp{Development} to the menu bar.
|
|
Many EDE commands, including the ones described below, can be invoked
|
|
from this menu.
|
|
|
|
EDE organizes files into @dfn{projects}, which correspond to
|
|
directory trees. The @dfn{project root} is the topmost directory of a
|
|
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,
|
|
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,
|
|
EDE also creates a file named @file{Project.ede}, which stores
|
|
information about the project.
|
|
|
|
A project may contain one or more @dfn{targets}. A target can be an
|
|
object file, executable program, or some other type of file, which is
|
|
built from one or more of the files in the project.
|
|
|
|
To add a new @dfn{target} to a project, type @kbd{C-c . t}
|
|
(@code{M-x ede-new-target}). This command also asks if you wish to
|
|
add the current file to that target, which means that the target
|
|
is to be built from that file. After you have defined a target, you
|
|
can add more files to it by typing @kbd{C-c . a}
|
|
(@code{ede-add-file}).
|
|
|
|
To build a target, type @kbd{C-c . c} (@code{ede-compile-target}).
|
|
To build all the targets in the project, type @kbd{C-c . C}
|
|
(@code{ede-compile-project}). EDE uses the file types to guess how
|
|
the target should be built.
|
|
|
|
@ifnottex
|
|
@include emerge-xtra.texi
|
|
@end ifnottex
|
|
|
|
|
|
@node Bug Reference
|
|
@section Bug Reference
|
|
@cindex bug reference
|
|
|
|
Most projects with a certain amount of users track bug reports in some
|
|
issue tracking software which assigns each report a unique and short
|
|
number or identifier. Those are used to reference a given bug, e.g.,
|
|
in a source code comment above the code fixing some bug, in
|
|
documentation files, or in discussions on some mailing list or IRC
|
|
channel.
|
|
|
|
@findex bug-reference-mode
|
|
@findex bug-reference-prog-mode
|
|
The minor modes @code{bug-reference-mode} and
|
|
@code{bug-reference-prog-mode} highlight such bug references and make
|
|
it possible to follow them to the corresponding bug report on the
|
|
project's issue tracker. @code{bug-reference-prog-mode} is a variant
|
|
of @code{bug-reference-mode} which highlights bug references only
|
|
inside source code comments and strings.
|
|
|
|
@vindex bug-reference-bug-regexp
|
|
@vindex bug-reference-url-format
|
|
For its working, bug reference mode needs to know the syntax of bug
|
|
references (@code{bug-reference-bug-regexp}), and the URL of the
|
|
tracker where bug reports can be looked up
|
|
(@code{bug-reference-url-format}). Since those are typically
|
|
different from project to project, it makes sense to specify them in
|
|
@pxref{Directory Variables} or @pxref{File Variables}.
|
|
|
|
For example, let's assume in our project, we usually write references
|
|
to bug reports as bug#1234, or Bug-1234 and that this bug's page on
|
|
the issue tracker is @url{https://project.org/issues/1234}, then
|
|
these local variables section would do.
|
|
|
|
@smallexample
|
|
;; Local Variables:
|
|
;; bug-reference-bug-regexp: "\\([Bb]ug[#-]\\([0-9]+\\)\\)"
|
|
;; bug-reference-url-format: "https://project.org/issues/%s"
|
|
;; End:
|
|
@end smallexample
|
|
|
|
The string captured by the first regexp group defines the bounds of
|
|
the overlay bug-reference creates, i.e., the part which is highlighted
|
|
and made clickable.
|
|
|
|
The string captured by the second regexp group in
|
|
@code{bug-reference-bug-regexp} is used to replace the @code{%s}
|
|
template in the @code{bug-reference-url-format}.
|
|
|
|
Note that @code{bug-reference-url-format} may also be a function in
|
|
order to cater for more complex scenarios, e.g., when different parts
|
|
of the bug reference have to be used to distinguish between issues and
|
|
merge requests resulting in different URLs.
|
|
|
|
|
|
@heading Automatic Setup
|
|
|
|
@vindex bug-reference-auto-setup-functions
|
|
If @code{bug-reference-mode} is activated,
|
|
@code{bug-reference-mode-hook} has been run, and either
|
|
@code{bug-reference-bug-regexp} or @code{bug-reference-url-format} is
|
|
still @code{nil}, the mode will try to automatically find a suitable
|
|
value for these two variables by calling the functions in
|
|
@code{bug-reference-auto-setup-functions} one by one until one
|
|
succeeds.
|
|
|
|
@vindex bug-reference-setup-from-vc-alist
|
|
@vindex bug-reference-forge-alist
|
|
@vindex bug-reference-setup-from-mail-alist
|
|
@vindex bug-reference-setup-from-irc-alist
|
|
Right now, there are three types of setup functions.
|
|
|
|
@enumerate
|
|
@item
|
|
Setup for version-controlled files configurable by the variables
|
|
@code{bug-reference-forge-alist}, and
|
|
@code{bug-reference-setup-from-vc-alist}. The defaults are able to
|
|
set up GNU projects where @url{https://debbugs.gnu.org} is used as
|
|
issue tracker and issues are usually referenced as @code{bug#13} (but
|
|
many different notations are considered, too), as well as several
|
|
other kinds of software forges such as GitLab, Gitea, SourceHut, and
|
|
GitHub. If you deploy a self-hosted instance of such a forge, the
|
|
easiest way to tell bug-reference about it is through
|
|
@code{bug-reference-forge-alist}.
|
|
|
|
@item
|
|
Setup for email guessing from mail folder/mbox names, and mail header
|
|
values configurable by the variable
|
|
@code{bug-reference-setup-from-mail-alist}. The built-in news- and
|
|
mailreader @ref{Gnus} and @ref{Rmail} are supported.
|
|
|
|
@item
|
|
Setup for IRC channels configurable by the variable
|
|
@code{bug-reference-setup-from-irc-alist}. The built-in IRC clients
|
|
Rcirc, @xref{Top, Rcirc,, rcirc, The Rcirc Manual}, and ERC,
|
|
@xref{Top, ERC,, erc, The ERC Manual}, are supported.
|
|
@end enumerate
|
|
|
|
For almost all of those modes, it's enough to simply enable
|
|
@code{bug-reference-mode}; only Rmail requires a slightly different
|
|
setup.
|
|
|
|
@smallexample
|
|
;; Use VC-based setup if file is under version control.
|
|
(add-hook 'prog-mode-hook #'bug-reference-prog-mode)
|
|
|
|
;; Gnus (summary & article buffers)
|
|
(add-hook 'gnus-mode-hook #'bug-reference-mode)
|
|
|
|
;; Rmail
|
|
(add-hook 'rmail-show-message-hook #'bug-reference-mode-force-auto-setup)
|
|
|
|
;; Rcirc
|
|
(add-hook 'rcirc-mode-hook #'bug-reference-mode)
|
|
|
|
;; ERC
|
|
(add-hook 'erc-mode-hook #'bug-reference-mode)
|
|
@end smallexample
|
|
|
|
In the Rmail case, instead of the mode hook, the
|
|
@code{rmail-show-message-hook} has to be used in combination with the
|
|
function @code{bug-reference-mode-force-auto-setup} which activates
|
|
@code{bug-reference-mode} and forces auto-setup. The reason is that
|
|
with Rmail all messages reside in the same buffer but the setup needs
|
|
to be performed whenever another messages is displayed.
|
|
|
|
|
|
@heading Adding support for third-party packages
|
|
|
|
@vindex bug-reference-auto-setup-functions
|
|
Adding support for bug-reference auto-setup is usually quite
|
|
straightforward: write a setup function of zero arguments which
|
|
gathers the required information (e.g., List-Id/To/From/Cc mail header
|
|
values in the case of a MUA), and then calls one of the following
|
|
helper functions:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@code{bug-reference-maybe-setup-from-vc}, which does the setup
|
|
according to @code{bug-reference-setup-from-vc-alist};
|
|
|
|
@item
|
|
@code{bug-reference-maybe-setup-from-mail}, which does the setup
|
|
according to @code{bug-reference-setup-from-mail-alist}; and
|
|
|
|
@item
|
|
@code{bug-reference-maybe-setup-from-irc}, which does the setup
|
|
according to @code{bug-reference-setup-from-irc-alist}.
|
|
@end itemize
|
|
|
|
A setup function should return non-@code{nil} if it could set up
|
|
bug-reference mode, which is the case if the last thing the function
|
|
does is call one of the helper functions above.
|
|
|
|
Finally, the setup function has to be added to
|
|
@code{bug-reference-auto-setup-functions}.
|
|
|
|
Note that these auto-setup functions should check as a first step if
|
|
they are applicable, e.g., by checking the value of @code{major-mode}.
|
|
|
|
|
|
@heading Integration with the debbugs package
|
|
|
|
@findex debbugs-browse-mode
|
|
If your project's issues are tracked on the server
|
|
@url{https://debbugs.gnu.org}, you can browse and reply to reports
|
|
directly in Emacs using the @code{debbugs} package, which can be
|
|
downloaded via the Package Menu (@pxref{Packages}). This package adds
|
|
the minor mode @code{debbugs-browse-mode}, which can be activated on
|
|
top of @code{bug-reference-mode} and @code{bug-reference-prog-mode} as
|
|
follows:
|
|
|
|
@smallexample
|
|
(add-hook 'bug-reference-mode-hook 'debbugs-browse-mode)
|
|
(add-hook 'bug-reference-prog-mode-hook 'debbugs-browse-mode)
|
|
@end smallexample
|