0001: @c This is part of the Emacs manual., Abbrevs, This is part of the Emacs manual., Top
0002: @c Copyright (C) 1985-1987, 1993-1995, 1997, 1999-2019 Free Software
0003: @c Foundation, Inc.
0004: @c See file emacs.texi for copying conditions.
0005: @node Maintaining
0006: @chapter Maintaining Large Programs
0007: 
0008:   This chapter describes Emacs features for maintaining medium- to
0009: large-size programs and packages.  These features include:
0010: 
0011: @itemize @minus
0012: @item
0013: Unified interface to Support for Version Control Systems
0014: (@acronym{VCS}) that record the history of changes to source files.
0015: 
0016: @item
0017: A specialized mode for maintaining @file{ChangeLog} files that provide
0018: a chronological log of program changes.
0019: 
0020: @item
0021: @acronym{Xref}, a set of commands for displaying definitions of
0022: symbols (a.k.a.@: ``identifiers'') and their references.
0023: 
0024: @item
0025: @acronym{EDE}, the Emacs's own IDE.
0026: 
0027: @ifnottex
0028: @item
0029: A mode for merging changes to program sources made on separate
0030: branches of development.
0031: @end ifnottex
0032: @end itemize
0033: 
0034: If you are maintaining a large Lisp program, then in addition to the
0035: features described here, you may find the Emacs Lisp Regression
0036: Testing (@acronym{ERT}) library useful (@pxref{Top,,ERT,ert, Emacs
0037: Lisp Regression Testing}).
0038: 
0039: @menu
0040: * Version Control::     Using version control systems.
0041: * Change Log::          Maintaining a change history for your program.
0042: * Xref::                Find definitions and references of any function,
0043:                           method, struct, macro, @dots{} in your program.
0044: * EDE::                 An integrated development environment for Emacs.
0045: @ifnottex
0046: * Emerge::              A convenient way of merging two versions of a program.
0047: @end ifnottex
0048: @end menu
0049: 
0050: @node Version Control
0051: @section Version Control
0052: @cindex version control
0053: 
0054:   A @dfn{version control system} is a program that can record multiple
0055: versions of a source file, storing information such as the creation
0056: time of each version, who made it, and a description of what was
0057: changed.
0058: 
0059: @cindex VC
0060:   The Emacs version control interface is called @dfn{VC}@.  VC
0061: commands work with several different version control systems;
0062: currently, it supports Bazaar, CVS, Git, Mercurial, Monotone, RCS,
0063: SRC, SCCS/CSSC, and Subversion.  Of these, the GNU project distributes
0064: CVS, RCS, and Bazaar.
0065: 
0066:   VC is enabled automatically whenever you visit a file governed by a
0067: version control system.  To disable VC entirely, set the customizable
0068: variable @code{vc-handled-backends} to @code{nil}
0069: @iftex
0070: (@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
0071: @end iftex
0072: @ifnottex
0073: (@pxref{Customizing VC}).
0074: @end ifnottex
0075: 
0076: @findex vc-refresh-state
0077: @findex vc-state-refresh
0078:   To update the VC state information for the file visited in the
0079: current buffer, use the command @code{vc-refresh-state}.  This command
0080: is useful when you perform version control commands outside Emacs
0081: (e.g., from the shell prompt), or if you put the buffer's file under a
0082: different version control system, or remove it from version control
0083: entirely.
0084: 
0085: @menu
0086: * Introduction to VC::  How version control works in general.
0087: * VC Mode Line::        How the mode line shows version control status.
0088: * Basic VC Editing::    How to edit a file under version control.
0089: * Log Buffer::          Features available in log entry buffers.
0090: * Registering::         Putting a file under version control.
0091: * Old Revisions::       Examining and comparing old versions.
0092: * VC Change Log::       Viewing the VC Change Log.
0093: * VC Undo::             Canceling changes before or after committing.
0094: * VC Ignore::           Ignore files under version control system.
0095: * VC Directory Mode::   Listing files managed by version control.
0096: * Branches::            Multiple lines of development.
0097: @ifnottex
0098: * Miscellaneous VC::    Various other commands and features of VC.
0099: * Customizing VC::      Variables that change VC's behavior.
0100: @end ifnottex
0101: @end menu
0102: 
0103: @node Introduction to VC
0104: @subsection Introduction to Version Control
0105: 
0106:   VC allows you to use a version control system from within Emacs,
0107: integrating the version control operations smoothly with editing.  It
0108: provides a uniform interface for common operations in many version
0109: control operations.
0110: 
0111:   Some uncommon or intricate version control operations, such as
0112: altering repository settings, are not supported in VC@.  You should
0113: perform such tasks outside VC, e.g., via the command line.
0114: 
0115:   This section provides a general overview of version control, and
0116: describes the version control systems that VC supports.  You can skip
0117: this section if you are already familiar with the version control system
0118: you want to use.
0119: 
0120: @menu
0121: * Why Version Control?::    Understanding the problems it addresses.
0122: * Version Control Systems:: Supported version control back-end systems.
0123: * VCS Concepts::            Words and concepts related to version control.
0124: * VCS Merging::             How file conflicts are handled.
0125: * VCS Changesets::          How changes are grouped.
0126: * VCS Repositories::        Where version control repositories are stored.
0127: * Types of Log File::       The VCS log in contrast to the ChangeLog.
0128: @end menu
0129: 
0130: @node Why Version Control?
0131: @subsubsection Understanding the Problems it Addresses
0132: 
0133:   Version control systems provide you with three important
0134: capabilities:
0135: 
0136: @itemize @bullet
0137: @item
0138: @dfn{Reversibility}: the ability to back up to a previous state if you
0139: discover that some modification you did was a mistake or a bad idea.
0140: 
0141: @item
0142: @dfn{Concurrency}: the ability to have many people modifying the same
0143: collection of files knowing that conflicting modifications can be
0144: detected and resolved.
0145: 
0146: @item
0147: @dfn{History}: the ability to attach historical data to your data,
0148: such as explanatory comments about the intention behind each change.
0149: Even for a programmer working solo, change histories are an important
0150: aid to memory; for a multi-person project, they are a vitally
0151: important form of communication among developers.
0152: @end itemize
0153: 
0154: @node Version Control Systems
0155: @subsubsection Supported Version Control Systems
0156: 
0157: @cindex back end (version control)
0158:   VC currently works with many different version control systems,
0159: which it refers to as @dfn{back ends}:
0160: 
0161: @itemize @bullet
0162: 
0163: @cindex SCCS
0164: @item
0165: SCCS was the first version control system ever built, and was long ago
0166: superseded by more advanced ones.  VC compensates for certain features
0167: missing in SCCS (e.g., tag names for releases) by implementing them
0168: itself.  Other VC features, such as multiple branches, are simply
0169: unavailable.  Since SCCS is non-free, we recommend avoiding it.
0170: 
0171: @cindex CSSC
0172: @item
0173: CSSC is a free replacement for SCCS@.  You should use CSSC only if, for
0174: some reason, you cannot use a more recent and better-designed version
0175: control system.
0176: 
0177: @cindex RCS
0178: @item
0179: RCS is the free version control system around which VC was initially
0180: built.  It is relatively primitive: it cannot be used over the
0181: network, and works at the level of individual files.  Almost
0182: everything you can do with RCS can be done through VC.
0183: 
0184: @cindex CVS
0185: @item
0186: CVS is the free version control system that was, until circa 2008,
0187: used by the majority of free software projects.  Since then, it has
0188: been superseded by newer systems.  CVS allows concurrent multi-user
0189: development either locally or over the network.  Unlike newer systems,
0190: it lacks support for atomic commits and file moving/renaming.  VC
0191: supports all basic editing operations under CVS.
0192: 
0193: @cindex SVN
0194: @cindex Subversion
0195: @item
0196: Subversion (svn) is a free version control system designed to be
0197: similar to CVS but without its problems (e.g., it supports atomic
0198: commits of filesets, and versioning of directories, symbolic links,
0199: meta-data, renames, copies, and deletes).
0200: 
0201: @cindex git
0202: @item
0203: Git is a decentralized version control system originally invented by
0204: Linus Torvalds to support development of Linux (his kernel).  VC
0205: supports many common Git operations, but others, such as repository
0206: syncing, must be done from the command line.
0207: 
0208: @cindex hg
0209: @cindex Mercurial
0210: @item
0211: Mercurial (hg) is a decentralized version control system broadly
0212: resembling Git.  VC supports most Mercurial commands, with the
0213: exception of repository sync operations.
0214: 
0215: @cindex bzr
0216: @cindex Bazaar
0217: @item
0218: Bazaar (bzr) is a decentralized version control system that supports
0219: both repository-based and decentralized versioning.  VC supports most
0220: basic editing operations under Bazaar.
0221: 
0222: @cindex SRC
0223: @cindex src
0224: @item
0225: SRC (src) is RCS, reloaded---a specialized version-control system
0226: designed for single-file projects worked on by only one person.  It
0227: allows multiple files with independent version-control histories to
0228: exist in one directory, and is thus particularly well suited for
0229: maintaining small documents, scripts, and dotfiles.  While it uses RCS
0230: for revision storage, it presents a modern user interface featuring
0231: lockless operation and integer sequential version numbers.  VC
0232: supports almost all SRC operations.
0233: @end itemize
0234: 
0235: @node VCS Concepts
0236: @subsubsection Concepts of Version Control
0237: 
0238: @cindex repository
0239: @cindex registered file
0240:    When a file is under version control, we say that it is
0241: @dfn{registered} in the version control system.  The system has a
0242: @dfn{repository} which stores both the file's present state and its
0243: change history---enough to reconstruct the current version or any
0244: earlier version.  The repository also contains other information, such
0245: as @dfn{log entries} that describe the changes made to each file.
0246: 
0247: @cindex work file
0248: @cindex checking out files
0249:   The copy of a version-controlled file that you actually edit is
0250: called the @dfn{work file}.  You can change each work file as you
0251: would an ordinary file.  After you are done with a set of changes, you
0252: may @dfn{commit} (or @dfn{check in}) the changes; this records the
0253: changes in the repository, along with a descriptive log entry.
0254: 
0255: @cindex working tree
0256:   A directory tree of work files is called a @dfn{working tree}.
0257: 
0258: @cindex revision
0259: @cindex revision ID
0260:   Each commit creates a new @dfn{revision} in the repository.  The
0261: version control system keeps track of all past revisions and the
0262: changes that were made in each revision.  Each revision is named by a
0263: @dfn{revision ID}, whose format depends on the version control system;
0264: in the simplest case, it is just an integer.
0265: 
0266:   To go beyond these basic concepts, you will need to understand three
0267: aspects in which version control systems differ.  As explained in the
0268: next three sections, they can be lock-based or merge-based; file-based
0269: or changeset-based; and centralized or decentralized.  VC handles all
0270: these modes of operation, but it cannot hide the differences.
0271: 
0272: @node VCS Merging
0273: @subsubsection Merge-based vs Lock-based Version Control
0274: 
0275:   A version control system typically has some mechanism to coordinate
0276: between users who want to change the same file.  There are two ways to
0277: do this: merging and locking.
0278: 
0279: @cindex merging-based version
0280:   In a version control system that uses merging, each user may modify
0281: a work file at any time.  The system lets you @dfn{merge} your work
0282: file, which may contain changes that have not been committed, with the
0283: latest changes that others have committed.
0284: 
0285: @cindex locking-based version
0286:   Older version control systems use a @dfn{locking} scheme instead.
0287: Here, work files are normally read-only.  To edit a file, you ask the
0288: version control system to make it writable for you by @dfn{locking}
0289: it; only one user can lock a given file at any given time.  This
0290: procedure is analogous to, but different from, the locking that Emacs
0291: uses to detect simultaneous editing of ordinary files
0292: (@pxref{Interlocking}).  When you commit your changes, that unlocks
0293: the file, and the work file becomes read-only again.  Other users may
0294: then lock the file to make their own changes.
0295: 
0296:   Both locking and merging systems can have problems when multiple
0297: users try to modify the same file at the same time.  Locking systems
0298: have @dfn{lock conflicts}; a user may try to check a file out and be
0299: unable to because it is locked.  In merging systems, @dfn{merge
0300: conflicts} happen when you commit a change to a file that conflicts
0301: with a change committed by someone else after your checkout.  Both
0302: kinds of conflict have to be resolved by human judgment and
0303: communication.  Experience has shown that merging is superior to
0304: locking, both in convenience to developers and in minimizing the
0305: number and severity of conflicts that actually occur.
0306: 
0307:   SCCS always uses locking.  RCS is lock-based by default but can be
0308: told to operate in a merging style.  CVS and Subversion are
0309: merge-based by default but can be told to operate in a locking mode.
0310: Decentralized version control systems, such as Git and Mercurial, are
0311: exclusively merging-based.
0312: 
0313:   VC mode supports both locking and merging version control.  The
0314: terms ``commit'' and ``update'' are used in newer version control
0315: systems; older lock-based systems use the terms ``check in'' and
0316: ``check out''.  VC hides the differences between them as much as
0317: possible.
0318: 
0319: @node VCS Changesets
0320: @subsubsection Changeset-based vs File-based Version Control
0321: 
0322: @cindex file-based version control
0323:   On SCCS, RCS, CVS, and other early version control systems (and also
0324: in SRC), version control operations are @dfn{file-based}: each file
0325: has its own comment and revision history separate from that of all
0326: other files.  Newer systems, beginning with Subversion, are
0327: @dfn{changeset-based}: a commit may include changes to several files,
0328: and the entire set of changes is handled as a unit.  Any comment
0329: associated with the change does not belong to a single file, but to
0330: the changeset itself.
0331: 
0332: @cindex changeset-based version control
0333:   Changeset-based version control is more flexible and powerful than
0334: file-based version control; usually, when a change to multiple files
0335: has to be reversed, it's good to be able to easily identify and remove
0336: all of it.
0337: 
0338: @node VCS Repositories
0339: @subsubsection Decentralized vs Centralized Repositories
0340: 
0341: @cindex centralized version control
0342: @cindex decentralized version control
0343: @cindex distributed version control
0344:   Early version control systems were designed around a
0345: @dfn{centralized} model in which each project has only one repository
0346: used by all developers.  SCCS, RCS, CVS, Subversion, and SRC share this
0347: kind of model.  One of its drawbacks is that the repository is a choke
0348: point for reliability and efficiency.
0349: 
0350:   GNU Arch pioneered the concept of @dfn{distributed} or
0351: @dfn{decentralized} version control, later implemented in Git,
0352: Mercurial, and Bazaar.  A project may have several different
0353: repositories, and these systems support a sort of super-merge between
0354: repositories that tries to reconcile their change histories.  In
0355: effect, there is one repository for each developer, and repository
0356: merges take the place of commit operations.
0357: 
0358:   VC helps you manage the traffic between your personal workfiles and
0359: a repository.  Whether the repository is a single master, or one of a
0360: network of peer repositories, is not something VC has to care about.
0361: 
0362: @node Types of Log File
0363: @subsubsection Types of Log File
0364: @cindex types of log file
0365: @cindex log File, types of
0366: @cindex version control log
0367: 
0368:   Projects that use a version control system can have two types of log
0369: for changes.  One is the log maintained by the version control system:
0370: each time you commit a change, you fill out a @dfn{log entry} for the
0371: change (@pxref{Log Buffer}).  This is called the @dfn{version control
0372: log}.
0373: 
0374:   The other kind of log is the file @file{ChangeLog} (@pxref{Change
0375: Log}).  It provides a chronological record of all changes to a large
0376: portion of a program---typically one directory and its subdirectories.
0377: A small program would use one @file{ChangeLog} file; a large program
0378: may have a @file{ChangeLog} file in each major directory.
0379: @xref{Change Log}.  Programmers have used change logs since long
0380: before version control systems.
0381: 
0382:   Changeset-based version systems typically maintain a changeset-based
0383: modification log for the entire system, which makes change log files
0384: somewhat redundant.  One advantage that they retain is that it is
0385: sometimes useful to be able to view the transaction history of a
0386: single directory separately from those of other directories.  Another
0387: advantage is that commit logs can't be fixed in many version control
0388: systems.
0389: 
0390:   A project maintained with version control can use just the version
0391: control log, or it can use both kinds of logs.  It can handle some
0392: files one way and some files the other way.  Each project has its
0393: policy, which you should follow.
0394: 
0395:   When the policy is to use both, you typically want to write an entry
0396: for each change just once, then put it into both logs.  You can write
0397: the entry in @file{ChangeLog}, then copy it to the log buffer with
0398: @kbd{C-c C-a} when committing the change (@pxref{Log Buffer}).  Or you
0399: can write the entry in the log buffer while committing the change, and
0400: later use the @kbd{C-x v a} command to copy it to @file{ChangeLog}
0401: @iftex
0402: (@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}).
0403: @end iftex
0404: @ifnottex
0405: (@pxref{Change Logs and VC}).
0406: @end ifnottex
0407: 
0408: @node VC Mode Line
0409: @subsection Version Control and the Mode Line
0410: @cindex VC mode line indicator
0411: 
0412:   When you visit a file that is under version control, Emacs indicates
0413: this on the mode line.  For example, @samp{Bzr-1223} says that Bazaar
0414: is used for that file, and the current revision ID is 1223.
0415: 
0416: @cindex version control status
0417:   The character between the back-end name and the revision ID
0418: indicates the @dfn{version control status} of the work file.  In a
0419: merge-based version control system, a @samp{-} character indicates
0420: that the work file is unmodified, and @samp{:} indicates that it has
0421: been modified.  @samp{!} indicates that the file contains conflicts as
0422: result of a recent merge operation (@pxref{Merging}), or that the file
0423: was removed from the version control.  Finally, @samp{?} means that
0424: the file is under version control, but is missing from the working
0425: tree.
0426: 
0427:   In a lock-based system, @samp{-} indicates an unlocked file, and
0428: @samp{:} a locked file; if the file is locked by another user (for
0429: instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
0430: @samp{@@} means that the file was locally added, but not yet committed
0431: to the master repository.
0432: 
0433:   On a graphical display, you can move the mouse over this mode line
0434: indicator to pop up a tool-tip, which displays a more verbose
0435: description of the version control status.  Pressing @kbd{mouse-1}
0436: over the indicator pops up a menu of VC commands, identical to
0437: @samp{Tools / Version Control} on the menu bar.
0438: 
0439: @vindex auto-revert-check-vc-info
0440:   When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is
0441: under version control, it updates the version control information in
0442: the mode line.  However, Auto Revert mode may not properly update this
0443: information if the version control status changes without changes to
0444: the work file, from outside the current Emacs session.  If you set
0445: @code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates
0446: the version control status information every
0447: @code{auto-revert-interval} seconds, even if the work file itself is
0448: unchanged.  The resulting CPU usage depends on the version control
0449: system, but is usually not excessive.
0450: 
0451: @node Basic VC Editing
0452: @subsection Basic Editing under Version Control
0453: 
0454: @cindex filesets, VC
0455: @cindex VC filesets
0456:    Most VC commands operate on @dfn{VC filesets}.  A VC fileset is a
0457: collection of one or more files that a VC operation acts on.  When you
0458: type VC commands in a buffer visiting a version-controlled file, the
0459: VC fileset is simply that one file.  When you type them in a VC
0460: Directory buffer, and some files in it are marked, the VC fileset
0461: consists of the marked files (@pxref{VC Directory Mode}).
0462: 
0463:   On modern changeset-based version control systems (@pxref{VCS
0464: Changesets}), VC commands handle multi-file VC filesets as a group.
0465: For example, committing a multi-file VC fileset generates a single
0466: revision, containing the changes to all those files.  On older
0467: file-based version control systems like CVS, each file in a multi-file
0468: VC fileset is handled individually; for example, a commit generates
0469: one revision for each changed file.
0470: 
0471: @table @kbd
0472: @item C-x v v
0473: Perform the next appropriate version control operation on the current
0474: VC fileset.
0475: @end table
0476: 
0477: @findex vc-next-action
0478: @kindex C-x v v
0479:   The principal VC command is a multi-purpose command, @kbd{C-x v v}
0480: (@code{vc-next-action}), which performs the most appropriate
0481: action on the current VC fileset: either registering it with a version
0482: control system, or committing it, or unlocking it, or merging changes
0483: into it.  The precise actions are described in detail in the following
0484: subsections.  You can use @kbd{C-x v v} either in a file-visiting
0485: buffer or in a VC Directory buffer.
0486: 
0487:   Note that VC filesets are distinct from the named filesets used
0488: for viewing and visiting files in functional groups
0489: (@pxref{Filesets}).  Unlike named filesets, VC filesets are not named
0490: and don't persist across sessions.
0491: 
0492: @menu
0493: * VC With A Merging VCS::  Without locking: default mode for CVS.
0494: * VC With A Locking VCS::  RCS in its default mode, SCCS, and optionally CVS.
0495: * Advanced C-x v v::       Advanced features available with a prefix argument.
0496: @end menu
0497: 
0498: @node VC With A Merging VCS
0499: @subsubsection Basic Version Control with Merging
0500: 
0501:   On a merging-based version control system (i.e., most modern ones;
0502: @pxref{VCS Merging}), @kbd{C-x v v} does the following:
0503: 
0504: @itemize @bullet
0505: @item
0506: If there is more than one file in the VC fileset and the files have
0507: inconsistent version control statuses, signal an error.  (Note,
0508: however, that a fileset is allowed to include both newly-added
0509: files and modified files; @pxref{Registering}.)
0510: 
0511: @item
0512: If none of the files in the VC fileset are registered with a version
0513: control system, register the VC fileset, i.e., place it under version
0514: control.  @xref{Registering}.  If Emacs cannot find a system to
0515: register under, it prompts for a repository type, creates a new
0516: repository, and registers the VC fileset with it.
0517: 
0518: @item
0519: If every work file in the VC fileset is unchanged, do nothing.
0520: 
0521: @item
0522: If every work file in the VC fileset has been modified, commit the
0523: changes.  To do this, Emacs pops up a @file{*vc-log*} buffer; type the
0524: desired log entry for the new revision, followed by @kbd{C-c C-c} to
0525: commit.  @xref{Log Buffer}.
0526: 
0527: If committing to a shared repository, the commit may fail if the
0528: repository has been changed since your last update.  In that
0529: case, you must perform an update before trying again.  On a
0530: decentralized version control system, use @kbd{C-x v +}
0531: (@pxref{Pulling / Pushing}) or @kbd{C-x v m} (@pxref{Merging}).
0532: On a centralized version control system, type @kbd{C-x v v} again to
0533: merge in the repository changes.
0534: 
0535: @item
0536: Finally, if you are using a centralized version control system, check
0537: if each work file in the VC fileset is up-to-date.  If any file has
0538: been changed in the repository, offer to update it.
0539: @end itemize
0540: 
0541:   These rules also apply when you use RCS in its non-locking mode,
0542: except that changes are not automatically merged from the repository.
0543: Nothing informs you if another user has committed changes in the same
0544: file since you began editing it; when you commit your revision, that
0545: other user's changes are removed (however, they remain in the
0546: repository and are thus not irrevocably lost).  Therefore, you must
0547: verify that the current revision is unchanged before committing your
0548: changes.  In addition, locking is possible with RCS even in this mode:
0549: @kbd{C-x v v} with an unmodified file locks the file, just as it does
0550: with RCS in its normal locking mode (@pxref{VC With A Locking VCS}).
0551: 
0552: @node VC With A Locking VCS
0553: @subsubsection Basic Version Control with Locking
0554: 
0555:   On a locking-based version control system (such as SCCS, and RCS in
0556: its default mode), @kbd{C-x v v} does the following:
0557: 
0558: @itemize @bullet
0559: @item
0560: If there is more than one file in the VC fileset and the files have
0561: inconsistent version control statuses, signal an error.
0562: 
0563: @item
0564: If each file in the VC fileset is not registered with a version
0565: control system, register the VC fileset.  @xref{Registering}.  If
0566: Emacs cannot find a system to register under, it prompts for a
0567: repository type, creates a new repository, and registers the VC
0568: fileset with it.
0569: 
0570: @item
0571: If each file is registered and unlocked, lock it and make it writable,
0572: so that you can begin to edit it.
0573: 
0574: @item
0575: If each file is locked by you and contains changes, commit the
0576: changes.  To do this, Emacs pops up a @file{*vc-log*} buffer; type the
0577: desired log entry for the new revision, followed by @kbd{C-c C-c} to
0578: commit (@pxref{Log Buffer}).
0579: 
0580: @item
0581: If each file is locked by you, but you have not changed it, release
0582: the lock and make the file read-only again.
0583: 
0584: @item
0585: If each file is locked by another user, ask whether you want to
0586: steal the lock.  If you say yes, the file becomes locked by you,
0587: and a warning message is sent to the user who had formerly locked the
0588: file.
0589: @end itemize
0590: 
0591:   These rules also apply when you use CVS in locking mode, except
0592: that CVS does not support stealing locks.
0593: 
0594: @node Advanced C-x v v
0595: @subsubsection Advanced Control in @kbd{C-x v v}
0596: 
0597: @cindex revision ID in version control
0598:   When you give a prefix argument to @code{vc-next-action} (@kbd{C-u
0599: C-x v v}), it still performs the next logical version control
0600: operation, but accepts additional arguments to specify precisely how
0601: to do the operation.
0602: 
0603: @itemize @bullet
0604: @item
0605: @cindex specific version control system
0606: You can specify the name of a version control system.  This is useful
0607: if the fileset can be managed by more than one version control system,
0608: and Emacs fails to detect the correct one.
0609: 
0610: @item
0611: Otherwise, if using CVS, RCS or SRC, you can specify a revision ID.
0612: 
0613: If the fileset is modified (or locked), this makes Emacs commit with
0614: that revision ID@.  You can create a new branch by supplying an
0615: appropriate revision ID (@pxref{Branches}).
0616: 
0617: If the fileset is unmodified (and unlocked), this checks the specified
0618: revision into the working tree.  You can also specify a revision on
0619: another branch by giving its revision or branch ID (@pxref{Switching
0620: Branches}).  An empty argument (i.e., @kbd{C-u C-x v v @key{RET}})
0621: checks out the latest (head) revision on the current branch.
0622: 
0623: This is silently ignored on a decentralized version control system.
0624: Those systems do not let you specify your own revision IDs, nor do
0625: they use the concept of checking out individual files.
0626: @end itemize
0627: 
0628: @node Log Buffer
0629: @subsection Features of the Log Entry Buffer
0630: 
0631: @kindex C-c C-c @r{(Log Edit mode)}
0632: @findex log-edit-done
0633:   When you tell VC to commit a change, it pops up a buffer named
0634: @file{*vc-log*}.  In this buffer, you should write a @dfn{log entry}
0635: describing the changes you have made (@pxref{Why Version Control?}).
0636: After you are done, type @kbd{C-c C-c} (@code{log-edit-done}) to exit
0637: the buffer and commit the change, together with your log entry.
0638: 
0639: @cindex Log Edit mode
0640: @cindex mode, Log Edit
0641: @vindex vc-log-mode-hook
0642: @c FIXME: Mention log-edit-mode-hook here?  --xfq
0643:   The major mode for the @file{*vc-log*} buffer is Log Edit mode, a
0644: variant of Text mode (@pxref{Text Mode}).  On entering Log Edit mode,
0645: Emacs runs the hooks @code{text-mode-hook} and @code{vc-log-mode-hook}
0646: (@pxref{Hooks}).
0647: 
0648:   In the @file{*vc-log*} buffer, you can write one or more @dfn{header
0649: lines}, specifying additional information to be supplied to the
0650: version control system.  Each header line must occupy a single line at
0651: the top of the buffer; the first line that is not a header line is
0652: treated as the start of the log entry.  For example, the following
0653: header line states that the present change was not written by you, but
0654: by another developer:
0655: 
0656: @smallexample
0657: Author: J. R. Hacker <jrh@@example.com>
0658: @end smallexample
0659: 
0660: @noindent
0661: Apart from the @samp{Author} header, Emacs recognizes the headers
0662: @samp{Summary} (a one-line summary of the changeset), @samp{Date} (a
0663: manually-specified commit time), and @samp{Fixes} (a reference to a
0664: bug fixed by the change).  Not all version control systems recognize
0665: all headers.  If you specify a header for a system that does not
0666: support it, the header is treated as part of the log entry.
0667: 
0668: @kindex C-c C-f @r{(Log Edit mode)}
0669: @findex log-edit-show-files
0670: @kindex C-c C-d @r{(Log Edit mode)}
0671: @findex log-edit-show-diff
0672:   While in the @file{*vc-log*} buffer, the current VC fileset is
0673: considered to be the fileset that will be committed if you type
0674: @w{@kbd{C-c C-c}}.  To view a list of the files in the VC fileset,
0675: type @w{@kbd{C-c C-f}} (@code{log-edit-show-files}).  To view a diff
0676: of changes between the VC fileset and the version from which you
0677: started editing (@pxref{Old Revisions}), type @kbd{C-c C-d}
0678: (@code{log-edit-show-diff}).
0679: 
0680: @kindex C-c C-a @r{(Log Edit mode)}
0681: @findex log-edit-insert-changelog
0682:   If the VC fileset includes one or more @file{ChangeLog} files
0683: (@pxref{Change Log}), type @kbd{C-c C-a}
0684: (@code{log-edit-insert-changelog}) to pull the relevant entries into
0685: the @file{*vc-log*} buffer.  If the topmost item in each
0686: @file{ChangeLog} was made under your user name on the current date,
0687: this command searches that item for entries matching the file(s) to be
0688: committed, and inserts them.
0689: @ifnottex
0690: If you are using CVS or RCS, see @ref{Change Logs and VC}, for the
0691: opposite way of working---generating ChangeLog entries from the Log
0692: Edit buffer.
0693: @end ifnottex
0694: 
0695:   To abort a commit, just @emph{don't} type @kbd{C-c C-c} in that
0696: buffer.  You can switch buffers and do other editing.  As long as you
0697: don't try to make another commit, the entry you were editing remains
0698: in the @file{*vc-log*} buffer, and you can go back to that buffer at
0699: any time to complete the commit.
0700: 
0701: @kindex M-n @r{(Log Edit mode)}
0702: @kindex M-p @r{(Log Edit mode)}
0703: @kindex M-s @r{(Log Edit mode)}
0704: @kindex M-r @r{(Log Edit mode)}
0705:   You can also browse the history of previous log entries to duplicate
0706: a commit comment.  This can be useful when you want to make several
0707: commits with similar comments.  The commands @kbd{M-n}, @kbd{M-p},
0708: @kbd{M-s} and @kbd{M-r} for doing this work just like the minibuffer
0709: history commands (@pxref{Minibuffer History}), except that they are
0710: used outside the minibuffer.
0711: 
0712: @node Registering
0713: @subsection Registering a File for Version Control
0714: 
0715: @table @kbd
0716: @item C-x v i
0717: Register the visited file for version control.
0718: @end table
0719: 
0720: @kindex C-x v i
0721: @findex vc-register
0722:   The command @kbd{C-x v i} (@code{vc-register}) @dfn{registers} each
0723: file in the current VC fileset, placing it under version control.
0724: This is essentially equivalent to the action of @kbd{C-x v v} on an
0725: unregistered VC fileset (@pxref{Basic VC Editing}), except that if the
0726: VC fileset is already registered, @kbd{C-x v i} signals an error
0727: whereas @kbd{C-x v v} performs some other action.
0728: 
0729:   To register a file, Emacs must choose a version control system.  For
0730: a multi-file VC fileset, the VC Directory buffer specifies the system
0731: to use (@pxref{VC Directory Mode}).  For a single-file VC fileset, if
0732: the file's directory already contains files registered in a version
0733: control system, or if the directory is part of a directory tree
0734: controlled by a version control system, Emacs chooses that system.  In
0735: the event that more than one version control system is applicable,
0736: Emacs uses the one that appears first in the variable
0737: @iftex
0738: @code{vc-handled-backends}.
0739: @end iftex
0740: @ifnottex
0741: @code{vc-handled-backends} (@pxref{Customizing VC}).
0742: @end ifnottex
0743: If Emacs cannot find a version control system to register the file
0744: under, it prompts for a repository type, creates a new repository, and
0745: registers the file into that repository.
0746: 
0747:   On most version control systems, registering a file with @kbd{C-x v
0748: i} or @kbd{C-x v v} adds it to the working tree but not to the
0749: repository.  Such files are labeled as @samp{added} in the VC
0750: Directory buffer, and show a revision ID of @samp{@@@@} in the mode
0751: line.  To make the registration take effect in the repository, you
0752: must perform a commit (@pxref{Basic VC Editing}).  Note that a single
0753: commit can include both file additions and edits to existing files.
0754: 
0755:   On a locking-based version control system (@pxref{VCS Merging}),
0756: registering a file leaves it unlocked and read-only.  Type @kbd{C-x v
0757: v} to start editing it.
0758: 
0759: @node Old Revisions
0760: @subsection Examining And Comparing Old Revisions
0761: 
0762: @table @kbd
0763: @item C-x v =
0764: Compare the work files in the current VC fileset with the versions you
0765: started from (@code{vc-diff}).  With a prefix argument, prompt for two
0766: revisions of the current VC fileset and compare them.  You can also
0767: call this command from a Dired buffer (@pxref{Dired}).
0768: 
0769: @ifnottex
0770: @item M-x vc-ediff
0771: Like @kbd{C-x v =}, but using Ediff.  @xref{Top,, Ediff, ediff, The
0772: Ediff Manual}.
0773: @end ifnottex
0774: 
0775: @item C-x v D
0776: Compare the entire working tree to the revision you started from
0777: (@code{vc-root-diff}).  With a prefix argument, prompt for two
0778: revisions and compare their trees.
0779: 
0780: @item C-x v ~
0781: Prompt for a revision of the current file, and visit it in a separate
0782: buffer (@code{vc-revision-other-window}).
0783: 
0784: @item C-x v g
0785: Display an annotated version of the current file: for each line, show
0786: the latest revision in which it was modified (@code{vc-annotate}).
0787: @end table
0788: 
0789: @findex vc-diff
0790: @kindex C-x v =
0791:   @kbd{C-x v =} (@code{vc-diff}) displays a @dfn{diff} which compares
0792: each work file in the current VC fileset to the version(s) from which
0793: you started editing.  The diff is displayed in another window, in a
0794: Diff mode buffer (@pxref{Diff Mode}) named @file{*vc-diff*}.  The
0795: usual Diff mode commands are available in this buffer.  In particular,
0796: the @kbd{g} (@code{revert-buffer}) command performs the file
0797: comparison again, generating a new diff.
0798: 
0799: @kindex C-u C-x v =
0800:   To compare two arbitrary revisions of the current VC fileset, call
0801: @code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}.  This
0802: prompts for two revision IDs (@pxref{VCS Concepts}), and displays a
0803: diff between those versions of the fileset.  This will not work
0804: reliably for multi-file VC filesets, if the version control system is
0805: file-based rather than changeset-based (e.g., CVS), since then
0806: revision IDs for different files would not be related in any
0807: meaningful way.
0808: 
0809:   Instead of the revision ID, some version control systems let you
0810: specify revisions in other formats.  For instance, under Bazaar you
0811: can enter @samp{date:yesterday} for the argument to @kbd{C-u C-x v =}
0812: (and related commands) to specify the first revision committed after
0813: yesterday.  See the documentation of the version control system for
0814: details.
0815: 
0816:   If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a Dired buffer
0817: (@pxref{Dired}), the file listed on the current line is treated as the
0818: current VC fileset.
0819: 
0820: @ifnottex
0821: @findex vc-ediff
0822:   @kbd{M-x vc-ediff} works like @kbd{C-x v =}, except that it uses an
0823: Ediff session.  @xref{Top,, Ediff, ediff, The Ediff Manual}.
0824: @end ifnottex
0825: 
0826: @findex vc-root-diff
0827: @kindex C-x v D
0828:   @kbd{C-x v D} (@code{vc-root-diff}) is similar to @kbd{C-x v =}, but
0829: it displays the changes in the entire current working tree (i.e., the
0830: working tree containing the current VC fileset).  If you invoke this
0831: command from a Dired buffer, it applies to the working tree containing
0832: the directory.
0833: 
0834: @vindex vc-diff-switches
0835:   You can customize the @command{diff} options that @kbd{C-x v =} and
0836: @kbd{C-x v D} use for generating diffs.  The options used are taken
0837: from the first non-@code{nil} value amongst the variables
0838: @code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, and
0839: @code{diff-switches} (@pxref{Comparing Files}), in that order.  Here,
0840: @var{backend} stands for the relevant version control system,
0841: e.g., @code{bzr} for Bazaar.  Since @code{nil} means to check the
0842: next variable in the sequence, either of the first two may use the
0843: value @code{t} to mean no switches at all.  Most of the
0844: @code{vc-@var{backend}-diff-switches} variables default to @code{nil},
0845: but some default to @code{t}; these are for version control systems
0846: whose @code{diff} implementations do not accept common diff options,
0847: such as Subversion.
0848: 
0849: @findex vc-revision-other-window
0850: @kindex C-x v ~
0851:   To directly examine an older version of a file, visit the work file
0852: and type @kbd{C-x v ~ @var{revision} @key{RET}}
0853: (@code{vc-revision-other-window}).  This retrieves the file version
0854: corresponding to @var{revision}, saves it to
0855: @file{@var{filename}.~@var{revision}~}, and visits it in a separate
0856: window.
0857: 
0858: @findex vc-annotate
0859: @vindex vc-annotate-background-mode
0860: @kindex C-x v g
0861:   Many version control systems allow you to view files @dfn{annotated}
0862: with per-line revision information, by typing @kbd{C-x v g}
0863: (@code{vc-annotate}).  This creates a new ``annotate'' buffer
0864: displaying the file's text, with each line colored to show how old it
0865: is.  Red text is new, blue is old, and intermediate colors indicate
0866: intermediate ages.  By default, the color is scaled over the full
0867: range of ages, such that the oldest changes are blue, and the newest
0868: changes are red.  If the variable @code{vc-annotate-background-mode}
0869: is non-@code{nil}, the colors expressing the age of each line are
0870: applied to the background color, leaving the foreground at its default
0871: color.
0872: 
0873:   When you give a prefix argument to this command, Emacs reads two
0874: arguments using the minibuffer: the revision to display and annotate
0875: (instead of the current file contents), and the time span in days the
0876: color range should cover.
0877: 
0878:   From the ``annotate'' buffer, these and other color scaling options are
0879: available from the @samp{VC-Annotate} menu.  In this buffer, you can
0880: also use the following keys to browse the annotations of past revisions,
0881: view diffs, or view log entries:
0882: 
0883: @table @kbd
0884: @item p
0885: Annotate the previous revision, i.e., the revision before the one
0886: currently annotated.  A numeric prefix argument is a repeat count, so
0887: @kbd{C-u 10 p} would take you back 10 revisions.
0888: 
0889: @item n
0890: Annotate the next revision, i.e., the revision after the one
0891: currently annotated.  A numeric prefix argument is a repeat count.
0892: 
0893: @item j
0894: Annotate the revision indicated by the current line.
0895: 
0896: @item a
0897: Annotate the revision before the one indicated by the current line.
0898: This is useful to see the state the file was in before the change on
0899: the current line was made.
0900: 
0901: @item f
0902: Show in a buffer the file revision indicated by the current line.
0903: 
0904: @item d
0905: Display the diff between the current line's revision and the previous
0906: revision.  This is useful to see what the current line's revision
0907: actually changed in the file.
0908: 
0909: @item D
0910: Display the diff between the current line's revision and the previous
0911: revision for all files in the changeset (for VC systems that support
0912: changesets).  This is useful to see what the current line's revision
0913: actually changed in the tree.
0914: 
0915: @item l
0916: Show the log of the current line's revision.  This is useful to see
0917: the author's description of the changes in the revision on the current
0918: line.
0919: 
0920: @item w
0921: Annotate the working revision--the one you are editing.  If you used
0922: @kbd{p} and @kbd{n} to browse to other revisions, use this key to
0923: return to your working revision.
0924: 
0925: @item v
0926: Toggle the annotation visibility.  This is useful for looking just at
0927: the file contents without distraction from the annotations.
0928: @end table
0929: 
0930: @node VC Change Log
0931: @subsection VC Change Log
0932: 
0933: @table @kbd
0934: @item C-x v l
0935: Display the change history for the current fileset
0936: (@code{vc-print-log}).
0937: 
0938: @item C-x v L
0939: Display the change history for the current repository
0940: (@code{vc-print-root-log}).
0941: 
0942: @item C-x v I
0943: Display the changes that a ``pull'' operation will retrieve
0944: (@code{vc-log-incoming}).
0945: 
0946: @item C-x v O
0947: Display the changes that will be sent by the next ``push'' operation
0948: (@code{vc-log-outgoing}).
0949: @end table
0950: 
0951: @kindex C-x v l
0952: @findex vc-print-log
0953:   @kbd{C-x v l} (@code{vc-print-log}) displays a buffer named
0954: @file{*vc-change-log*}, showing the history of changes made to the
0955: current file, including who made the changes, the dates, and the log
0956: entry for each change (these are the same log entries you would enter
0957: via the @file{*vc-log*} buffer; @pxref{Log Buffer}).  Point is
0958: centered at the revision of the file currently being visited.  With a
0959: prefix argument, the command prompts for the revision to center on,
0960: and the maximum number of revisions to display.
0961: 
0962:   If you call @kbd{C-x v l} from a VC Directory buffer (@pxref{VC
0963: Directory Mode}) or a Dired buffer (@pxref{Dired}), it applies to the
0964: file listed on the current line.
0965: 
0966: @findex vc-print-root-log
0967: @findex log-view-toggle-entry-display
0968:   @kbd{C-x v L} (@code{vc-print-root-log}) displays a
0969: @file{*vc-change-log*} buffer showing the history of the entire
0970: version-controlled directory tree (RCS, SCCS, CVS, and SRC do not
0971: support this feature).  With a prefix argument, the command prompts
0972: for the maximum number of revisions to display.
0973: 
0974:   The @kbd{C-x v L} history is shown in a compact form, usually
0975: showing only the first line of each log entry.  However, you can type
0976: @key{RET} (@code{log-view-toggle-entry-display}) in the
0977: @file{*vc-change-log*} buffer to reveal the entire log entry for the
0978: revision at point.  A second @key{RET} hides it again.
0979: 
0980:   On a decentralized version control system, the @kbd{C-x v I}
0981: (@code{vc-log-incoming}) command displays a log buffer showing the
0982: changes that will be applied, the next time you run the version
0983: control system's pull command to get new revisions from another
0984: repository (@pxref{Pulling / Pushing}).  This other repository is the default
0985: one from which changes are pulled, as defined by the version control
0986: system; with a prefix argument, @code{vc-log-incoming} prompts for a
0987: specific repository.  Similarly, @kbd{C-x v O}
0988: (@code{vc-log-outgoing}) shows the changes that will be sent to
0989: another repository, the next time you run the push command; with a
0990: prefix argument, it prompts for a specific destination repository.
0991: 
0992:   In the @file{*vc-change-log*} buffer, you can use the following keys
0993: to move between the logs of revisions and of files, and to examine and
0994: compare past revisions (@pxref{Old Revisions}):
0995: 
0996: @table @kbd
0997: @item p
0998: Move to the previous revision entry.  (Revision entries in the log
0999: buffer are usually in reverse-chronological order, so the previous
1000: revision-item usually corresponds to a newer revision.)  A numeric
1001: prefix argument is a repeat count.
1002: 
1003: @item n
1004: Move to the next revision entry.  A numeric prefix argument is a
1005: repeat count.
1006: 
1007: @item P
1008: Move to the log of the previous file, if showing logs for a multi-file
1009: VC fileset.  Otherwise, just move to the beginning of the log.  A
1010: numeric prefix argument is a repeat count.
1011: 
1012: @item N
1013: Move to the log of the next file, if showing logs for a multi-file VC
1014: fileset.  A numeric prefix argument is a repeat count.
1015: 
1016: @item a
1017: Annotate the revision on the current line (@pxref{Old Revisions}).
1018: 
1019: @item e
1020: Modify the change comment displayed at point.  Note that not all VC
1021: systems support modifying change comments.
1022: 
1023: @item f
1024: Visit the revision indicated at the current line.
1025: 
1026: @item d
1027: Display a diff between the revision at point and the next earlier
1028: revision, for the specific file.
1029: 
1030: @item D
1031: Display the changeset diff between the revision at point and the next
1032: earlier revision.  This shows the changes to all files made in that
1033: revision.
1034: 
1035: @item @key{RET}
1036: In a compact-style log buffer (e.g., the one created by @kbd{C-x v
1037: L}), toggle between showing and hiding the full log entry for the
1038: revision at point.
1039: @end table
1040: 
1041: @vindex vc-log-show-limit
1042: Because fetching many log entries can be slow, the
1043: @file{*vc-change-log*} buffer displays no more than 2000 revisions by
1044: default.  The variable @code{vc-log-show-limit} specifies this limit;
1045: if you set the value to zero, that removes the limit.  You can also
1046: increase the number of revisions shown in an existing
1047: @file{*vc-change-log*} buffer by clicking on the @samp{Show 2X
1048: entries} or @samp{Show unlimited entries} buttons at the end of the
1049: buffer.  However, RCS, SCCS, CVS, and SRC do not support this feature.
1050: 
1051: @kindex C-x v h
1052: @findex vc-region-history
1053: A useful variant of examining changes is provided by the command
1054: @kbd{vc-region-history} (by default bound to @kbd{C-x v h}), which shows
1055: a @file{*VC-history*} buffer with the history of changes to the region
1056: of the current file between point and the mark (@pxref{Mark}).  The
1057: history of changes includes the commit log messages and also the
1058: changes themselves in the Diff format.
1059: 
1060: Invoke this command after marking the region of the current file in
1061: whose changes you are interested.  In the @file{*VC-history*} buffer
1062: it pops up, you can use all of the commands available in the
1063: @file{*vc-change-log*} buffer described above, and also the commands
1064: defined by Diff mode (@pxref{Diff Mode}).
1065: 
1066: This command is currently available only with Git.
1067: 
1068: @node VC Undo
1069: @subsection Undoing Version Control Actions
1070: 
1071: @table @kbd
1072: @item C-x v u
1073: Revert the work file(s) in the current VC fileset to the last revision
1074: (@code{vc-revert}).
1075: @end table
1076: 
1077: @kindex C-x v u
1078: @findex vc-revert
1079: @vindex vc-revert-show-diff
1080:   If you want to discard all the changes you have made to the current
1081: VC fileset, type @kbd{C-x v u} (@code{vc-revert}).  This shows
1082: you a diff between the work file(s) and the revision from which you
1083: started editing, and asks for confirmation for discarding the changes.
1084: If you agree, the fileset is reverted.  If you don't want @kbd{C-x v
1085: u} to show a diff, set the variable @code{vc-revert-show-diff} to
1086: @code{nil} (you can still view the diff directly with @kbd{C-x v =};
1087: @pxref{Old Revisions}).
1088: 
1089:   On locking-based version control systems, @kbd{C-x v u} leaves files
1090: unlocked; you must lock again to resume editing.  You can also use
1091: @kbd{C-x v u} to unlock a file if you lock it and then decide not to
1092: change it.
1093: 
1094: @node VC Ignore
1095: @subsection Ignore Version Control Files
1096: 
1097: @table @kbd
1098: @item C-x v G
1099: Ignore a file under current version control system.  (@code{vc-ignore}).
1100: @end table
1101: 
1102: @kindex C-x v G
1103: @findex vc-ignore
1104:   Many source trees contain some files that do not need to be
1105: versioned, such as editor backups, object or bytecode files, and built
1106: programs.  You can simply not add them, but then they'll always crop
1107: up as unknown files.  You can also tell the version control system to
1108: ignore these files by adding them to the ignore file at the top of the
1109: tree.  @kbd{C-x v G} (@code{vc-ignore}) can help you do this.  When
1110: called with a prefix argument, you can remove a file from the ignored
1111: file list.
1112: 
1113: @node VC Directory Mode
1114: @subsection VC Directory Mode
1115: 
1116: @cindex VC Directory buffer
1117:   The @dfn{VC Directory buffer} is a specialized buffer for viewing
1118: the version control statuses of the files in a directory tree, and
1119: performing version control operations on those files.  In particular,
1120: it is used to specify multi-file VC filesets for commands like
1121: @w{@kbd{C-x v v}} to act on (@pxref{VC Directory Commands}).
1122: 
1123: @kindex C-x v d
1124: @findex vc-dir
1125:   To use the VC Directory buffer, type @kbd{C-x v d} (@code{vc-dir}).
1126: This reads a directory's name using the minibuffer, and switches to a VC
1127: Directory buffer for that directory.  By default, the buffer is named
1128: @file{*vc-dir*}.  Its contents are described
1129: @iftex
1130: below.
1131: @end iftex
1132: @ifnottex
1133: in @ref{VC Directory Buffer}.
1134: @end ifnottex
1135: 
1136:   The @code{vc-dir} command automatically detects the version control
1137: system to be used in the specified directory.  In the event that more
1138: than one system is being used in the directory, you should invoke the
1139: command with a prefix argument, @kbd{C-u C-x v d}; this prompts for
1140: the version control system which the VC Directory buffer should use.
1141: 
1142: @ifnottex
1143: @cindex PCL-CVS
1144: @pindex cvs
1145: @cindex CVS directory mode
1146:   In addition to the VC Directory buffer, Emacs has a similar facility
1147: called PCL-CVS which is specialized for CVS@.  @xref{Top, , About
1148: PCL-CVS, pcl-cvs, PCL-CVS---The Emacs Front-End to CVS}.
1149: @end ifnottex
1150: 
1151: @menu
1152: * Buffer: VC Directory Buffer.      What the buffer looks like and means.
1153: * Commands: VC Directory Commands.  Commands to use in a VC directory buffer.
1154: @end menu
1155: 
1156: @node VC Directory Buffer
1157: @subsubsection The VC Directory Buffer
1158: 
1159:   The VC Directory buffer contains a list of version-controlled files
1160: and their version control statuses.  It lists files in the current
1161: directory (the one specified when you called @kbd{C-x v d}) and its
1162: subdirectories, but only those with a noteworthy status.  Files
1163: that are up-to-date (i.e., the same as in the repository) are
1164: omitted.  If all the files in a subdirectory are up-to-date, the
1165: subdirectory is not listed either.  As an exception, if a file has
1166: become up-to-date as a direct result of a VC command, it is listed.
1167: 
1168:   Here is an example of a VC Directory buffer listing:
1169: 
1170: @smallexample
1171: @group
1172:                      ./
1173:     edited           configure.ac
1174: *   added            README
1175:     unregistered     temp.txt
1176:                      src/
1177: *   edited           src/main.c
1178: @end group
1179: @end smallexample
1180: 
1181: @noindent
1182: Two work files have been modified but not committed:
1183: @file{configure.ac} in the current directory, and @file{main.c} in the
1184: @file{src/} subdirectory.  The file named @file{README} has been added
1185: but is not yet committed, while @file{temp.txt} is not under version
1186: control (@pxref{Registering}).
1187: 
1188: The @samp{*} characters next to the entries for @file{README} and
1189: @file{src/main.c} indicate that the user has marked these files as
1190: the current VC fileset
1191: @iftex
1192: (see below).
1193: @end iftex
1194: @ifnottex
1195: (@pxref{VC Directory Commands}).
1196: @end ifnottex
1197: 
1198:   The above example is typical for a decentralized version control
1199: system like Bazaar, Git, or Mercurial.  Other systems can show other
1200: statuses.  For instance, CVS shows the @samp{needs-update} status if
1201: the repository has changes that have not been applied to the work
1202: file.  RCS and SCCS show the name of the user locking a file as its
1203: status.
1204: 
1205: @ifnottex
1206:   On CVS, the @code{vc-dir} command normally contacts the repository,
1207: which may be on a remote machine, to check for updates.  If you change
1208: the variable @code{vc-cvs-stay-local} to @code{nil} (@pxref{CVS
1209: Options}), then Emacs avoids contacting a remote repository when
1210: generating the VC Directory buffer (it will still contact it when
1211: necessary, e.g., when doing a commit).  This may be desirable if you
1212: are working offline or the network is slow.
1213: @end ifnottex
1214: 
1215: @vindex vc-directory-exclusion-list
1216:   The VC Directory buffer omits subdirectories listed in the variable
1217: @code{vc-directory-exclusion-list}.  Its default value contains
1218: directories that are used internally by version control systems.
1219: 
1220: @node VC Directory Commands
1221: @subsubsection VC Directory Commands
1222: 
1223:   Emacs provides several commands for navigating the VC Directory
1224: buffer, and for marking files as belonging to the current VC
1225: fileset.
1226: 
1227: @table @kbd
1228: @item n
1229: @itemx @key{SPC}
1230: Move point to the next entry (@code{vc-dir-next-line}).
1231: 
1232: @item p
1233: Move point to the previous entry (@code{vc-dir-previous-line}).
1234: 
1235: @item @key{TAB}
1236: Move to the next directory entry (@code{vc-dir-next-directory}).
1237: 
1238: @item S-@key{TAB}
1239: Move to the previous directory entry
1240: (@code{vc-dir-previous-directory}).
1241: 
1242: @item @key{RET}
1243: @itemx f
1244: Visit the file or directory listed on the current line
1245: (@code{vc-dir-find-file}).
1246: 
1247: @item o
1248: Visit the file or directory on the current line, in a separate window
1249: (@code{vc-dir-find-file-other-window}).
1250: 
1251: @item m
1252: Mark the file or directory on the current line (@code{vc-dir-mark}),
1253: putting it in the current VC fileset.  If the region is active, mark
1254: all files in the region.
1255: 
1256: A file cannot be marked with this command if it is already in a marked
1257: directory, or one of its subdirectories.  Similarly, a directory
1258: cannot be marked with this command if any file in its tree is marked.
1259: 
1260: @item M
1261: If point is on a file entry, mark all files with the same status; if
1262: point is on a directory entry, mark all files in that directory tree
1263: (@code{vc-dir-mark-all-files}).  With a prefix argument, mark all
1264: listed files and directories.
1265: 
1266: @item q
1267: Quit the VC Directory buffer, and bury it (@code{quit-window}).
1268: 
1269: @item u
1270: Unmark the file or directory on the current line.  If the region is
1271: active, unmark all the files in the region (@code{vc-dir-unmark}).
1272: 
1273: @item U
1274: If point is on a file entry, unmark all files with the same status; if
1275: point is on a directory entry, unmark all files in that directory tree
1276: (@code{vc-dir-unmark-all-files}).  With a prefix argument, unmark all
1277: files and directories.
1278: 
1279: @item x
1280: Hide files with @samp{up-to-date} or @samp{ignored} status
1281: (@code{vc-dir-hide-up-to-date}).  With a prefix argument, hide items
1282: whose state is that of the item at point.
1283: @end table
1284: 
1285: @findex vc-dir-mark
1286: @findex vc-dir-mark-all-files
1287:   While in the VC Directory buffer, all the files that you mark with
1288: @kbd{m} (@code{vc-dir-mark}) or @kbd{M} (@code{vc-dir-mark-all-files})
1289: are in the current VC fileset.  If you mark a directory entry with
1290: @kbd{m}, all the listed files in that directory tree are in the
1291: current VC fileset.  The files and directories that belong to the
1292: current VC fileset are indicated with a @samp{*} character in the VC
1293: Directory buffer, next to their VC status.  In this way, you can set
1294: up a multi-file VC fileset to be acted on by VC commands like
1295: @w{@kbd{C-x v v}} (@pxref{Basic VC Editing}), @w{@kbd{C-x v =}}
1296: (@pxref{Old Revisions}), and @w{@kbd{C-x v u}} (@pxref{VC Undo}).
1297: 
1298:   The VC Directory buffer also defines some single-key shortcuts for
1299: VC commands with the @kbd{C-x v} prefix: @kbd{=}, @kbd{+}, @kbd{l},
1300: @kbd{i}, @kbd{D}, @kbd{L}, @kbd{G}, @kbd{I}, @kbd{O}, and @kbd{v}.
1301: 
1302:   For example, you can commit a set of edited files by opening a VC
1303: Directory buffer, where the files are listed with the @samp{edited}
1304: status; marking the files; and typing @kbd{v} or @kbd{C-x v v}
1305: (@code{vc-next-action}).  If the version control system is
1306: changeset-based, Emacs will commit the files in a single revision.
1307: 
1308:   While in the VC Directory buffer, you can also perform search and
1309: replace on the current VC fileset, with the following commands:
1310: 
1311: @table @kbd
1312: @item S
1313: Search the fileset (@code{vc-dir-search}).
1314: 
1315: @item Q
1316: Do a regular expression query replace on the fileset
1317: (@code{vc-dir-query-replace-regexp}).
1318: 
1319: @item M-s a C-s
1320: Do an incremental search on the fileset (@code{vc-dir-isearch}).
1321: 
1322: @item M-s a C-M-s
1323: Do an incremental regular expression search on the fileset
1324: (@code{vc-dir-isearch-regexp}).
1325: @end table
1326: 
1327: @noindent
1328: Apart from acting on multiple files, these commands behave much like
1329: their single-buffer counterparts (@pxref{Search}).
1330: 
1331:   The VC Directory buffer additionally defines some branch-related
1332: commands starting with the prefix @kbd{B}:
1333: 
1334: @table @kbd
1335: @item B c
1336: Create a new branch (@code{vc-create-tag}).
1337: 
1338: @item B l
1339: Prompt for the name of a branch and display the change history of that
1340: branch (@code{vc-print-branch-log}).
1341: 
1342: @item B s
1343: Switch to a branch (@code{vc-retrieve-tag}).  @xref{Switching Branches}.
1344: @end table
1345: 
1346: @cindex stashes in version control
1347: @cindex shelves in version control
1348:   The above commands are also available via the menu bar, and via a
1349: context menu invoked by @kbd{mouse-2}.  Furthermore, some VC backends
1350: use the menu to provide extra backend-specific commands.  For example,
1351: Git and Bazaar allow you to manipulate @dfn{stashes} and @dfn{shelves}
1352: (which are a way to temporarily put aside uncommitted changes, and
1353: bring them back at a later time).
1354: 
1355: @node Branches
1356: @subsection Version Control Branches
1357: @cindex branch (version control)
1358: 
1359:   One use of version control is to support multiple independent lines
1360: of development, which are called @dfn{branches}.  Amongst other
1361: things, branches can be used for maintaining separate stable and
1362: development versions of a program, and for developing unrelated
1363: features in isolation from one another.
1364: 
1365:   VC's support for branch operations is currently fairly limited.  For
1366: decentralized version control systems, it provides commands for
1367: @dfn{updating} one branch with the contents of another, and for
1368: @dfn{merging} the changes made to two different branches
1369: (@pxref{Merging}).  For centralized version control systems, it
1370: supports checking out different branches and committing into new or
1371: different branches.
1372: 
1373: @menu
1374: * Switching Branches::    How to get to another existing branch.
1375: * Pulling / Pushing::     Receiving/sending changes from/to elsewhere.
1376: * Merging::               Transferring changes between branches.
1377: * Creating Branches::     How to start a new branch.
1378: @end menu
1379: 
1380: @node Switching Branches
1381: @subsubsection Switching between Branches
1382: 
1383:   The various version control systems differ in how branches are
1384: implemented, and these differences cannot be entirely concealed by VC.
1385: 
1386:   On some decentralized version control systems, including Bazaar and
1387: Mercurial in its normal mode of operation, each branch has its own
1388: working directory tree, so switching between branches just involves
1389: switching directories.  On Git, branches are normally @dfn{co-located}
1390: in the same directory, and switching between branches is done using
1391: the @command{git checkout} command, which changes the contents of the
1392: working tree to match the branch you switch to.  Bazaar also supports
1393: co-located branches, in which case the @command{bzr switch} command
1394: will switch branches in the current directory.  With Subversion, you
1395: switch to another branch using the @command{svn switch} command.
1396: 
1397:   The VC command to switch to another branch in the current directory
1398: is @kbd{C-x v r @var{branch-name} @key{RET}} (@code{vc-retrieve-tag}).
1399: 
1400:   On centralized version control systems, you can also switch between
1401: branches by typing @kbd{C-u C-x v v} in an up-to-date work file
1402: (@pxref{Advanced C-x v v}), and entering the revision ID for a
1403: revision on another branch.  On CVS, for instance, revisions on the
1404: @dfn{trunk} (the main line of development) normally have IDs of the
1405: form 1.1, 1.2, 1.3, @dots{}, while the first branch created from (say)
1406: revision 1.2 has revision IDs 1.2.1.1, 1.2.1.2, @dots{}, the second
1407: branch created from revision 1.2 has revision IDs 1.2.2.1, 1.2.2.2,
1408: @dots{}, and so forth.  You can also specify the @dfn{branch ID},
1409: which is a branch revision ID omitting its final component
1410: (e.g., 1.2.1), to switch to the latest revision on that branch.
1411: 
1412:   On a locking-based system, switching to a different branch also
1413: unlocks (write-protects) the working tree.
1414: 
1415:   Once you have switched to a branch, VC commands will apply to that
1416: branch until you switch away; for instance, any VC filesets that you
1417: commit will be committed to that specific branch.
1418: 
1419: @node Pulling / Pushing
1420: @subsubsection Pulling/Pushing Changes into/from a Branch
1421: 
1422: @table @kbd
1423: @item C-x v P
1424: On a decentralized version control system, update another location
1425: with changes from the current branch (a.k.a. ``push'' changes).  This
1426: concept does not exist for centralized version control systems
1427: 
1428: @item C-x v +
1429: On a decentralized version control system, update the current branch
1430: by ``pulling in'' changes from another location.
1431: 
1432: On a centralized version control system, update the current VC
1433: fileset.
1434: @end table
1435: 
1436: @kindex C-x v P
1437: @findex vc-push
1438: On a decentralized version control system, the command @kbd{C-x v P}
1439: (@code{vc-push}) updates another location with changes from the
1440: current branch.  With a prefix argument, it prompts for the exact
1441: version control command to run, which lets you specify where to push
1442: changes; the default is @command{bzr push} with Bazaar, @command{git
1443: push} with Git, and @command{hg push} with Mercurial.  The default
1444: commands always push to a default location determined by the version
1445: control system from your branch configuration.
1446: 
1447: Prior to pushing, you can use @kbd{C-x v O} (@code{vc-log-outgoing})
1448: to view a log buffer of the changes to be sent.  @xref{VC Change Log}.
1449: 
1450: @cindex bound branch (Bazaar VCS)
1451: This command is currently supported only by Bazaar, Git, and Mercurial.
1452: The concept of ``pushing'' does not exist for centralized version
1453: control systems, where this operation is a part of committing a
1454: changeset, so invoking this command on a centralized VCS signals an
1455: error.  This command also signals an error when attempted in a Bazaar
1456: @dfn{bound branch}, where committing a changeset automatically pushes
1457: the changes to the remote repository to which the local branch is
1458: bound.
1459: 
1460: @kindex C-x v +
1461: @findex vc-pull
1462:   On a decentralized version control system, the command @kbd{C-x v +}
1463: (@code{vc-pull}) updates the current branch and working tree.  It is
1464: typically used to update a copy of a remote branch.  If you supply a
1465: prefix argument, the command prompts for the exact version control
1466: command to use, which lets you specify where to pull changes from.
1467: Otherwise, it pulls from a default location determined by the version
1468: control system.
1469: 
1470:   Amongst decentralized version control systems, @kbd{C-x v +} is
1471: currently supported only by Bazaar, Git, and Mercurial.  With Bazaar,
1472: it calls @command{bzr pull} for ordinary branches (to pull from a
1473: master branch into a mirroring branch), and @command{bzr update} for a
1474: bound branch (to pull from a central repository).  With Git, it calls
1475: @command{git pull} to fetch changes from a remote repository and merge
1476: it into the current branch.  With Mercurial, it calls @command{hg pull
1477: -u} to fetch changesets from the default remote repository and update
1478: the working directory.
1479: 
1480:   Prior to pulling, you can use @kbd{C-x v I} (@code{vc-log-incoming})
1481: to view a log buffer of the changes to be applied.  @xref{VC Change
1482: Log}.
1483: 
1484:   On a centralized version control system like CVS, @kbd{C-x v +}
1485: updates the current VC fileset from the repository.
1486: 
1487: @node Merging
1488: @subsubsection Merging Branches
1489: @cindex merging changes
1490: 
1491: @table @kbd
1492: @item C-x v m
1493: On a decentralized version control system, merge changes from another
1494: branch into the current one.
1495: 
1496: On a centralized version control system, merge changes from another
1497: branch into the current VC fileset.
1498: @end table
1499: 
1500:   While developing a branch, you may sometimes need to @dfn{merge} in
1501: changes that have already been made in another branch.  This is not a
1502: trivial operation, as overlapping changes may have been made to the
1503: two branches.
1504: 
1505:   On a decentralized version control system, merging is done with the
1506: command @kbd{C-x v m} (@code{vc-merge}).  On Bazaar, this prompts for
1507: the exact arguments to pass to @command{bzr merge}, offering a
1508: sensible default if possible.  On Git, this prompts for the name of a
1509: branch to merge from, with completion (based on the branch names known
1510: to the current repository).  The output from running the merge command
1511: is shown in a separate buffer.
1512: 
1513:   On a centralized version control system like CVS, @kbd{C-x v m}
1514: prompts for a branch ID, or a pair of revision IDs (@pxref{Switching
1515: Branches}); then it finds the changes from that branch, or the changes
1516: between the two revisions you specified, and merges those changes into
1517: the current VC fileset.  If you just type @kbd{@key{RET}}, Emacs simply
1518: merges any changes that were made on the same branch since you checked
1519: the file out.
1520: 
1521: @cindex conflicts
1522: @cindex resolving conflicts
1523:   Immediately after performing a merge, only the working tree is
1524: modified, and you can review the changes produced by the merge with
1525: @kbd{C-x v D} and related commands (@pxref{Old Revisions}).  If the
1526: two branches contained overlapping changes, merging produces a
1527: @dfn{conflict}; a warning appears in the output of the merge command,
1528: and @dfn{conflict markers} are inserted into each affected work file,
1529: surrounding the two sets of conflicting changes.  You must then
1530: resolve the conflict by editing the conflicted files.  Once you are
1531: done, the modified files must be committed in the usual way for the
1532: merge to take effect (@pxref{Basic VC Editing}).
1533: 
1534: @node Creating Branches
1535: @subsubsection Creating New Branches
1536: 
1537:   On centralized version control systems like CVS, Emacs supports
1538: creating new branches as part of a commit operation.  When committing
1539: a modified VC fileset, type @kbd{C-u C-x v v} (@code{vc-next-action}
1540: with a prefix argument; @pxref{Advanced C-x v v}).  Then Emacs prompts
1541: for a revision ID for the new revision.  You should specify a suitable
1542: branch ID for a branch starting at the current revision.  For example,
1543: if the current revision is 2.5, the branch ID should be 2.5.1, 2.5.2,
1544: and so on, depending on the number of existing branches at that point.
1545: 
1546:   To create a new branch at an older revision (one that is no longer
1547: the head of a branch), first select that revision (@pxref{Switching
1548: Branches}).  Your procedure will then differ depending on whether you
1549: are using a locking or merging-based VCS.
1550: 
1551:   On a locking VCS, you will need to lock the old revision branch with
1552: @kbd{C-x v v}.  You'll be asked to confirm, when you lock the old
1553: revision, that you really mean to create a new branch---if you say no,
1554: you'll be offered a chance to lock the latest revision instead.  On a
1555: merging-based VCS you will skip this step.
1556: 
1557:   Then make your changes and type @kbd{C-x v v} again to commit a new
1558: revision.  This creates a new branch starting from the selected
1559: revision.
1560: 
1561:   After the branch is created, subsequent commits create new revisions
1562: on that branch.  To leave the branch, you must explicitly select a
1563: different revision with @kbd{C-u C-x v v}.
1564: 
1565: @ifnottex
1566: @include vc1-xtra.texi
1567: @end ifnottex
1568: 
1569: @node Change Log
1570: @section Change Logs
1571: 
1572: @cindex change log
1573:   Many software projects keep a @dfn{change log}.  This is a file,
1574: normally named @file{ChangeLog}, containing a chronological record of
1575: when and how the program was changed.  Sometimes, these files are
1576: automatically generated from the change log entries stored in version
1577: control systems, or are used to generate these change log entries.
1578: Sometimes, there are several change log files, each recording the
1579: changes in one directory or directory tree.
1580: 
1581: @menu
1582: * Change Log Commands:: Commands for editing change log files.
1583: * Format of ChangeLog:: What the change log file looks like.
1584: @end menu
1585: 
1586: @node Change Log Commands
1587: @subsection Change Log Commands
1588: 
1589: @kindex C-x 4 a
1590: @findex add-change-log-entry-other-window
1591:   The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
1592: file for the file you are editing
1593: (@code{add-change-log-entry-other-window}).  If that file is actually
1594: a backup file, it makes an entry appropriate for the file's
1595: parent---that is useful for making log entries for functions that
1596: have been deleted in the current version.
1597: 
1598:   @kbd{C-x 4 a} visits the change log file and creates a new entry
1599: unless the most recent entry is for today's date and your name.  It
1600: also creates a new item for the current file.  For many languages, it
1601: can even guess the name of the function or other object that was
1602: changed.
1603: 
1604: @c Not worth it.
1605: @c @vindex change-log-directory-files
1606: To find the change log file, Emacs searches up the directory tree from
1607: the file you are editing.  By default, it stops if it finds a
1608: directory that seems to be the root of a version-control repository.
1609: To change this, customize @code{change-log-directory-files}.
1610: 
1611: @vindex add-log-keep-changes-together
1612:   When the variable @code{add-log-keep-changes-together} is
1613: non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file,
1614: rather than starting a new item.
1615: 
1616: You can combine multiple changes of the same nature.  If you don't
1617: enter any text after the initial @kbd{C-x 4 a}, any subsequent
1618: @kbd{C-x 4 a} adds another symbol to the change log entry.
1619: 
1620: @vindex add-log-always-start-new-record
1621:   If @code{add-log-always-start-new-record} is non-@code{nil},
1622: @kbd{C-x 4 a} always makes a new entry, even if the last entry
1623: was made by you and on the same date.
1624: 
1625: @vindex change-log-version-info-enabled
1626: @vindex change-log-version-number-regexp-list
1627: @cindex file version in change log entries
1628:   If the value of the variable @code{change-log-version-info-enabled}
1629: is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the
1630: change log entry.  It finds the version number by searching the first
1631: ten percent of the file, using regular expressions from the variable
1632: @code{change-log-version-number-regexp-list}.
1633: 
1634: @cindex Change Log mode
1635: @findex change-log-mode
1636:   The change log file is visited in Change Log mode.  In this major
1637: mode, each bunch of grouped items counts as one paragraph, and each
1638: entry is considered a page.  This facilitates editing the entries.
1639: @kbd{C-j} and auto-fill indent each new line like the previous line;
1640: this is convenient for entering the contents of an entry.
1641: 
1642: You can use the @code{next-error} command (by default bound to
1643: @kbd{C-x `}) to move between entries in the Change Log, when Change
1644: Log mode is on.  You will jump to the actual site in the file that was
1645: changed, not just to the next Change Log entry.  You can also use
1646: @code{previous-error} to move back in the same list.
1647: 
1648: @findex change-log-merge
1649:   You can use the command @kbd{M-x change-log-merge} to merge other
1650: log files into a buffer in Change Log Mode, preserving the date
1651: ordering of entries.
1652: 
1653:   Version control systems are another way to keep track of changes in
1654: your program and keep a change log.  In the VC log buffer, typing
1655: @kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant
1656: Change Log entry, if one exists.  @xref{Log Buffer}.
1657: 
1658: @node Format of ChangeLog
1659: @subsection Format of ChangeLog
1660: 
1661:   A change log entry starts with a header line that contains the
1662: current date, your name (taken from the variable
1663: @code{add-log-full-name}), and your email address (taken from the
1664: variable @code{add-log-mailing-address}).  Aside from these header
1665: lines, every line in the change log starts with a space or a tab.  The
1666: bulk of the entry consists of @dfn{items}, each of which starts with a
1667: line starting with whitespace and a star.  Here are two entries, both
1668: dated in May 1993, with two items and one item respectively.
1669: 
1670: @iftex
1671: @medbreak
1672: @end iftex
1673: @smallexample
1674: 1993-05-25  Richard Stallman  <rms@@gnu.org>
1675: 
1676:         * man.el: Rename symbols 'man-*' to 'Man-*'.
1677:         (manual-entry): Make prompt string clearer.
1678: 
1679:         * simple.el (blink-matching-paren-distance):
1680:         Change default to 12,000.
1681: 
1682: 1993-05-24  Richard Stallman  <rms@@gnu.org>
1683: 
1684:         * vc.el (minor-mode-map-alist): Don't use it if it's void.
1685:         (vc-cancel-version): Doc fix.
1686: @end smallexample
1687: 
1688:   One entry can describe several changes; each change should have its
1689: own item, or its own line in an item.  Normally there should be a
1690: blank line between items.  When items are related (parts of the same
1691: change, in different places), group them by leaving no blank line
1692: between them.
1693: 
1694:   You should put a copyright notice and permission notice at the
1695: end of the change log file.  Here is an example:
1696: 
1697: @smallexample
1698: Copyright 1997, 1998 Free Software Foundation, Inc.
1699: Copying and distribution of this file, with or without modification, are
1700: permitted provided the copyright notice and this notice are preserved.
1701: @end smallexample
1702: 
1703: @noindent
1704: Of course, you should substitute the proper years and copyright holder.
1705: 
1706: @node Xref
1707: @section Find Identifier References
1708: @cindex xref
1709: 
1710:   An @dfn{identifier} is a name of a syntactical subunit of the
1711: program: a function, a subroutine, a method, a class, a data type, a
1712: macro, etc.  In a programming language, each identifier is a symbol in
1713: the language's syntax.  Program development and maintenance requires
1714: capabilities to quickly find where each identifier was defined and
1715: referenced, to rename identifiers across the entire project, etc.
1716: 
1717: These capabilities are also useful for finding references in major
1718: modes other than those defined to support programming languages.  For
1719: example, chapters, sections, appendices, etc.@: of a text or a @TeX{}
1720: document can be treated as subunits as well, and their names can be
1721: used as identifiers.  In this chapter, we use the term ``identifiers''
1722: to collectively refer to the names of any kind of subunits, in program
1723: source and in other kinds of text alike.
1724: 
1725: Emacs provides a unified interface to these capabilities, called
1726: @samp{xref}.
1727: 
1728: @cindex xref backend
1729: To do its job, @code{xref} needs to make use of information and to
1730: employ methods specific to the major mode.  What files to search for
1731: identifiers, how to find references to identifiers, how to complete on
1732: identifiers---all this and more is mode-specific knowledge.
1733: @code{xref} delegates the mode-specific parts of its job to a
1734: @dfn{backend} provided by the mode; it also includes defaults for some
1735: of its commands, for those modes that don't provide their own.
1736: 
1737: A backend can implement its capabilities in a variety of ways.  Here
1738: are a few examples:
1739: 
1740: @enumerate a
1741: @item
1742: Some major modes provide built-in means for looking up the language
1743: symbols.  For example, Emacs Lisp symbols can be identified by
1744: searching the package load history, maintained by the Emacs Lisp
1745: interpreter, and by consulting the built-in documentation strings; the
1746: Emacs Lisp mode uses these facilities in its backend to allow finding
1747: definitions of symbols.  (One disadvantage of this kind of backend is
1748: that it only knows about subunits that were loaded into the
1749: interpreter.)
1750: 
1751: @item
1752: An external program can extract references by scanning the relevant
1753: files, and build a database of these references.  A backend can then
1754: access this database whenever it needs to list or look up references.
1755: The Emacs distribution includes @command{etags}, a command for tagging
1756: identifier definitions in programs, which supports many programming
1757: languages and other major modes, such as HTML, by extracting
1758: references into @dfn{tags tables}.  @xref{Create Tags Table}.  Major
1759: modes for languages supported by @command{etags} can use tags tables
1760: as basis for their backend.  (One disadvantage of this kind of backend
1761: is that tags tables need to be kept reasonably up to date, by
1762: rebuilding them from time to time.)
1763: @end enumerate
1764: 
1765: @menu
1766: * Find Identifiers::    Commands to find where an identifier is defined
1767:                           or referenced, to list identifiers, etc.
1768: * Tags Tables::         Tags table records which file defines a symbol.
1769: * Select Tags Table::   How to visit a specific tags table.
1770: @end menu
1771: 
1772: @node Find Identifiers
1773: @subsection Find Identifiers
1774: 
1775:   This subsection describes the commands that find references to
1776: identifiers and perform various queries about identifiers.  Each such
1777: reference could @emph{define} an identifier, e.g., provide the
1778: implementation of a program subunit or the text of a document section;
1779: or it could @emph{use} the identifier, e.g., call a function or a
1780: method, assign a value to a variable, mention a chapter in a
1781: cross-reference, etc.
1782: 
1783: @menu
1784: * Looking Up Identifiers:: Commands to find the definition of an identifier.
1785: * Xref Commands::          Commands in the @file{*xref*} buffer.
1786: * Identifier Search::      Searching and replacing identifiers.
1787: * List Identifiers::       Listing identifiers and completing on them.
1788: @end menu
1789: 
1790: @node Looking Up Identifiers
1791: @subsubsection Looking Up Identifiers
1792: @cindex find definition of symbols
1793: @cindex identifier, finding definition of
1794: @cindex find references to symbols
1795: 
1796:   The most important thing that @code{xref} enables you to do is to find
1797: the definition of a specific identifier.
1798: 
1799: @table @kbd
1800: @item M-.@:
1801: Find definitions of an identifier (@code{xref-find-definitions}).
1802: @item C-M-. @var{pattern} @key{RET}
1803: Find all identifiers whose name matches @var{pattern}
1804: (@code{xref-find-apropos}).
1805: @item C-x 4 .@: @key{RET}
1806: Find definitions of identifier, but display it in another window
1807: (@code{xref-find-definitions-other-window}).
1808: @item C-x 5 .@: @key{RET}
1809: Find definition of identifier, and display it in a new frame
1810: (@code{xref-find-definitions-other-frame}).
1811: @item M-,
1812: Go back to where you previously invoked @kbd{M-.} and friends
1813: (@code{xref-pop-marker-stack}).
1814: @item M-x xref-etags-mode
1815: Switch @code{xref} to use the @code{etags} backend.
1816: @end table
1817: 
1818: @kindex M-.
1819: @findex xref-find-definitions
1820: @vindex xref-prompt-for-identifier
1821:   @kbd{M-.}@: (@code{xref-find-definitions}) shows the definitions of
1822: the identifier at point.  With a prefix argument, or if there's no
1823: identifier at point, it prompts for the identifier.  (If you want it
1824: to always prompt, customize @code{xref-prompt-for-identifier} to
1825: @code{t}.)
1826: 
1827: If the specified identifier has only one definition, the command jumps
1828: to it.  If the identifier has more than one possible definition (e.g.,
1829: in an object-oriented language, or if there's a function and a
1830: variable by the same name), the command shows the candidate
1831: definitions in the @file{*xref*} buffer, together with the files in
1832: which these definitions are found.  Selecting one of these candidates
1833: by typing @kbd{@key{RET}} or clicking @kbd{mouse-2} will pop a buffer
1834: showing the corresponding definition.
1835: 
1836:   When entering the identifier argument to @kbd{M-.}, the usual
1837: minibuffer completion commands can be used (@pxref{Completion}), with
1838: the known identifier names as completion candidates.
1839: 
1840: @kindex C-x 4 .
1841: @findex xref-find-definitions-other-window
1842: @kindex C-x 5 .
1843: @findex xref-find-definitions-other-frame
1844:   Like most commands that can switch buffers,
1845: @code{xref-find-definitions} has a variant that displays the new
1846: buffer in another window, and one that makes a new frame for it.  The
1847: former is @w{@kbd{C-x 4 .}}
1848: (@code{xref-find-definitions-other-window}), and the latter is
1849: @w{@kbd{C-x 5 .}}  (@code{xref-find-definitions-other-frame}).
1850: 
1851: @findex xref-find-apropos
1852: @kindex C-M-.
1853:   The command @kbd{C-M-.} (@code{xref-find-apropos}) finds the
1854: definitions of one or more identifiers that match a specified regular
1855: expression.  It is just like @kbd{M-.} except that it does regexp
1856: matching of identifiers instead of matching symbol names as fixed
1857: strings.
1858: 
1859:   When any of the above commands finds more than one definition, it
1860: presents the @file{*xref*} buffer showing the definition candidates.
1861: In that buffer, you have several specialized commands, described in
1862: @ref{Xref Commands}.
1863: 
1864: @kindex M-,
1865: @findex xref-pop-marker-stack
1866: @vindex xref-marker-ring-length
1867:   To go back to places @emph{from where} you found the definition,
1868: use @kbd{M-,} (@code{xref-pop-marker-stack}).  It jumps back to the
1869: point of the last invocation of @kbd{M-.}.  Thus you can find and
1870: examine the definition of something with @kbd{M-.} and then return to
1871: where you were with @kbd{M-,}.  @kbd{M-,} allows you to retrace your
1872: steps to a depth determined by the variable
1873: @code{xref-marker-ring-length}, which defaults to 16.
1874: 
1875: @findex xref-etags-mode
1876:   Some major modes install @code{xref} support facilities that might
1877: sometimes fail to find certain identifiers.  For example, in Emacs
1878: Lisp mode (@pxref{Lisp Eval}) @kbd{M-.} will by default find only
1879: functions and variables from Lisp packages which are loaded into the
1880: current Emacs session or are auto-loaded (@pxref{Autoload,,, elisp,
1881: The Emacs Lisp Reference Manual}).  If @kbd{M-.} fails to find some
1882: identifiers, you can try forcing @code{xref} to use the @code{etags}
1883: backend (@pxref{Xref}).  To this end, turn on the Xref Etags minor
1884: mode with @w{@kbd{M-x xref-etags-mode}}, then invoke @kbd{M-.} again.
1885: (For this to work, be sure to run @command{etags} to create the tags
1886: table in the directory tree of the source files, see @ref{Create Tags
1887: Table}.)
1888: 
1889: @node Xref Commands
1890: @subsubsection Commands Available in the @file{*xref*} Buffer
1891: @cindex commands in @file{*xref*} buffers
1892: @cindex XREF mode
1893: 
1894:   The following commands are provided in the @file{*xref*} buffer by
1895: the special XREF mode:
1896: 
1897: @table @kbd
1898: @item @key{RET}
1899: @itemx mouse-2
1900: Display the reference on the current line.
1901: 
1902: @item n
1903: @itemx .
1904: @findex xref-next-line
1905: Move to the next reference and display it in the other window
1906: (@code{xref-next-line}).
1907: 
1908: @item p
1909: @itemx ,
1910: @findex xref-prev-line
1911: Move to the previous reference and display it in the other window
1912: (@code{xref-prev-line}).
1913: 
1914: @item C-o
1915: @findex xref-show-location-at-point
1916: Display the reference on the current line in the other window
1917: (@code{xref-show-location-at-point}).
1918: 
1919: @item @key{TAB}
1920: @findex xref-quit-and-goto-xref
1921: Display the reference on the current line and bury the @file{*xref*}
1922: buffer (@code{xref-quit-and-goto-xref}).
1923: 
1924: @item r @var{pattern} @key{RET} @var{replacement} @key{RET}
1925: Perform interactive query-replace on references that match
1926: @var{pattern} (@code{xref-query-replace-in-results}), replacing
1927: the match with @var{replacement}.  @xref{Identifier Search}.
1928: 
1929: @findex xref-quit
1930: @item q
1931: Quit the window showing the @file{*xref*} buffer (@code{xref-quit}).
1932: @end table
1933: 
1934: In addition, the usual navigation commands, such as the arrow keys,
1935: @kbd{C-n}, and @kbd{C-p} are available for moving around the buffer
1936: without displaying the references.
1937: 
1938: @node Identifier Search
1939: @subsubsection Searching and Replacing with Identifiers
1940: @cindex search and replace in multiple source files
1941: @cindex multiple source file search and replace
1942: 
1943:   The commands in this section perform various search and replace
1944: operations either on identifiers themselves or on files that reference
1945: them.
1946: 
1947: @table @kbd
1948: @item M-?
1949: Find all the references for the identifier at point.
1950: 
1951: @item M-x xref-query-replace-in-results @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
1952: Interactively replace @var{regexp} with @var{replacement} in the names
1953: of all the identifiers shown in the @file{*xref*} buffer.
1954: 
1955: @item M-x tags-search @key{RET} @var{regexp} @key{RET}
1956: Search for @var{regexp} through the files in the selected tags
1957: table.
1958: 
1959: @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
1960: Perform a @code{query-replace-regexp} on each file in the selected tags table.
1961: 
1962: @item M-x tags-loop-continue
1963: Restart one of the last 2 commands above, from the current location of point.
1964: @end table
1965: 
1966: @kindex M-?
1967: @findex xref-find-references
1968:   @kbd{M-?} finds all the references for the identifier at point,
1969: prompting for the identifier as needed, with completion.  Depending on
1970: the current backend (@pxref{Xref}), the command may prompt even if it
1971: finds a valid identifier at point.  When invoked with a prefix
1972: argument, it always prompts for the identifier.  (If you want it to
1973: prompt always, customize the value of the variable
1974: @code{xref-prompt-for-identifier} to @code{t}; or set it to @code{nil}
1975: to prompt only if there's no usable identifier at point.)  The command
1976: then presents the @file{*xref*} buffer with all the references to the
1977: identifier, showing the file name and the line where the identifier is
1978: referenced.  The XREF mode commands are available in this buffer, see
1979: @ref{Xref Commands}.
1980: 
1981: @findex xref-query-replace-in-results
1982:   @kbd{M-x xref-query-replace-in-results} reads a regexp to match identifier
1983: names and a replacement string, just like ordinary @kbd{M-x
1984: query-replace-regexp}.  It then performs the specified replacement in
1985: the names of the matching identifiers in all the places in all the
1986: files where these identifiers are referenced.  This is useful when you
1987: rename your identifiers as part of refactoring.  This command should
1988: be invoked in the @file{*xref*} buffer generated by @kbd{M-?}.
1989: 
1990: @findex tags-search
1991:   @kbd{M-x tags-search} reads a regexp using the minibuffer, then
1992: searches for matches in all the files in the selected tags table, one
1993: file at a time.  It displays the name of the file being searched so
1994: you can follow its progress.  As soon as it finds an occurrence,
1995: @code{tags-search} returns.  This command requires tags tables to be
1996: available (@pxref{Tags Tables}).
1997: 
1998: @findex tags-loop-continue
1999:   Having found one match with @code{tags-search}, you probably want to
2000: find all the rest.  @kbd{M-x tags-loop-continue} resumes the
2001: @code{tags-search}, finding one more match.  This searches the rest of
2002: the current buffer, followed by the remaining files of the tags table.
2003: 
2004: @findex tags-query-replace
2005:   @kbd{M-x tags-query-replace} performs a single
2006: @code{query-replace-regexp} through all the files in the tags table.  It
2007: reads a regexp to search for and a string to replace with, just like
2008: ordinary @kbd{M-x query-replace-regexp}.  It searches much like @kbd{M-x
2009: tags-search}, but repeatedly, processing matches according to your
2010: input.  @xref{Query Replace}, for more information on query replace.
2011: 
2012: @vindex tags-case-fold-search
2013: @cindex case-sensitivity and tags search
2014:   You can control the case-sensitivity of tags search commands by
2015: customizing the value of the variable @code{tags-case-fold-search}.  The
2016: default is to use the same setting as the value of
2017: @code{case-fold-search} (@pxref{Lax Search}).
2018: 
2019:   It is possible to get through all the files in the tags table with a
2020: single invocation of @kbd{M-x tags-query-replace}.  But often it is
2021: useful to exit temporarily, which you can do with any input event that
2022: has no special query replace meaning.  You can resume the query
2023: replace subsequently by typing @kbd{M-x tags-loop-continue}; this
2024: command resumes the last tags search or replace command that you did.
2025: For instance, to skip the rest of the current file, you can type
2026: @w{@kbd{M-> M-x tags-loop-continue}}.
2027: 
2028:   Note that the commands described above carry out much broader
2029: searches than the @code{xref-find-definitions} family.  The
2030: @code{xref-find-definitions} commands search only for definitions of
2031: identifiers that match your string or regexp.  The commands
2032: @code{xref-find-references}, @code{tags-search}, and
2033: @code{tags-query-replace} find every occurrence of the identifier or
2034: regexp, as ordinary search commands and replace commands do in the
2035: current buffer.
2036: 
2037:   As an alternative to @code{xref-find-references} and
2038: @code{tags-search}, you can run @command{grep} as a subprocess and
2039: have Emacs show you the matching lines one by one.  @xref{Grep
2040: Searching}.
2041: 
2042: @node List Identifiers
2043: @subsubsection Identifier Inquiries
2044: 
2045: @table @kbd
2046: @item C-M-i
2047: @itemx M-@key{TAB}
2048: Perform completion on the text around point, possibly using the
2049: selected tags table if one is loaded (@code{completion-at-point}).
2050: 
2051: @item M-x xref-find-apropos @key{RET} @var{regexp} @key{RET}
2052: Display a list of all known identifiers matching @var{regexp}.
2053: 
2054: @item M-x list-tags @key{RET} @var{file} @key{RET}
2055: Display a list of the identifiers defined in the program file
2056: @var{file}.
2057: 
2058: @item M-x next-file
2059: Visit files recorded in the selected tags table.
2060: @end table
2061: 
2062:   In most programming language modes, you can type @kbd{C-M-i} or
2063: @kbd{M-@key{TAB}} (@code{completion-at-point}) to complete the symbol
2064: at point.  Some modes provide specialized completion for this command
2065: tailored to the mode; for those that don't, if there is a tags table
2066: loaded, this command can use it to generate completion candidates.
2067: @xref{Symbol Completion}.
2068: 
2069: @findex list-tags
2070:   @kbd{M-x list-tags} reads the name of one of the files covered by
2071: the selected tags table, and displays a list of tags defined in that
2072: file.  Do not include a directory as part of the file name unless the
2073: file name recorded in the tags table includes a directory.  This
2074: command works only with the etags backend, and requires a tags table
2075: for the project to be available.  @xref{Tags Tables}.
2076: 
2077: @c Sadly, the new-and-improved Xref feature doesn't provide anything
2078: @c close to the described below features of the now-obsoleted
2079: @c tags-apropos.  I'm leaving this here to encourage enhancements to
2080: @c xref.el.
2081: @ignore
2082: @findex tags-apropos
2083: @vindex tags-apropos-verbose
2084: @vindex tags-tag-face
2085: @vindex tags-apropos-additional-actions
2086:   @kbd{M-x tags-apropos} is like @code{apropos} for tags
2087: (@pxref{Apropos}).  It displays a list of tags in the selected tags
2088: table whose entries match @var{regexp}.  If the variable
2089: @code{tags-apropos-verbose} is non-@code{nil}, it displays the names
2090: of the tags files together with the tag names.  You can customize the
2091: appearance of the output by setting the variable @code{tags-tag-face}
2092: to a face.  You can display additional output by customizing the
2093: variable @code{tags-apropos-additional-actions}; see its documentation
2094: for details.
2095: @end ignore
2096: 
2097: @findex next-file
2098:   @kbd{M-x next-file} visits files covered by the selected tags table.
2099: The first time it is called, it visits the first file covered by the
2100: table.  Each subsequent call visits the next covered file, unless a
2101: prefix argument is supplied, in which case it returns to the first
2102: file.  This command requires a tags table to be selected.
2103: 
2104: @node Tags Tables
2105: @subsection Tags Tables
2106: @cindex tags and tag tables
2107: 
2108:   A @dfn{tags table} records the tags@footnote{
2109: A @dfn{tag} is a synonym for identifier reference.  Commands and
2110: features based on the @code{etags} package traditionally use ``tag''
2111: with this meaning, and this subsection follows that tradition.
2112: } extracted by scanning the source code of a certain program or a
2113: certain document.  Tags extracted from generated files reference the
2114: original files, rather than the generated files that were scanned
2115: during tag extraction.  Examples of generated files include C files
2116: generated from Cweb source files, from a Yacc parser, or from Lex
2117: scanner definitions; @file{.i} preprocessed C files; and Fortran files
2118: produced by preprocessing @file{.fpp} source files.
2119: 
2120: @cindex etags
2121:   To produce a tags table, you run the @command{etags} shell command
2122: on a document or the source code file.  The @samp{etags} program
2123: writes the tags to a @dfn{tags table file}, or @dfn{tags file} in
2124: short.  The conventional name for a tags file is @file{TAGS}@.
2125: @xref{Create Tags Table}.  (It is also possible to create a tags table
2126: by using one of the commands from other packages that can produce such
2127: tables in the same format.)
2128: 
2129:   Emacs uses the tags tables via the @code{etags} package as one of
2130: the supported backends for @code{xref}.  Because tags tables are
2131: produced by the @command{etags} command that is part of an Emacs
2132: distribution, we describe tags tables in more detail here.
2133: 
2134: @cindex C++ class browser, tags
2135: @cindex tags, C++
2136: @cindex class browser, C++
2137: @cindex Ebrowse
2138:   The Ebrowse facility is similar to @command{etags} but specifically
2139: tailored for C++.  @xref{Top,, Ebrowse, ebrowse, Ebrowse User's
2140: Manual}.  The Semantic package provides another way to generate and
2141: use tags, separate from the @command{etags} facility.
2142: @xref{Semantic}.
2143: 
2144: @menu
2145: * Tag Syntax::          Tag syntax for various types of code and text files.
2146: * Create Tags Table::   Creating a tags table with @command{etags}.
2147: * Etags Regexps::       Create arbitrary tags using regular expressions.
2148: @end menu
2149: 
2150: @node Tag Syntax
2151: @subsubsection Source File Tag Syntax
2152: 
2153:   Here is how tag syntax is defined for the most popular languages:
2154: 
2155: @itemize @bullet
2156: @item
2157: In C code, any C function or typedef is a tag, and so are definitions of
2158: @code{struct}, @code{union} and @code{enum}.
2159: @code{#define} macro definitions, @code{#undef} and @code{enum}
2160: constants are also
2161: tags, unless you specify @samp{--no-defines} when making the tags table.
2162: Similarly, global variables are tags, unless you specify
2163: @samp{--no-globals}, and so are struct members, unless you specify
2164: @samp{--no-members}.  Use of @samp{--no-globals}, @samp{--no-defines}
2165: and @samp{--no-members} can make the tags table file much smaller.
2166: 
2167: You can tag function declarations and external variables in addition
2168: to function definitions by giving the @samp{--declarations} option to
2169: @command{etags}.
2170: 
2171: @item
2172: In C++ code, in addition to all the tag constructs of C code, member
2173: functions are also recognized; member variables are also recognized,
2174: unless you use the @samp{--no-members} option.  @code{operator}
2175: definitions have tag names like @samp{operator+}.  If you specify the
2176: @samp{--class-qualify} option, tags for variables and functions in
2177: classes are named @samp{@var{class}::@var{variable}} and
2178: @samp{@var{class}::@var{function}}.  By default, class methods and
2179: members are not class-qualified, which allows to identify their names in
2180: the sources more accurately.
2181: 
2182: @item
2183: In Java code, tags include all the constructs recognized in C++, plus
2184: the @code{interface}, @code{extends} and @code{implements} constructs.
2185: Tags for variables and functions in classes are named
2186: @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
2187: 
2188: @item
2189: In @LaTeX{} documents, the arguments for @code{\chapter},
2190: @code{\section}, @code{\subsection}, @code{\subsubsection},
2191: @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite},
2192: @code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry},
2193: @code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},
2194: @code{\newenvironment} and @code{\renewenvironment} are tags.
2195: 
2196: Other commands can make tags as well, if you specify them in the
2197: environment variable @env{TEXTAGS} before invoking @command{etags}.  The
2198: value of this environment variable should be a colon-separated list of
2199: command names.  For example,
2200: 
2201: @example
2202: TEXTAGS="mycommand:myothercommand"
2203: export TEXTAGS
2204: @end example
2205: 
2206: @noindent
2207: specifies (using Bourne shell syntax) that the commands
2208: @samp{\mycommand} and @samp{\myothercommand} also define tags.
2209: 
2210: @item
2211: In Lisp code, any function defined with @code{defun}, any variable
2212: defined with @code{defvar} or @code{defconst}, and in general the
2213: first argument of any expression that starts with @samp{(def} in
2214: column zero is a tag.  As an exception, expressions of the form
2215: @code{(defvar @var{foo})} are treated as declarations, and are only
2216: tagged if the @samp{--declarations} option is given.
2217: 
2218: @item
2219: In Scheme code, tags include anything defined with @code{def} or with a
2220: construct whose name starts with @samp{def}.  They also include variables
2221: set with @code{set!} at top level in the file.
2222: @end itemize
2223: 
2224:   Several other languages are also supported:
2225: 
2226: @itemize @bullet
2227: 
2228: @item
2229: In Ada code, functions, procedures, packages, tasks and types are
2230: tags.  Use the @samp{--packages-only} option to create tags for
2231: packages only.
2232: 
2233: In Ada, the same name can be used for different kinds of entity
2234: (e.g., for a procedure and for a function).  Also, for things like
2235: packages, procedures and functions, there is the spec (i.e., the
2236: interface) and the body (i.e., the implementation).  To make it
2237: easier to pick the definition you want, Ada tag names have suffixes
2238: indicating the type of entity:
2239: 
2240: @table @samp
2241: @item /b
2242: package body.
2243: @item /f
2244: function.
2245: @item /k
2246: task.
2247: @item /p
2248: procedure.
2249: @item /s
2250: package spec.
2251: @item /t
2252: type.
2253: @end table
2254: 
2255:   Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
2256: directly to the body of the package @code{bidule}, while @kbd{M-x
2257: find-tag @key{RET} bidule @key{RET}} will just search for any tag
2258: @code{bidule}.
2259: 
2260: @item
2261: In assembler code, labels appearing at the start of a line,
2262: followed by a colon, are tags.
2263: 
2264: @item
2265: In Bison or Yacc input files, each rule defines as a tag the nonterminal
2266: it constructs.  The portions of the file that contain C code are parsed
2267: as C code.
2268: 
2269: @item
2270: In Cobol code, tags are paragraph names; that is, any word starting in
2271: column 8 and followed by a period.
2272: 
2273: @item
2274: In Erlang code, the tags are the functions, records and macros defined
2275: in the file.
2276: 
2277: @item
2278: In Fortran code, functions, subroutines and block data are tags.
2279: 
2280: @item
2281: In Go code, packages, functions, and types are tags.
2282: 
2283: @item
2284: In HTML input files, the tags are the @code{title} and the @code{h1},
2285: @code{h2}, @code{h3} headers.  Also, tags are @code{name=} in anchors
2286: and all occurrences of @code{id=}.
2287: 
2288: @item
2289: In Lua input files, all functions are tags.
2290: 
2291: @item
2292: In makefiles, targets are tags; additionally, variables are tags
2293: unless you specify @samp{--no-globals}.
2294: 
2295: @item
2296: In Objective C code, tags include Objective C definitions for classes,
2297: class categories, methods and protocols.  Tags for variables and
2298: functions in classes are named @samp{@var{class}::@var{variable}} and
2299: @samp{@var{class}::@var{function}}.
2300: 
2301: @item
2302: In Pascal code, the tags are the functions and procedures defined in
2303: the file.
2304: 
2305: @item
2306: In Perl code, the tags are the packages, subroutines and variables
2307: defined by the @code{package}, @code{sub}, @code{use constant},
2308: @code{my}, and @code{local} keywords.  Use @samp{--globals} if you
2309: want to tag global variables.  Tags for subroutines are named
2310: @samp{@var{package}::@var{sub}}.  The name for subroutines defined in
2311: the default package is @samp{main::@var{sub}}.
2312: 
2313: @item
2314: In PHP code, tags are functions, classes and defines.  Vars are tags
2315: too, unless you use the @samp{--no-members} option.
2316: 
2317: @item
2318: In PostScript code, the tags are the functions.
2319: 
2320: @item
2321: In Prolog code, tags are predicates and rules at the beginning of
2322: line.
2323: 
2324: @item
2325: In Python code, @code{def} or @code{class} at the beginning of a line
2326: generate a tag.
2327: 
2328: @item
2329: In Ruby code, @code{def} or @code{class} or @code{module} at the
2330: beginning of a line generate a tag.  Constants also generate tags.
2331: @end itemize
2332: 
2333:   You can also generate tags based on regexp matching (@pxref{Etags
2334: Regexps}) to handle other formats and languages.
2335: 
2336: @node Create Tags Table
2337: @subsubsection Creating Tags Tables
2338: @cindex @command{etags} program
2339: 
2340:   The @command{etags} program is used to create a tags table file.  It knows
2341: the syntax of several languages, as described in
2342: @iftex
2343: the previous section.
2344: @end iftex
2345: @ifnottex
2346: @ref{Tag Syntax}.
2347: @end ifnottex
2348: Here is how to run @command{etags}:
2349: 
2350: @example
2351: etags @var{inputfiles}@dots{}
2352: @end example
2353: 
2354: @noindent
2355: The @command{etags} program reads the specified files, and writes a tags
2356: table named @file{TAGS} in the current working directory.  You can
2357: optionally specify a different file name for the tags table by using the
2358: @samp{--output=@var{file}} option; specifying @file{-} as a file name
2359: prints the tags table to standard output.  You can also append the
2360: newly created tags table to an existing file by using the @samp{--append}
2361: option.
2362: 
2363:   If the specified files don't exist, @command{etags} looks for
2364: compressed versions of them and uncompresses them to read them.  Under
2365: MS-DOS, @command{etags} also looks for file names like @file{mycode.cgz}
2366: if it is given @samp{mycode.c} on the command line and @file{mycode.c}
2367: does not exist.
2368: 
2369:   If the tags table becomes outdated due to changes in the files
2370: described in it, you can update it by running the @command{etags}
2371: program again.  If the tags table does not record a tag, or records it
2372: for the wrong file, then Emacs will not be able to find that
2373: definition until you update the tags table.  But if the position
2374: recorded in the tags table becomes a little bit wrong (due to other
2375: editing), Emacs will still be able to find the right position, with a
2376: slight delay.
2377: 
2378:    Thus, there is no need to update the tags table after each edit.
2379: You should update a tags table when you define new tags that you want
2380: to have listed, or when you move tag definitions from one file to
2381: another, or when changes become substantial.
2382: 
2383:   You can make a tags table @dfn{include} another tags table, by
2384: passing the @samp{--include=@var{file}} option to @command{etags}.  It
2385: then covers all the files covered by the included tags file, as well
2386: as its own.
2387: 
2388:   If you specify the source files with relative file names when you run
2389: @command{etags}, the tags file will contain file names relative to the
2390: directory where the tags file was initially written.  This way, you can
2391: move an entire directory tree containing both the tags file and the
2392: source files, and the tags file will still refer correctly to the source
2393: files.  If the tags file is @file{-} or is in the @file{/dev} directory,
2394: however, the file names are
2395: made relative to the current working directory.  This is useful, for
2396: example, when writing the tags to the standard output.
2397: 
2398:   When using a relative file name, it should not be a symbolic link
2399: pointing to a tags file in a different directory, because this would
2400: generally render the file names invalid.
2401: 
2402:   If you specify absolute file names as arguments to @command{etags}, then
2403: the tags file will contain absolute file names.  This way, the tags file
2404: will still refer to the same files even if you move it, as long as the
2405: source files remain in the same place.  Absolute file names start with
2406: @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
2407: 
2408:    When you want to make a tags table from a great number of files,
2409: you may have problems listing them on the command line, because some
2410: systems have a limit on its length.  You can circumvent this limit by
2411: telling @command{etags} to read the file names from its standard
2412: input, by typing a dash in place of the file names, like this:
2413: 
2414: @smallexample
2415: find . -name "*.[chCH]" -print | etags -
2416: @end smallexample
2417: 
2418:   @command{etags} recognizes the language used in an input file based on
2419: its file name and contents.  It first tries to match the file's name and
2420: extension to the ones commonly used with certain languages.  Some
2421: languages have interpreters with known names (e.g., @command{perl} for
2422: Perl or @command{pl} for Prolog), so @command{etags} next looks for an
2423: interpreter specification of the form @samp{#!@var{interp}} on the first
2424: line of an input file, and matches that against known interpreters.  If
2425: none of that works, or if you want to override the automatic detection of
2426: the language, you can specify the language explicitly with the
2427: @samp{--language=@var{name}} option.  You can intermix these options with
2428: file names; each one applies to the file names that follow it.  Specify
2429: @samp{--language=auto} to tell @command{etags} to resume guessing the
2430: language from the file names and file contents.  Specify
2431: @samp{--language=none} to turn off language-specific processing entirely;
2432: then @command{etags} recognizes tags by regexp matching alone
2433: (@pxref{Etags Regexps}).  This comes in handy when an input file uses a
2434: language not yet supported by @command{etags}, and you want to avoid
2435: having @command{etags} fall back on Fortran and C as the default
2436: languages.
2437: 
2438:   The option @samp{--parse-stdin=@var{file}} is mostly useful when
2439: calling @command{etags} from programs.  It can be used (only once) in
2440: place of a file name on the command line.  @command{etags} will read from
2441: standard input and mark the produced tags as belonging to the file
2442: @var{file}.
2443: 
2444:   @samp{etags --help} outputs the list of the languages @command{etags}
2445: knows, and the file name rules for guessing the language.  It also prints
2446: a list of all the available @command{etags} options, together with a short
2447: explanation.  If followed by one or more @samp{--language=@var{lang}}
2448: options, it outputs detailed information about how tags are generated for
2449: @var{lang}.
2450: 
2451: @node Etags Regexps
2452: @subsubsection Etags Regexps
2453: 
2454:   The @samp{--regex} option to @command{etags} allows tags to be
2455: recognized by regular expression matching.  You can intermix this
2456: option with file names; each one applies to the source files that
2457: follow it.  If you specify multiple @samp{--regex} options, all of
2458: them are used in parallel.  The syntax is:
2459: 
2460: @smallexample
2461: --regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}
2462: @end smallexample
2463: 
2464: @noindent
2465: The essential part of the option value is @var{tagregexp}, the regexp
2466: for matching tags.  It is always used anchored, that is, it only
2467: matches at the beginning of a line.  If you want to allow indented
2468: tags, use a regexp that matches initial whitespace; start it with
2469: @samp{[ \t]*}.
2470: 
2471:   In these regular expressions, @samp{\} quotes the next character,
2472: and all the C character escape sequences are supported: @samp{\a} for
2473: bell, @samp{\b} for back space, @samp{\e} for escape, @samp{\f} for
2474: formfeed, @samp{\n} for newline, @samp{\r} for carriage return,
2475: @samp{\t} for tab, and @samp{\v} for vertical tab.  In addition,
2476: @samp{\d} stands for the @code{DEL} character.
2477: 
2478:   Ideally, @var{tagregexp} should not match more characters than are
2479: needed to recognize what you want to tag.  If the syntax requires you
2480: to write @var{tagregexp} so it matches more characters beyond the tag
2481: itself, you should add a @var{nameregexp}, to pick out just the tag.
2482: This will enable Emacs to find tags more accurately and to do
2483: completion on tag names more reliably.  In @var{nameregexp}, it is
2484: frequently convenient to use ``back references'' (@pxref{Regexp
2485: Backslash}) to parenthesized groupings @w{@samp{\( @dots{} \)}} in
2486: @var{tagregexp}.  For example, @samp{\1} refers to the first such
2487: parenthesized grouping.  You can find some examples of this below.
2488: 
2489:   The @var{modifiers} are a sequence of zero or more characters that
2490: modify the way @command{etags} does the matching.  A regexp with no
2491: modifiers is applied sequentially to each line of the input file, in a
2492: case-sensitive way.  The modifiers and their meanings are:
2493: 
2494: @table @samp
2495: @item i
2496: Ignore case when matching this regexp.
2497: @item m
2498: Match this regular expression against the whole file, so that
2499: multi-line matches are possible.
2500: @item s
2501: Match this regular expression against the whole file, and allow
2502: @samp{.} in @var{tagregexp} to match newlines.
2503: @end table
2504: 
2505:   The @samp{-R} option cancels all the regexps defined by preceding
2506: @samp{--regex} options.  It too applies to the file names following
2507: it.  Here's an example:
2508: 
2509: @smallexample
2510: etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
2511:     bar.ber -R --lang=lisp los.er
2512: @end smallexample
2513: 
2514: @noindent
2515: Here @command{etags} chooses the parsing language for @file{voo.doo} and
2516: @file{bar.ber} according to their contents.  @command{etags} also uses
2517: @var{reg1} to recognize additional tags in @file{voo.doo}, and both
2518: @var{reg1} and @var{reg2} to recognize additional tags in
2519: @file{bar.ber}.  @var{reg1} is checked against each line of
2520: @file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while
2521: @var{reg2} is checked against the whole @file{bar.ber} file,
2522: permitting multi-line matches, in a case-sensitive way.  @command{etags}
2523: uses only the Lisp tags rules, with no user-specified regexp matching,
2524: to recognize tags in @file{los.er}.
2525: 
2526:   You can restrict a @samp{--regex} option to match only files of a
2527: given language by using the optional prefix @var{@{language@}}.
2528: (@samp{etags --help} prints the list of languages recognized by
2529: @command{etags}.)  This is particularly useful when storing many
2530: predefined regular expressions for @command{etags} in a file.  The
2531: following example tags the @code{DEFVAR} macros in the Emacs source
2532: files, for the C language only:
2533: 
2534: @smallexample
2535: --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/'
2536: @end smallexample
2537: 
2538: @noindent
2539: When you have complex regular expressions, you can store the list of
2540: them in a file.  The following option syntax instructs @command{etags} to
2541: read two files of regular expressions.  The regular expressions
2542: contained in the second file are matched without regard to case.
2543: 
2544: @smallexample
2545: --regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file}
2546: @end smallexample
2547: 
2548: @noindent
2549: A regex file for @command{etags} contains one regular expression per
2550: line.  Empty lines, and lines beginning with space or tab are ignored.
2551: When the first character in a line is @samp{@@}, @command{etags} assumes
2552: that the rest of the line is the name of another file of regular
2553: expressions; thus, one such file can include another file.  All the
2554: other lines are taken to be regular expressions.  If the first
2555: non-whitespace text on the line is @samp{--}, that line is a comment.
2556: 
2557:   For example, we can create a file called @samp{emacs.tags} with the
2558: following contents:
2559: 
2560: @smallexample
2561:         -- This is for GNU Emacs C source files
2562: @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
2563: @end smallexample
2564: 
2565: @noindent
2566: and then use it like this:
2567: 
2568: @smallexample
2569: etags --regex=@@emacs.tags *.[ch] */*.[ch]
2570: @end smallexample
2571: 
2572:   Here are some more examples.  The regexps are quoted to protect them
2573: from shell interpretation.
2574: 
2575: @itemize @bullet
2576: 
2577: @item
2578: Tag Octave files:
2579: 
2580: @smallexample
2581: etags --language=none \
2582:       --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
2583:       --regex='/###key \(.*\)/\1/' \
2584:       --regex='/[ \t]*global[ \t].*/' \
2585:       *.m
2586: @end smallexample
2587: 
2588: @noindent
2589: Note that tags are not generated for scripts, so that you have to add
2590: a line by yourself of the form @samp{###key @var{scriptname}} if you
2591: want to jump to it.
2592: 
2593: @item
2594: Tag Tcl files:
2595: 
2596: @smallexample
2597: etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
2598: @end smallexample
2599: 
2600: @item
2601: Tag VHDL files:
2602: 
2603: @smallexample
2604: etags --language=none \
2605:   --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
2606:   --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
2607:   \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
2608: @end smallexample
2609: @end itemize
2610: 
2611: @node Select Tags Table
2612: @subsection Selecting a Tags Table
2613: 
2614: @findex visit-tags-table
2615:   Emacs has at any time at most one @dfn{selected} tags table.  All the
2616: commands for working with tags tables use the selected one.  To select
2617: a tags table, type @kbd{M-x visit-tags-table}, which reads the tags
2618: table file name as an argument, with @file{TAGS} in the default
2619: directory as the default.
2620: 
2621: @vindex tags-file-name
2622:   Emacs does not actually read in the tags table contents until you
2623: try to use them; all @code{visit-tags-table} does is store the file
2624: name in the variable @code{tags-file-name}, and not much more.  The
2625: variable's initial value is @code{nil}; that value tells all the
2626: commands for working with tags tables that they must ask for a tags
2627: table file name to use.
2628: 
2629:   Using @code{visit-tags-table} when a tags table is already loaded
2630: gives you a choice: you can add the new tags table to the current list
2631: of tags tables, or start a new list.  The tags commands use all the tags
2632: tables in the current list.  If you start a new list, the new tags table
2633: is used @emph{instead} of others.  If you add the new table to the
2634: current list, it is used @emph{as well as} the others.
2635: 
2636: @vindex tags-table-list
2637:   You can specify a precise list of tags tables by setting the variable
2638: @code{tags-table-list} to a list of strings, like this:
2639: 
2640: @c keep this on two lines for formatting in smallbook
2641: @example
2642: @group
2643: (setq tags-table-list
2644:       '("~/.emacs.d" "/usr/local/lib/emacs/src"))
2645: @end group
2646: @end example
2647: 
2648: @noindent
2649: This tells the tags commands to look at the @file{TAGS} files in your
2650: @file{~/.emacs.d} directory and in the @file{/usr/local/lib/emacs/src}
2651: directory.  The order depends on which file you are in and which tags
2652: table mentions that file.
2653: 
2654:   Do not set both @code{tags-file-name} and @code{tags-table-list}.
2655: 
2656: @node EDE
2657: @section Emacs Development Environment
2658: @cindex EDE (Emacs Development Environment)
2659: @cindex Emacs Development Environment
2660: @cindex Integrated development environment
2661: 
2662: EDE (@dfn{Emacs Development Environment}) is a package that simplifies
2663: the task of creating, building, and debugging large programs with
2664: Emacs.  It provides some of the features of an IDE, or @dfn{Integrated
2665: Development Environment}, in Emacs.
2666: 
2667: This section provides a brief description of EDE usage.
2668: @ifnottex
2669: For full details, see @ref{Top, EDE,, ede, Emacs Development Environment}.
2670: @end ifnottex
2671: @iftex
2672: For full details on Ede, type @kbd{C-h i} and then select the EDE
2673: manual.
2674: @end iftex
2675: 
2676:   EDE is implemented as a global minor mode (@pxref{Minor Modes}).  To
2677: enable it, type @kbd{M-x global-ede-mode} or click on the
2678: @samp{Project Support (EDE)} item in the @samp{Tools} menu.  You can
2679: also enable EDE each time you start Emacs, by adding the following
2680: line to your initialization file:
2681: 
2682: @smallexample
2683: (global-ede-mode t)
2684: @end smallexample
2685: 
2686: @noindent
2687: Activating EDE adds a menu named @samp{Development} to the menu bar.
2688: Many EDE commands, including the ones described below, can be invoked
2689: from this menu.
2690: 
2691:   EDE organizes files into @dfn{projects}, which correspond to
2692: directory trees.  The @dfn{project root} is the topmost directory of a
2693: project.  To define a new project, visit a file in the desired project
2694: root and type @kbd{M-x ede-new}.  This command prompts for a
2695: @dfn{project type}, which refers to the underlying method that EDE
2696: will use to manage the project (@pxref{Creating a project, EDE,, ede,
2697: Emacs Development Environment}).  The most common project types are
2698: @samp{Make}, which uses Makefiles, and @samp{Automake}, which uses GNU
2699: Automake (@pxref{Top, Automake,, automake, Automake}).  In both cases,
2700: EDE also creates a file named @file{Project.ede}, which stores
2701: information about the project.
2702: 
2703:   A project may contain one or more @dfn{targets}.  A target can be an
2704: object file, executable program, or some other type of file, which is
2705: built from one or more of the files in the project.
2706: 
2707:   To add a new @dfn{target} to a project, type @kbd{C-c . t}
2708: (@code{M-x ede-new-target}).  This command also asks if you wish to
2709: add the current file to that target, which means that the target
2710: is to be built from that file.  After you have defined a target, you
2711: can add more files to it by typing @kbd{C-c . a}
2712: (@code{ede-add-file}).
2713: 
2714:   To build a target, type @kbd{C-c . c} (@code{ede-compile-target}).
2715: To build all the targets in the project, type @kbd{C-c . C}
2716: (@code{ede-compile-project}).  EDE uses the file types to guess how
2717: the target should be built.
2718: 
2719: @ifnottex
2720: @include emerge-xtra.texi
2721: @end ifnottex
2722: