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-2018 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}).  Note that @kbd{C-x v u} cannot be reversed
1088: with the usual undo commands (@pxref{Undo}), so use it with care.
1089: 
1090:   On locking-based version control systems, @kbd{C-x v u} leaves files
1091: unlocked; you must lock again to resume editing.  You can also use
1092: @kbd{C-x v u} to unlock a file if you lock it and then decide not to
1093: change it.
1094: 
1095: @node VC Ignore
1096: @subsection Ignore Version Control Files
1097: 
1098: @table @kbd
1099: @item C-x v G
1100: Ignore a file under current version control system.  (@code{vc-ignore}).
1101: @end table
1102: 
1103: @kindex C-x v G
1104: @findex vc-ignore
1105:   Many source trees contain some files that do not need to be
1106: versioned, such as editor backups, object or bytecode files, and built
1107: programs.  You can simply not add them, but then they'll always crop
1108: up as unknown files.  You can also tell the version control system to
1109: ignore these files by adding them to the ignore file at the top of the
1110: tree.  @kbd{C-x v G} (@code{vc-ignore}) can help you do this.  When
1111: called with a prefix argument, you can remove a file from the ignored
1112: file list.
1113: 
1114: @node VC Directory Mode
1115: @subsection VC Directory Mode
1116: 
1117: @cindex VC Directory buffer
1118:   The @dfn{VC Directory buffer} is a specialized buffer for viewing
1119: the version control statuses of the files in a directory tree, and
1120: performing version control operations on those files.  In particular,
1121: it is used to specify multi-file VC filesets for commands like
1122: @w{@kbd{C-x v v}} to act on (@pxref{VC Directory Commands}).
1123: 
1124: @kindex C-x v d
1125: @findex vc-dir
1126:   To use the VC Directory buffer, type @kbd{C-x v d} (@code{vc-dir}).
1127: This reads a directory's name using the minibuffer, and switches to a VC
1128: Directory buffer for that directory.  By default, the buffer is named
1129: @file{*vc-dir*}.  Its contents are described
1130: @iftex
1131: below.
1132: @end iftex
1133: @ifnottex
1134: in @ref{VC Directory Buffer}.
1135: @end ifnottex
1136: 
1137:   The @code{vc-dir} command automatically detects the version control
1138: system to be used in the specified directory.  In the event that more
1139: than one system is being used in the directory, you should invoke the
1140: command with a prefix argument, @kbd{C-u C-x v d}; this prompts for
1141: the version control system which the VC Directory buffer should use.
1142: 
1143: @ifnottex
1144: @cindex PCL-CVS
1145: @pindex cvs
1146: @cindex CVS directory mode
1147:   In addition to the VC Directory buffer, Emacs has a similar facility
1148: called PCL-CVS which is specialized for CVS@.  @xref{Top, , About
1149: PCL-CVS, pcl-cvs, PCL-CVS---The Emacs Front-End to CVS}.
1150: @end ifnottex
1151: 
1152: @menu
1153: * Buffer: VC Directory Buffer.      What the buffer looks like and means.
1154: * Commands: VC Directory Commands.  Commands to use in a VC directory buffer.
1155: @end menu
1156: 
1157: @node VC Directory Buffer
1158: @subsubsection The VC Directory Buffer
1159: 
1160:   The VC Directory buffer contains a list of version-controlled files
1161: and their version control statuses.  It lists files in the current
1162: directory (the one specified when you called @kbd{C-x v d}) and its
1163: subdirectories, but only those with a noteworthy status.  Files
1164: that are up-to-date (i.e., the same as in the repository) are
1165: omitted.  If all the files in a subdirectory are up-to-date, the
1166: subdirectory is not listed either.  As an exception, if a file has
1167: become up-to-date as a direct result of a VC command, it is listed.
1168: 
1169:   Here is an example of a VC Directory buffer listing:
1170: 
1171: @smallexample
1172: @group
1173:                      ./
1174:     edited           configure.ac
1175: *   added            README
1176:     unregistered     temp.txt
1177:                      src/
1178: *   edited           src/main.c
1179: @end group
1180: @end smallexample
1181: 
1182: @noindent
1183: Two work files have been modified but not committed:
1184: @file{configure.ac} in the current directory, and @file{main.c} in the
1185: @file{src/} subdirectory.  The file named @file{README} has been added
1186: but is not yet committed, while @file{temp.txt} is not under version
1187: control (@pxref{Registering}).
1188: 
1189: The @samp{*} characters next to the entries for @file{README} and
1190: @file{src/main.c} indicate that the user has marked these files as
1191: the current VC fileset
1192: @iftex
1193: (see below).
1194: @end iftex
1195: @ifnottex
1196: (@pxref{VC Directory Commands}).
1197: @end ifnottex
1198: 
1199:   The above example is typical for a decentralized version control
1200: system like Bazaar, Git, or Mercurial.  Other systems can show other
1201: statuses.  For instance, CVS shows the @samp{needs-update} status if
1202: the repository has changes that have not been applied to the work
1203: file.  RCS and SCCS show the name of the user locking a file as its
1204: status.
1205: 
1206: @ifnottex
1207:   On CVS, the @code{vc-dir} command normally contacts the repository,
1208: which may be on a remote machine, to check for updates.  If you change
1209: the variable @code{vc-cvs-stay-local} to @code{nil} (@pxref{CVS
1210: Options}), then Emacs avoids contacting a remote repository when
1211: generating the VC Directory buffer (it will still contact it when
1212: necessary, e.g., when doing a commit).  This may be desirable if you
1213: are working offline or the network is slow.
1214: @end ifnottex
1215: 
1216: @vindex vc-directory-exclusion-list
1217:   The VC Directory buffer omits subdirectories listed in the variable
1218: @code{vc-directory-exclusion-list}.  Its default value contains
1219: directories that are used internally by version control systems.
1220: 
1221: @node VC Directory Commands
1222: @subsubsection VC Directory Commands
1223: 
1224:   Emacs provides several commands for navigating the VC Directory
1225: buffer, and for marking files as belonging to the current VC
1226: fileset.
1227: 
1228: @table @kbd
1229: @item n
1230: @itemx @key{SPC}
1231: Move point to the next entry (@code{vc-dir-next-line}).
1232: 
1233: @item p
1234: Move point to the previous entry (@code{vc-dir-previous-line}).
1235: 
1236: @item @key{TAB}
1237: Move to the next directory entry (@code{vc-dir-next-directory}).
1238: 
1239: @item S-@key{TAB}
1240: Move to the previous directory entry
1241: (@code{vc-dir-previous-directory}).
1242: 
1243: @item @key{RET}
1244: @itemx f
1245: Visit the file or directory listed on the current line
1246: (@code{vc-dir-find-file}).
1247: 
1248: @item o
1249: Visit the file or directory on the current line, in a separate window
1250: (@code{vc-dir-find-file-other-window}).
1251: 
1252: @item m
1253: Mark the file or directory on the current line (@code{vc-dir-mark}),
1254: putting it in the current VC fileset.  If the region is active, mark
1255: all files in the region.
1256: 
1257: A file cannot be marked with this command if it is already in a marked
1258: directory, or one of its subdirectories.  Similarly, a directory
1259: cannot be marked with this command if any file in its tree is marked.
1260: 
1261: @item M
1262: If point is on a file entry, mark all files with the same status; if
1263: point is on a directory entry, mark all files in that directory tree
1264: (@code{vc-dir-mark-all-files}).  With a prefix argument, mark all
1265: listed files and directories.
1266: 
1267: @item q
1268: Quit the VC Directory buffer, and bury it (@code{quit-window}).
1269: 
1270: @item u
1271: Unmark the file or directory on the current line.  If the region is
1272: active, unmark all the files in the region (@code{vc-dir-unmark}).
1273: 
1274: @item U
1275: If point is on a file entry, unmark all files with the same status; if
1276: point is on a directory entry, unmark all files in that directory tree
1277: (@code{vc-dir-unmark-all-files}).  With a prefix argument, unmark all
1278: files and directories.
1279: 
1280: @item x
1281: Hide files with @samp{up-to-date} or @samp{ignored} status
1282: (@code{vc-dir-hide-up-to-date}).  With a prefix argument, hide items
1283: whose state is that of the item at point.
1284: @end table
1285: 
1286: @findex vc-dir-mark
1287: @findex vc-dir-mark-all-files
1288:   While in the VC Directory buffer, all the files that you mark with
1289: @kbd{m} (@code{vc-dir-mark}) or @kbd{M} (@code{vc-dir-mark-all-files})
1290: are in the current VC fileset.  If you mark a directory entry with
1291: @kbd{m}, all the listed files in that directory tree are in the
1292: current VC fileset.  The files and directories that belong to the
1293: current VC fileset are indicated with a @samp{*} character in the VC
1294: Directory buffer, next to their VC status.  In this way, you can set
1295: up a multi-file VC fileset to be acted on by VC commands like
1296: @w{@kbd{C-x v v}} (@pxref{Basic VC Editing}), @w{@kbd{C-x v =}}
1297: (@pxref{Old Revisions}), and @w{@kbd{C-x v u}} (@pxref{VC Undo}).
1298: 
1299:   The VC Directory buffer also defines some single-key shortcuts for
1300: VC commands with the @kbd{C-x v} prefix: @kbd{=}, @kbd{+}, @kbd{l},
1301: @kbd{i}, @kbd{D}, @kbd{L}, @kbd{G}, @kbd{I}, @kbd{O}, and @kbd{v}.
1302: 
1303:   For example, you can commit a set of edited files by opening a VC
1304: Directory buffer, where the files are listed with the @samp{edited}
1305: status; marking the files; and typing @kbd{v} or @kbd{C-x v v}
1306: (@code{vc-next-action}).  If the version control system is
1307: changeset-based, Emacs will commit the files in a single revision.
1308: 
1309:   While in the VC Directory buffer, you can also perform search and
1310: replace on the current VC fileset, with the following commands:
1311: 
1312: @table @kbd
1313: @item S
1314: Search the fileset (@code{vc-dir-search}).
1315: 
1316: @item Q
1317: Do a regular expression query replace on the fileset
1318: (@code{vc-dir-query-replace-regexp}).
1319: 
1320: @item M-s a C-s
1321: Do an incremental search on the fileset (@code{vc-dir-isearch}).
1322: 
1323: @item M-s a C-M-s
1324: Do an incremental regular expression search on the fileset
1325: (@code{vc-dir-isearch-regexp}).
1326: @end table
1327: 
1328: @noindent
1329: Apart from acting on multiple files, these commands behave much like
1330: their single-buffer counterparts (@pxref{Search}).
1331: 
1332:   The VC Directory buffer additionally defines some branch-related
1333: commands starting with the prefix @kbd{B}:
1334: 
1335: @table @kbd
1336: @item B c
1337: Create a new branch (@code{vc-create-tag}).
1338: 
1339: @item B l
1340: Prompt for the name of a branch and display the change history of that
1341: branch (@code{vc-print-branch-log}).
1342: 
1343: @item B s
1344: Switch to a branch (@code{vc-retrieve-tag}).  @xref{Switching Branches}.
1345: @end table
1346: 
1347: @cindex stashes in version control
1348: @cindex shelves in version control
1349:   The above commands are also available via the menu bar, and via a
1350: context menu invoked by @kbd{mouse-2}.  Furthermore, some VC backends
1351: use the menu to provide extra backend-specific commands.  For example,
1352: Git and Bazaar allow you to manipulate @dfn{stashes} and @dfn{shelves}
1353: (which are a way to temporarily put aside uncommitted changes, and
1354: bring them back at a later time).
1355: 
1356: @node Branches
1357: @subsection Version Control Branches
1358: @cindex branch (version control)
1359: 
1360:   One use of version control is to support multiple independent lines
1361: of development, which are called @dfn{branches}.  Amongst other
1362: things, branches can be used for maintaining separate stable and
1363: development versions of a program, and for developing unrelated
1364: features in isolation from one another.
1365: 
1366:   VC's support for branch operations is currently fairly limited.  For
1367: decentralized version control systems, it provides commands for
1368: @dfn{updating} one branch with the contents of another, and for
1369: @dfn{merging} the changes made to two different branches
1370: (@pxref{Merging}).  For centralized version control systems, it
1371: supports checking out different branches and committing into new or
1372: different branches.
1373: 
1374: @menu
1375: * Switching Branches::    How to get to another existing branch.
1376: * Pulling / Pushing::     Receiving/sending changes from/to elsewhere.
1377: * Merging::               Transferring changes between branches.
1378: * Creating Branches::     How to start a new branch.
1379: @end menu
1380: 
1381: @node Switching Branches
1382: @subsubsection Switching between Branches
1383: 
1384:   The various version control systems differ in how branches are
1385: implemented, and these differences cannot be entirely concealed by VC.
1386: 
1387:   On some decentralized version control systems, including Bazaar and
1388: Mercurial in its normal mode of operation, each branch has its own
1389: working directory tree, so switching between branches just involves
1390: switching directories.  On Git, branches are normally @dfn{co-located}
1391: in the same directory, and switching between branches is done using
1392: the @command{git checkout} command, which changes the contents of the
1393: working tree to match the branch you switch to.  Bazaar also supports
1394: co-located branches, in which case the @command{bzr switch} command
1395: will switch branches in the current directory.  With Subversion, you
1396: switch to another branch using the @command{svn switch} command.
1397: 
1398:   The VC command to switch to another branch in the current directory
1399: is @kbd{C-x v r @var{branch-name} @key{RET}} (@code{vc-retrieve-tag}).
1400: 
1401:   On centralized version control systems, you can also switch between
1402: branches by typing @kbd{C-u C-x v v} in an up-to-date work file
1403: (@pxref{Advanced C-x v v}), and entering the revision ID for a
1404: revision on another branch.  On CVS, for instance, revisions on the
1405: @dfn{trunk} (the main line of development) normally have IDs of the
1406: form 1.1, 1.2, 1.3, @dots{}, while the first branch created from (say)
1407: revision 1.2 has revision IDs 1.2.1.1, 1.2.1.2, @dots{}, the second
1408: branch created from revision 1.2 has revision IDs 1.2.2.1, 1.2.2.2,
1409: @dots{}, and so forth.  You can also specify the @dfn{branch ID},
1410: which is a branch revision ID omitting its final component
1411: (e.g., 1.2.1), to switch to the latest revision on that branch.
1412: 
1413:   On a locking-based system, switching to a different branch also
1414: unlocks (write-protects) the working tree.
1415: 
1416:   Once you have switched to a branch, VC commands will apply to that
1417: branch until you switch away; for instance, any VC filesets that you
1418: commit will be committed to that specific branch.
1419: 
1420: @node Pulling / Pushing
1421: @subsubsection Pulling/Pushing Changes into/from a Branch
1422: 
1423: @table @kbd
1424: @item C-x v P
1425: On a decentralized version control system, update another location
1426: with changes from the current branch (a.k.a. ``push'' changes).  This
1427: concept does not exist for centralized version control systems
1428: 
1429: @item C-x v +
1430: On a decentralized version control system, update the current branch
1431: by ``pulling in'' changes from another location.
1432: 
1433: On a centralized version control system, update the current VC
1434: fileset.
1435: @end table
1436: 
1437: @kindex C-x v P
1438: @findex vc-push
1439: On a decentralized version control system, the command @kbd{C-x v P}
1440: (@code{vc-push}) updates another location with changes from the
1441: current branch.  With a prefix argument, it prompts for the exact
1442: version control command to run, which lets you specify where to push
1443: changes; the default is @command{bzr push} with Bazaar, @command{git
1444: push} with Git, and @command{hg push} with Mercurial.  The default
1445: commands always push to a default location determined by the version
1446: control system from your branch configuration.
1447: 
1448: Prior to pushing, you can use @kbd{C-x v O} (@code{vc-log-outgoing})
1449: to view a log buffer of the changes to be sent.  @xref{VC Change Log}.
1450: 
1451: @cindex bound branch (Bazaar VCS)
1452: This command is currently supported only by Bazaar, Git, and Mercurial.
1453: The concept of ``pushing'' does not exist for centralized version
1454: control systems, where this operation is a part of committing a
1455: changeset, so invoking this command on a centralized VCS signals an
1456: error.  This command also signals an error when attempted in a Bazaar
1457: @dfn{bound branch}, where committing a changeset automatically pushes
1458: the changes to the remote repository to which the local branch is
1459: bound.
1460: 
1461: @kindex C-x v +
1462: @findex vc-pull
1463:   On a decentralized version control system, the command @kbd{C-x v +}
1464: (@code{vc-pull}) updates the current branch and working tree.  It is
1465: typically used to update a copy of a remote branch.  If you supply a
1466: prefix argument, the command prompts for the exact version control
1467: command to use, which lets you specify where to pull changes from.
1468: Otherwise, it pulls from a default location determined by the version
1469: control system.
1470: 
1471:   Amongst decentralized version control systems, @kbd{C-x v +} is
1472: currently supported only by Bazaar, Git, and Mercurial.  With Bazaar,
1473: it calls @command{bzr pull} for ordinary branches (to pull from a
1474: master branch into a mirroring branch), and @command{bzr update} for a
1475: bound branch (to pull from a central repository).  With Git, it calls
1476: @command{git pull} to fetch changes from a remote repository and merge
1477: it into the current branch.  With Mercurial, it calls @command{hg pull
1478: -u} to fetch changesets from the default remote repository and update
1479: the working directory.
1480: 
1481:   Prior to pulling, you can use @kbd{C-x v I} (@code{vc-log-incoming})
1482: to view a log buffer of the changes to be applied.  @xref{VC Change
1483: Log}.
1484: 
1485:   On a centralized version control system like CVS, @kbd{C-x v +}
1486: updates the current VC fileset from the repository.
1487: 
1488: @node Merging
1489: @subsubsection Merging Branches
1490: @cindex merging changes
1491: 
1492: @table @kbd
1493: @item C-x v m
1494: On a decentralized version control system, merge changes from another
1495: branch into the current one.
1496: 
1497: On a centralized version control system, merge changes from another
1498: branch into the current VC fileset.
1499: @end table
1500: 
1501:   While developing a branch, you may sometimes need to @dfn{merge} in
1502: changes that have already been made in another branch.  This is not a
1503: trivial operation, as overlapping changes may have been made to the
1504: two branches.
1505: 
1506:   On a decentralized version control system, merging is done with the
1507: command @kbd{C-x v m} (@code{vc-merge}).  On Bazaar, this prompts for
1508: the exact arguments to pass to @command{bzr merge}, offering a
1509: sensible default if possible.  On Git, this prompts for the name of a
1510: branch to merge from, with completion (based on the branch names known
1511: to the current repository).  The output from running the merge command
1512: is shown in a separate buffer.
1513: 
1514:   On a centralized version control system like CVS, @kbd{C-x v m}
1515: prompts for a branch ID, or a pair of revision IDs (@pxref{Switching
1516: Branches}); then it finds the changes from that branch, or the changes
1517: between the two revisions you specified, and merges those changes into
1518: the current VC fileset.  If you just type @kbd{@key{RET}}, Emacs simply
1519: merges any changes that were made on the same branch since you checked
1520: the file out.
1521: 
1522: @cindex conflicts
1523: @cindex resolving conflicts
1524:   Immediately after performing a merge, only the working tree is
1525: modified, and you can review the changes produced by the merge with
1526: @kbd{C-x v D} and related commands (@pxref{Old Revisions}).  If the
1527: two branches contained overlapping changes, merging produces a
1528: @dfn{conflict}; a warning appears in the output of the merge command,
1529: and @dfn{conflict markers} are inserted into each affected work file,
1530: surrounding the two sets of conflicting changes.  You must then
1531: resolve the conflict by editing the conflicted files.  Once you are
1532: done, the modified files must be committed in the usual way for the
1533: merge to take effect (@pxref{Basic VC Editing}).
1534: 
1535: @node Creating Branches
1536: @subsubsection Creating New Branches
1537: 
1538:   On centralized version control systems like CVS, Emacs supports
1539: creating new branches as part of a commit operation.  When committing
1540: a modified VC fileset, type @kbd{C-u C-x v v} (@code{vc-next-action}
1541: with a prefix argument; @pxref{Advanced C-x v v}).  Then Emacs prompts
1542: for a revision ID for the new revision.  You should specify a suitable
1543: branch ID for a branch starting at the current revision.  For example,
1544: if the current revision is 2.5, the branch ID should be 2.5.1, 2.5.2,
1545: and so on, depending on the number of existing branches at that point.
1546: 
1547:   To create a new branch at an older revision (one that is no longer
1548: the head of a branch), first select that revision (@pxref{Switching
1549: Branches}).  Your procedure will then differ depending on whether you
1550: are using a locking or merging-based VCS.
1551: 
1552:   On a locking VCS, you will need to lock the old revision branch with
1553: @kbd{C-x v v}.  You'll be asked to confirm, when you lock the old
1554: revision, that you really mean to create a new branch---if you say no,
1555: you'll be offered a chance to lock the latest revision instead.  On a
1556: merging-based VCS you will skip this step.
1557: 
1558:   Then make your changes and type @kbd{C-x v v} again to commit a new
1559: revision.  This creates a new branch starting from the selected
1560: revision.
1561: 
1562:   After the branch is created, subsequent commits create new revisions
1563: on that branch.  To leave the branch, you must explicitly select a
1564: different revision with @kbd{C-u C-x v v}.
1565: 
1566: @ifnottex
1567: @include vc1-xtra.texi
1568: @end ifnottex
1569: 
1570: @node Change Log
1571: @section Change Logs
1572: 
1573: @cindex change log
1574:   Many software projects keep a @dfn{change log}.  This is a file,
1575: normally named @file{ChangeLog}, containing a chronological record of
1576: when and how the program was changed.  Sometimes, these files are
1577: automatically generated from the change log entries stored in version
1578: control systems, or are used to generate these change log entries.
1579: Sometimes, there are several change log files, each recording the
1580: changes in one directory or directory tree.
1581: 
1582: @menu
1583: * Change Log Commands:: Commands for editing change log files.
1584: * Format of ChangeLog:: What the change log file looks like.
1585: @end menu
1586: 
1587: @node Change Log Commands
1588: @subsection Change Log Commands
1589: 
1590: @kindex C-x 4 a
1591: @findex add-change-log-entry-other-window
1592:   The Emacs command @kbd{C-x 4 a} adds a new entry to the change log
1593: file for the file you are editing
1594: (@code{add-change-log-entry-other-window}).  If that file is actually
1595: a backup file, it makes an entry appropriate for the file's
1596: parent---that is useful for making log entries for functions that
1597: have been deleted in the current version.
1598: 
1599:   @kbd{C-x 4 a} visits the change log file and creates a new entry
1600: unless the most recent entry is for today's date and your name.  It
1601: also creates a new item for the current file.  For many languages, it
1602: can even guess the name of the function or other object that was
1603: changed.
1604: 
1605: @c Not worth it.
1606: @c @vindex change-log-directory-files
1607: To find the change log file, Emacs searches up the directory tree from
1608: the file you are editing.  By default, it stops if it finds a
1609: directory that seems to be the root of a version-control repository.
1610: To change this, customize @code{change-log-directory-files}.
1611: 
1612: @vindex add-log-keep-changes-together
1613:   When the variable @code{add-log-keep-changes-together} is
1614: non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file,
1615: rather than starting a new item.
1616: 
1617: You can combine multiple changes of the same nature.  If you don't
1618: enter any text after the initial @kbd{C-x 4 a}, any subsequent
1619: @kbd{C-x 4 a} adds another symbol to the change log entry.
1620: 
1621: @vindex add-log-always-start-new-record
1622:   If @code{add-log-always-start-new-record} is non-@code{nil},
1623: @kbd{C-x 4 a} always makes a new entry, even if the last entry
1624: was made by you and on the same date.
1625: 
1626: @vindex change-log-version-info-enabled
1627: @vindex change-log-version-number-regexp-list
1628: @cindex file version in change log entries
1629:   If the value of the variable @code{change-log-version-info-enabled}
1630: is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the
1631: change log entry.  It finds the version number by searching the first
1632: ten percent of the file, using regular expressions from the variable
1633: @code{change-log-version-number-regexp-list}.
1634: 
1635: @cindex Change Log mode
1636: @findex change-log-mode
1637:   The change log file is visited in Change Log mode.  In this major
1638: mode, each bunch of grouped items counts as one paragraph, and each
1639: entry is considered a page.  This facilitates editing the entries.
1640: @kbd{C-j} and auto-fill indent each new line like the previous line;
1641: this is convenient for entering the contents of an entry.
1642: 
1643: @findex change-log-goto-source
1644:   You can use the command @code{change-log-goto-source} (by default
1645: bound to @kbd{C-c C-c}) to go to the source location of the change log
1646: entry near point, when Change Log mode is on.  Then subsequent
1647: invocations of the @code{next-error} command (by default bound to
1648: @kbd{M-g M-n} and @kbd{C-x `}) will move between entries in the change
1649: log.  You will jump to the actual site in the file that was changed,
1650: not just to the next change log entry.  You can also use
1651: @code{previous-error} to move back through the change log entries.
1652: 
1653: @findex change-log-merge
1654:   You can use the command @kbd{M-x change-log-merge} to merge other
1655: log files into a buffer in Change Log Mode, preserving the date
1656: ordering of entries.
1657: 
1658: @vindex add-log-dont-create-changelog-file
1659:   Version control systems are another way to keep track of changes in
1660: your program and keep a change log.  Many projects that use a VCS don't
1661: keep a separate versioned change log file nowadays, so you may wish to
1662: avoid having such a file in the repository.  If the value of
1663: @code{add-log-dont-create-changelog-file} is non-@code{nil}, commands
1664: like @kbd{C-x 4 a} (@code{add-change-log-entry-other-window}) will
1665: record changes in a suitably named temporary buffer instead of a file,
1666: if such a file does not already exist.
1667: 
1668: Whether you have a change log file or use a temporary buffer for
1669: change logs, you can type @kbd{C-c C-a}
1670: (@code{log-edit-insert-changelog}) in the VC Log buffer to insert the
1671: relevant change log entries, if they exist.  @xref{Log Buffer}.
1672: 
1673: @node Format of ChangeLog
1674: @subsection Format of ChangeLog
1675: 
1676:   A change log entry starts with a header line that contains the
1677: current date, your name (taken from the variable
1678: @code{add-log-full-name}), and your email address (taken from the
1679: variable @code{add-log-mailing-address}).  Aside from these header
1680: lines, every line in the change log starts with a space or a tab.  The
1681: bulk of the entry consists of @dfn{items}, each of which starts with a
1682: line starting with whitespace and a star.  Here are two entries, both
1683: dated in May 1993, with two items and one item respectively.
1684: 
1685: @iftex
1686: @medbreak
1687: @end iftex
1688: @smallexample
1689: 1993-05-25  Richard Stallman  <rms@@gnu.org>
1690: 
1691:         * man.el: Rename symbols 'man-*' to 'Man-*'.
1692:         (manual-entry): Make prompt string clearer.
1693: 
1694:         * simple.el (blink-matching-paren-distance):
1695:         Change default to 12,000.
1696: 
1697: 1993-05-24  Richard Stallman  <rms@@gnu.org>
1698: 
1699:         * vc.el (minor-mode-map-alist): Don't use it if it's void.
1700:         (vc-cancel-version): Doc fix.
1701: @end smallexample
1702: 
1703:   One entry can describe several changes; each change should have its
1704: own item, or its own line in an item.  Normally there should be a
1705: blank line between items.  When items are related (parts of the same
1706: change, in different places), group them by leaving no blank line
1707: between them.
1708: 
1709:   You should put a copyright notice and permission notice at the
1710: end of the change log file.  Here is an example:
1711: 
1712: @smallexample
1713: Copyright 1997, 1998 Free Software Foundation, Inc.
1714: Copying and distribution of this file, with or without modification, are
1715: permitted provided the copyright notice and this notice are preserved.
1716: @end smallexample
1717: 
1718: @noindent
1719: Of course, you should substitute the proper years and copyright holder.
1720: 
1721: @node Xref
1722: @section Find Identifier References
1723: @cindex xref
1724: 
1725:   An @dfn{identifier} is a name of a syntactical subunit of the
1726: program: a function, a subroutine, a method, a class, a data type, a
1727: macro, etc.  In a programming language, each identifier is a symbol in
1728: the language's syntax.  Program development and maintenance requires
1729: capabilities to quickly find where each identifier was defined and
1730: referenced, to rename identifiers across the entire project, etc.
1731: 
1732: These capabilities are also useful for finding references in major
1733: modes other than those defined to support programming languages.  For
1734: example, chapters, sections, appendices, etc.@: of a text or a @TeX{}
1735: document can be treated as subunits as well, and their names can be
1736: used as identifiers.  In this chapter, we use the term ``identifiers''
1737: to collectively refer to the names of any kind of subunits, in program
1738: source and in other kinds of text alike.
1739: 
1740: Emacs provides a unified interface to these capabilities, called
1741: @samp{xref}.
1742: 
1743: @cindex xref backend
1744: To do its job, @code{xref} needs to make use of information and to
1745: employ methods specific to the major mode.  What files to search for
1746: identifiers, how to find references to identifiers, how to complete on
1747: identifiers---all this and more is mode-specific knowledge.
1748: @code{xref} delegates the mode-specific parts of its job to a
1749: @dfn{backend} provided by the mode; it also includes defaults for some
1750: of its commands, for those modes that don't provide their own.
1751: 
1752: A backend can implement its capabilities in a variety of ways.  Here
1753: are a few examples:
1754: 
1755: @enumerate a
1756: @item
1757: Some major modes provide built-in means for looking up the language
1758: symbols.  For example, Emacs Lisp symbols can be identified by
1759: searching the package load history, maintained by the Emacs Lisp
1760: interpreter, and by consulting the built-in documentation strings; the
1761: Emacs Lisp mode uses these facilities in its backend to allow finding
1762: definitions of symbols.  (One disadvantage of this kind of backend is
1763: that it only knows about subunits that were loaded into the
1764: interpreter.)
1765: 
1766: @item
1767: An external program can extract references by scanning the relevant
1768: files, and build a database of these references.  A backend can then
1769: access this database whenever it needs to list or look up references.
1770: The Emacs distribution includes @command{etags}, a command for tagging
1771: identifier definitions in programs, which supports many programming
1772: languages and other major modes, such as HTML, by extracting
1773: references into @dfn{tags tables}.  @xref{Create Tags Table}.  Major
1774: modes for languages supported by @command{etags} can use tags tables
1775: as basis for their backend.  (One disadvantage of this kind of backend
1776: is that tags tables need to be kept reasonably up to date, by
1777: rebuilding them from time to time.)
1778: @end enumerate
1779: 
1780: @menu
1781: * Find Identifiers::    Commands to find where an identifier is defined
1782:                           or referenced, to list identifiers, etc.
1783: * Tags Tables::         Tags table records which file defines a symbol.
1784: * Select Tags Table::   How to visit a specific tags table.
1785: @end menu
1786: 
1787: @node Find Identifiers
1788: @subsection Find Identifiers
1789: 
1790:   This subsection describes the commands that find references to
1791: identifiers and perform various queries about identifiers.  Each such
1792: reference could @emph{define} an identifier, e.g., provide the
1793: implementation of a program subunit or the text of a document section;
1794: or it could @emph{use} the identifier, e.g., call a function or a
1795: method, assign a value to a variable, mention a chapter in a
1796: cross-reference, etc.
1797: 
1798: @menu
1799: * Looking Up Identifiers:: Commands to find the definition of an identifier.
1800: * Xref Commands::          Commands in the @file{*xref*} buffer.
1801: * Identifier Search::      Searching and replacing identifiers.
1802: * List Identifiers::       Listing identifiers and completing on them.
1803: @end menu
1804: 
1805: @node Looking Up Identifiers
1806: @subsubsection Looking Up Identifiers
1807: @cindex find definition of symbols
1808: @cindex identifier, finding definition of
1809: @cindex find references to symbols
1810: 
1811:   The most important thing that @code{xref} enables you to do is to find
1812: the definition of a specific identifier.
1813: 
1814: @table @kbd
1815: @item M-.@:
1816: Find definitions of an identifier (@code{xref-find-definitions}).
1817: @item C-M-. @var{pattern} @key{RET}
1818: Find all identifiers whose name matches @var{pattern}
1819: (@code{xref-find-apropos}).
1820: @item C-x 4 .@: @key{RET}
1821: Find definitions of identifier, but display it in another window
1822: (@code{xref-find-definitions-other-window}).
1823: @item C-x 5 .@: @key{RET}
1824: Find definition of identifier, and display it in a new frame
1825: (@code{xref-find-definitions-other-frame}).
1826: @item M-x xref-find-definitions-at-mouse
1827: Find definition of identifier at mouse click.
1828: @item M-,
1829: Go back to where you previously invoked @kbd{M-.} and friends
1830: (@code{xref-pop-marker-stack}).
1831: @item M-x xref-etags-mode
1832: Switch @code{xref} to use the @code{etags} backend.
1833: @end table
1834: 
1835: @kindex M-.
1836: @findex xref-find-definitions
1837: @vindex xref-prompt-for-identifier
1838:   @kbd{M-.}@: (@code{xref-find-definitions}) shows the definitions of
1839: the identifier at point.  With a prefix argument, or if there's no
1840: identifier at point, it prompts for the identifier.  (If you want it
1841: to always prompt, customize @code{xref-prompt-for-identifier} to
1842: @code{t}.)
1843: 
1844: If the specified identifier has only one definition, the command jumps
1845: to it.  If the identifier has more than one possible definition (e.g.,
1846: in an object-oriented language, or if there's a function and a
1847: variable by the same name), the command shows the candidate
1848: definitions in the @file{*xref*} buffer, together with the files in
1849: which these definitions are found.  Selecting one of these candidates
1850: by typing @kbd{@key{RET}} or clicking @kbd{mouse-2} will pop a buffer
1851: showing the corresponding definition.
1852: 
1853:   When entering the identifier argument to @kbd{M-.}, the usual
1854: minibuffer completion commands can be used (@pxref{Completion}), with
1855: the known identifier names as completion candidates.
1856: 
1857: @kindex C-x 4 .
1858: @findex xref-find-definitions-other-window
1859: @kindex C-x 5 .
1860: @findex xref-find-definitions-other-frame
1861:   Like most commands that can switch buffers,
1862: @code{xref-find-definitions} has a variant that displays the new
1863: buffer in another window, and one that makes a new frame for it.  The
1864: former is @w{@kbd{C-x 4 .}}
1865: (@code{xref-find-definitions-other-window}), and the latter is
1866: @w{@kbd{C-x 5 .}}  (@code{xref-find-definitions-other-frame}).
1867: 
1868:   The command @code{xref-find-definitions-at-mouse} works like
1869: @code{xref-find-definitions}, but it looks for the identifier name at
1870: or around the place of a mouse event.  This command is intended to be
1871: bound to a mouse event, such as @kbd{C-M-mouse-1}, for example.
1872: 
1873: @findex xref-find-apropos
1874: @kindex C-M-.
1875:   The command @kbd{C-M-.} (@code{xref-find-apropos}) finds the
1876: definitions of one or more identifiers that match a specified regular
1877: expression.  It is just like @kbd{M-.} except that it does regexp
1878: matching of identifiers instead of matching symbol names as fixed
1879: strings.
1880: 
1881:   When any of the above commands finds more than one definition, it
1882: presents the @file{*xref*} buffer showing the definition candidates.
1883: In that buffer, you have several specialized commands, described in
1884: @ref{Xref Commands}.
1885: 
1886: @kindex M-,
1887: @findex xref-pop-marker-stack
1888: @vindex xref-marker-ring-length
1889:   To go back to places @emph{from where} you found the definition,
1890: use @kbd{M-,} (@code{xref-pop-marker-stack}).  It jumps back to the
1891: point of the last invocation of @kbd{M-.}.  Thus you can find and
1892: examine the definition of something with @kbd{M-.} and then return to
1893: where you were with @kbd{M-,}.  @kbd{M-,} allows you to retrace your
1894: steps to a depth determined by the variable
1895: @code{xref-marker-ring-length}, which defaults to 16.
1896: 
1897: @findex xref-etags-mode
1898:   Some major modes install @code{xref} support facilities that might
1899: sometimes fail to find certain identifiers.  For example, in Emacs
1900: Lisp mode (@pxref{Lisp Eval}) @kbd{M-.} will by default find only
1901: functions and variables from Lisp packages which are loaded into the
1902: current Emacs session or are auto-loaded (@pxref{Autoload,,, elisp,
1903: The Emacs Lisp Reference Manual}).  If @kbd{M-.} fails to find some
1904: identifiers, you can try forcing @code{xref} to use the @code{etags}
1905: backend (@pxref{Xref}).  To this end, turn on the Xref Etags minor
1906: mode with @w{@kbd{M-x xref-etags-mode}}, then invoke @kbd{M-.} again.
1907: (For this to work, be sure to run @command{etags} to create the tags
1908: table in the directory tree of the source files, see @ref{Create Tags
1909: Table}.)
1910: 
1911: @node Xref Commands
1912: @subsubsection Commands Available in the @file{*xref*} Buffer
1913: @cindex commands in @file{*xref*} buffers
1914: @cindex XREF mode
1915: 
1916:   The following commands are provided in the @file{*xref*} buffer by
1917: the special XREF mode:
1918: 
1919: @table @kbd
1920: @item @key{RET}
1921: @itemx mouse-2
1922: Display the reference on the current line.
1923: 
1924: @item n
1925: @itemx .
1926: @findex xref-next-line
1927: Move to the next reference and display it in the other window
1928: (@code{xref-next-line}).
1929: 
1930: @item p
1931: @itemx ,
1932: @findex xref-prev-line
1933: Move to the previous reference and display it in the other window
1934: (@code{xref-prev-line}).
1935: 
1936: @item C-o
1937: @findex xref-show-location-at-point
1938: Display the reference on the current line in the other window
1939: (@code{xref-show-location-at-point}).
1940: 
1941: @item @key{TAB}
1942: @findex xref-quit-and-goto-xref
1943: Display the reference on the current line and bury the @file{*xref*}
1944: buffer (@code{xref-quit-and-goto-xref}).
1945: 
1946: @item r @var{pattern} @key{RET} @var{replacement} @key{RET}
1947: Perform interactive query-replace on references that match
1948: @var{pattern} (@code{xref-query-replace-in-results}), replacing
1949: the match with @var{replacement}.  @xref{Identifier Search}.
1950: 
1951: @findex xref-quit
1952: @item q
1953: Quit the window showing the @file{*xref*} buffer (@code{xref-quit}).
1954: @end table
1955: 
1956: In addition, the usual navigation commands, such as the arrow keys,
1957: @kbd{C-n}, and @kbd{C-p} are available for moving around the buffer
1958: without displaying the references.
1959: 
1960: @node Identifier Search
1961: @subsubsection Searching and Replacing with Identifiers
1962: @cindex search and replace in multiple source files
1963: @cindex multiple source file search and replace
1964: 
1965:   The commands in this section perform various search and replace
1966: operations either on identifiers themselves or on files that reference
1967: them.
1968: 
1969: @table @kbd
1970: @item M-?
1971: Find all the references for the identifier at point.
1972: 
1973: @item M-x xref-query-replace-in-results @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
1974: Interactively replace @var{regexp} with @var{replacement} in the names
1975: of all the identifiers shown in the @file{*xref*} buffer.
1976: 
1977: @item M-x tags-search @key{RET} @var{regexp} @key{RET}
1978: Search for @var{regexp} through the files in the selected tags
1979: table.
1980: 
1981: @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET}
1982: Perform a @code{query-replace-regexp} on each file in the selected tags table.
1983: 
1984: @item M-x multifile-continue
1985: Restart one of the last 2 commands above, from the current location of point.
1986: @end table
1987: 
1988: @kindex M-?
1989: @findex xref-find-references
1990:   @kbd{M-?} finds all the references for the identifier at point,
1991: prompting for the identifier as needed, with completion.  Depending on
1992: the current backend (@pxref{Xref}), the command may prompt even if it
1993: finds a valid identifier at point.  When invoked with a prefix
1994: argument, it always prompts for the identifier.  (If you want it to
1995: prompt always, customize the value of the variable
1996: @code{xref-prompt-for-identifier} to @code{t}; or set it to @code{nil}
1997: to prompt only if there's no usable identifier at point.)  The command
1998: then presents the @file{*xref*} buffer with all the references to the
1999: identifier, showing the file name and the line where the identifier is
2000: referenced.  The XREF mode commands are available in this buffer, see
2001: @ref{Xref Commands}.
2002: 
2003: @findex xref-query-replace-in-results
2004:   @kbd{M-x xref-query-replace-in-results} reads a regexp to match identifier
2005: names and a replacement string, just like ordinary @kbd{M-x
2006: query-replace-regexp}.  It then performs the specified replacement in
2007: the names of the matching identifiers in all the places in all the
2008: files where these identifiers are referenced.  This is useful when you
2009: rename your identifiers as part of refactoring.  This command should
2010: be invoked in the @file{*xref*} buffer generated by @kbd{M-?}.
2011: 
2012: @findex tags-search
2013:   @kbd{M-x tags-search} reads a regexp using the minibuffer, then
2014: searches for matches in all the files in the selected tags table, one
2015: file at a time.  It displays the name of the file being searched so
2016: you can follow its progress.  As soon as it finds an occurrence,
2017: @code{tags-search} returns.  This command requires tags tables to be
2018: available (@pxref{Tags Tables}).
2019: 
2020: @findex multifile-continue
2021:   Having found one match with @code{tags-search}, you probably want to
2022: find all the rest.  @kbd{M-x multifile-continue} resumes the
2023: @code{tags-search}, finding one more match.  This searches the rest of
2024: the current buffer, followed by the remaining files of the tags table.
2025: 
2026: @findex tags-query-replace
2027:   @kbd{M-x tags-query-replace} performs a single
2028: @code{query-replace-regexp} through all the files in the tags table.  It
2029: reads a regexp to search for and a string to replace with, just like
2030: ordinary @kbd{M-x query-replace-regexp}.  It searches much like @kbd{M-x
2031: tags-search}, but repeatedly, processing matches according to your
2032: input.  @xref{Query Replace}, for more information on query replace.
2033: 
2034: @vindex tags-case-fold-search
2035: @cindex case-sensitivity and tags search
2036:   You can control the case-sensitivity of tags search commands by
2037: customizing the value of the variable @code{tags-case-fold-search}.  The
2038: default is to use the same setting as the value of
2039: @code{case-fold-search} (@pxref{Lax Search}).
2040: 
2041:   It is possible to get through all the files in the tags table with a
2042: single invocation of @kbd{M-x tags-query-replace}.  But often it is
2043: useful to exit temporarily, which you can do with any input event that
2044: has no special query replace meaning.  You can resume the query
2045: replace subsequently by typing @kbd{M-x multifile-continue}; this
2046: command resumes the last tags search or replace command that you did.
2047: For instance, to skip the rest of the current file, you can type
2048: @w{@kbd{M-> M-x multifile-continue}}.
2049: 
2050:   Note that the commands described above carry out much broader
2051: searches than the @code{xref-find-definitions} family.  The
2052: @code{xref-find-definitions} commands search only for definitions of
2053: identifiers that match your string or regexp.  The commands
2054: @code{xref-find-references}, @code{tags-search}, and
2055: @code{tags-query-replace} find every occurrence of the identifier or
2056: regexp, as ordinary search commands and replace commands do in the
2057: current buffer.
2058: 
2059:   As an alternative to @code{xref-find-references} and
2060: @code{tags-search}, you can run @command{grep} as a subprocess and
2061: have Emacs show you the matching lines one by one.  @xref{Grep
2062: Searching}.
2063: 
2064: @node List Identifiers
2065: @subsubsection Identifier Inquiries
2066: 
2067: @table @kbd
2068: @item C-M-i
2069: @itemx M-@key{TAB}
2070: Perform completion on the text around point, possibly using the
2071: selected tags table if one is loaded (@code{completion-at-point}).
2072: 
2073: @item M-x xref-find-apropos @key{RET} @var{regexp} @key{RET}
2074: Display a list of all known identifiers matching @var{regexp}.
2075: 
2076: @item M-x list-tags @key{RET} @var{file} @key{RET}
2077: Display a list of the identifiers defined in the program file
2078: @var{file}.
2079: 
2080: @item M-x tags-next-file
2081: Visit files recorded in the selected tags table.
2082: @end table
2083: 
2084:   In most programming language modes, you can type @kbd{C-M-i} or
2085: @kbd{M-@key{TAB}} (@code{completion-at-point}) to complete the symbol
2086: at point.  Some modes provide specialized completion for this command
2087: tailored to the mode; for those that don't, if there is a tags table
2088: loaded, this command can use it to generate completion candidates.
2089: @xref{Symbol Completion}.
2090: 
2091: @findex list-tags
2092:   @kbd{M-x list-tags} reads the name of one of the files covered by
2093: the selected tags table, and displays a list of tags defined in that
2094: file.  Do not include a directory as part of the file name unless the
2095: file name recorded in the tags table includes a directory.  This
2096: command works only with the etags backend, and requires a tags table
2097: for the project to be available.  @xref{Tags Tables}.
2098: 
2099: @c Sadly, the new-and-improved Xref feature doesn't provide anything
2100: @c close to the described below features of the now-obsoleted
2101: @c tags-apropos.  I'm leaving this here to encourage enhancements to
2102: @c xref.el.
2103: @ignore
2104: @findex tags-apropos
2105: @vindex tags-apropos-verbose
2106: @vindex tags-tag-face
2107: @vindex tags-apropos-additional-actions
2108:   @kbd{M-x tags-apropos} is like @code{apropos} for tags
2109: (@pxref{Apropos}).  It displays a list of tags in the selected tags
2110: table whose entries match @var{regexp}.  If the variable
2111: @code{tags-apropos-verbose} is non-@code{nil}, it displays the names
2112: of the tags files together with the tag names.  You can customize the
2113: appearance of the output by setting the variable @code{tags-tag-face}
2114: to a face.  You can display additional output by customizing the
2115: variable @code{tags-apropos-additional-actions}; see its documentation
2116: for details.
2117: @end ignore
2118: 
2119: @findex tags-next-file
2120:   @kbd{M-x tags-next-file} visits files covered by the selected tags table.
2121: The first time it is called, it visits the first file covered by the
2122: table.  Each subsequent call visits the next covered file, unless a
2123: prefix argument is supplied, in which case it returns to the first
2124: file.  This command requires a tags table to be selected.
2125: 
2126: @node Tags Tables
2127: @subsection Tags Tables
2128: @cindex tags and tag tables
2129: 
2130:   A @dfn{tags table} records the tags@footnote{
2131: A @dfn{tag} is a synonym for identifier reference.  Commands and
2132: features based on the @code{etags} package traditionally use ``tag''
2133: with this meaning, and this subsection follows that tradition.
2134: } extracted by scanning the source code of a certain program or a
2135: certain document.  Tags extracted from generated files reference the
2136: original files, rather than the generated files that were scanned
2137: during tag extraction.  Examples of generated files include C files
2138: generated from Cweb source files, from a Yacc parser, or from Lex
2139: scanner definitions; @file{.i} preprocessed C files; and Fortran files
2140: produced by preprocessing @file{.fpp} source files.
2141: 
2142: @cindex etags
2143:   To produce a tags table, you run the @command{etags} shell command
2144: on a document or the source code file.  The @samp{etags} program
2145: writes the tags to a @dfn{tags table file}, or @dfn{tags file} in
2146: short.  The conventional name for a tags file is @file{TAGS}@.
2147: @xref{Create Tags Table}.  (It is also possible to create a tags table
2148: by using one of the commands from other packages that can produce such
2149: tables in the same format.)
2150: 
2151:   Emacs uses the tags tables via the @code{etags} package as one of
2152: the supported backends for @code{xref}.  Because tags tables are
2153: produced by the @command{etags} command that is part of an Emacs
2154: distribution, we describe tags tables in more detail here.
2155: 
2156: @cindex C++ class browser, tags
2157: @cindex tags, C++
2158: @cindex class browser, C++
2159: @cindex Ebrowse
2160:   The Ebrowse facility is similar to @command{etags} but specifically
2161: tailored for C++.  @xref{Top,, Ebrowse, ebrowse, Ebrowse User's
2162: Manual}.  The Semantic package provides another way to generate and
2163: use tags, separate from the @command{etags} facility.
2164: @xref{Semantic}.
2165: 
2166: @menu
2167: * Tag Syntax::          Tag syntax for various types of code and text files.
2168: * Create Tags Table::   Creating a tags table with @command{etags}.
2169: * Etags Regexps::       Create arbitrary tags using regular expressions.
2170: @end menu
2171: 
2172: @node Tag Syntax
2173: @subsubsection Source File Tag Syntax
2174: 
2175:   Here is how tag syntax is defined for the most popular languages:
2176: 
2177: @itemize @bullet
2178: @item
2179: In C code, any C function or typedef is a tag, and so are definitions of
2180: @code{struct}, @code{union} and @code{enum}.
2181: @code{#define} macro definitions, @code{#undef} and @code{enum}
2182: constants are also
2183: tags, unless you specify @samp{--no-defines} when making the tags table.
2184: Similarly, global variables are tags, unless you specify
2185: @samp{--no-globals}, and so are struct members, unless you specify
2186: @samp{--no-members}.  Use of @samp{--no-globals}, @samp{--no-defines}
2187: and @samp{--no-members} can make the tags table file much smaller.
2188: 
2189: You can tag function declarations and external variables in addition
2190: to function definitions by giving the @samp{--declarations} option to
2191: @command{etags}.
2192: 
2193: @item
2194: In C++ code, in addition to all the tag constructs of C code, member
2195: functions are also recognized; member variables are also recognized,
2196: unless you use the @samp{--no-members} option.  @code{operator}
2197: definitions have tag names like @samp{operator+}.  If you specify the
2198: @samp{--class-qualify} option, tags for variables and functions in
2199: classes are named @samp{@var{class}::@var{variable}} and
2200: @samp{@var{class}::@var{function}}.  By default, class methods and
2201: members are not class-qualified, which allows to identify their names in
2202: the sources more accurately.
2203: 
2204: @item
2205: In Java code, tags include all the constructs recognized in C++, plus
2206: the @code{interface}, @code{extends} and @code{implements} constructs.
2207: Tags for variables and functions in classes are named
2208: @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}.
2209: 
2210: @item
2211: In @LaTeX{} documents, the arguments for @code{\chapter},
2212: @code{\section}, @code{\subsection}, @code{\subsubsection},
2213: @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite},
2214: @code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry},
2215: @code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand},
2216: @code{\newenvironment} and @code{\renewenvironment} are tags.
2217: 
2218: Other commands can make tags as well, if you specify them in the
2219: environment variable @env{TEXTAGS} before invoking @command{etags}.  The
2220: value of this environment variable should be a colon-separated list of
2221: command names.  For example,
2222: 
2223: @example
2224: TEXTAGS="mycommand:myothercommand"
2225: export TEXTAGS
2226: @end example
2227: 
2228: @noindent
2229: specifies (using Bourne shell syntax) that the commands
2230: @samp{\mycommand} and @samp{\myothercommand} also define tags.
2231: 
2232: @item
2233: In Lisp code, any function defined with @code{defun}, any variable
2234: defined with @code{defvar} or @code{defconst}, and in general the
2235: first argument of any expression that starts with @samp{(def} in
2236: column zero is a tag.  As an exception, expressions of the form
2237: @code{(defvar @var{foo})} are treated as declarations, and are only
2238: tagged if the @samp{--declarations} option is given.
2239: 
2240: @item
2241: In Scheme code, tags include anything defined with @code{def} or with a
2242: construct whose name starts with @samp{def}.  They also include variables
2243: set with @code{set!} at top level in the file.
2244: @end itemize
2245: 
2246:   Several other languages are also supported:
2247: 
2248: @itemize @bullet
2249: 
2250: @item
2251: In Ada code, functions, procedures, packages, tasks and types are
2252: tags.  Use the @samp{--packages-only} option to create tags for
2253: packages only.
2254: 
2255: In Ada, the same name can be used for different kinds of entity
2256: (e.g., for a procedure and for a function).  Also, for things like
2257: packages, procedures and functions, there is the spec (i.e., the
2258: interface) and the body (i.e., the implementation).  To make it
2259: easier to pick the definition you want, Ada tag names have suffixes
2260: indicating the type of entity:
2261: 
2262: @table @samp
2263: @item /b
2264: package body.
2265: @item /f
2266: function.
2267: @item /k
2268: task.
2269: @item /p
2270: procedure.
2271: @item /s
2272: package spec.
2273: @item /t
2274: type.
2275: @end table
2276: 
2277:   Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go
2278: directly to the body of the package @code{bidule}, while @kbd{M-x
2279: find-tag @key{RET} bidule @key{RET}} will just search for any tag
2280: @code{bidule}.
2281: 
2282: @item
2283: In assembler code, labels appearing at the start of a line,
2284: followed by a colon, are tags.
2285: 
2286: @item
2287: In Bison or Yacc input files, each rule defines as a tag the nonterminal
2288: it constructs.  The portions of the file that contain C code are parsed
2289: as C code.
2290: 
2291: @item
2292: In Cobol code, tags are paragraph names; that is, any word starting in
2293: column 8 and followed by a period.
2294: 
2295: @item
2296: In Erlang code, the tags are the functions, records and macros defined
2297: in the file.
2298: 
2299: @item
2300: In Fortran code, functions, subroutines and block data are tags.
2301: 
2302: @item
2303: In Go code, packages, functions, and types are tags.
2304: 
2305: @item
2306: In HTML input files, the tags are the @code{title} and the @code{h1},
2307: @code{h2}, @code{h3} headers.  Also, tags are @code{name=} in anchors
2308: and all occurrences of @code{id=}.
2309: 
2310: @item
2311: In Lua input files, all functions are tags.
2312: 
2313: @item
2314: In makefiles, targets are tags; additionally, variables are tags
2315: unless you specify @samp{--no-globals}.
2316: 
2317: @item
2318: In Objective C code, tags include Objective C definitions for classes,
2319: class categories, methods and protocols.  Tags for variables and
2320: functions in classes are named @samp{@var{class}::@var{variable}} and
2321: @samp{@var{class}::@var{function}}.
2322: 
2323: @item
2324: In Pascal code, the tags are the functions and procedures defined in
2325: the file.
2326: 
2327: @item
2328: In Perl code, the tags are the packages, subroutines and variables
2329: defined by the @code{package}, @code{sub}, @code{use constant},
2330: @code{my}, and @code{local} keywords.  Use @samp{--globals} if you
2331: want to tag global variables.  Tags for subroutines are named
2332: @samp{@var{package}::@var{sub}}.  The name for subroutines defined in
2333: the default package is @samp{main::@var{sub}}.
2334: 
2335: @item
2336: In PHP code, tags are functions, classes and defines.  Vars are tags
2337: too, unless you use the @samp{--no-members} option.
2338: 
2339: @item
2340: In PostScript code, the tags are the functions.
2341: 
2342: @item
2343: In Prolog code, tags are predicates and rules at the beginning of
2344: line.
2345: 
2346: @item
2347: In Python code, @code{def} or @code{class} at the beginning of a line
2348: generate a tag.
2349: 
2350: @item
2351: In Ruby code, @code{def} or @code{class} or @code{module} at the
2352: beginning of a line generate a tag.  Constants also generate tags.
2353: @end itemize
2354: 
2355:   You can also generate tags based on regexp matching (@pxref{Etags
2356: Regexps}) to handle other formats and languages.
2357: 
2358: @node Create Tags Table
2359: @subsubsection Creating Tags Tables
2360: @cindex @command{etags} program
2361: 
2362:   The @command{etags} program is used to create a tags table file.  It knows
2363: the syntax of several languages, as described in
2364: @iftex
2365: the previous section.
2366: @end iftex
2367: @ifnottex
2368: @ref{Tag Syntax}.
2369: @end ifnottex
2370: Here is how to run @command{etags}:
2371: 
2372: @example
2373: etags @var{inputfiles}@dots{}
2374: @end example
2375: 
2376: @noindent
2377: The @command{etags} program reads the specified files, and writes a tags
2378: table named @file{TAGS} in the current working directory.  You can
2379: optionally specify a different file name for the tags table by using the
2380: @samp{--output=@var{file}} option; specifying @file{-} as a file name
2381: prints the tags table to standard output.  You can also append the
2382: newly created tags table to an existing file by using the @samp{--append}
2383: option.
2384: 
2385:   If the specified files don't exist, @command{etags} looks for
2386: compressed versions of them and uncompresses them to read them.  Under
2387: MS-DOS, @command{etags} also looks for file names like @file{mycode.cgz}
2388: if it is given @samp{mycode.c} on the command line and @file{mycode.c}
2389: does not exist.
2390: 
2391:   If the tags table becomes outdated due to changes in the files
2392: described in it, you can update it by running the @command{etags}
2393: program again.  If the tags table does not record a tag, or records it
2394: for the wrong file, then Emacs will not be able to find that
2395: definition until you update the tags table.  But if the position
2396: recorded in the tags table becomes a little bit wrong (due to other
2397: editing), Emacs will still be able to find the right position, with a
2398: slight delay.
2399: 
2400:    Thus, there is no need to update the tags table after each edit.
2401: You should update a tags table when you define new tags that you want
2402: to have listed, or when you move tag definitions from one file to
2403: another, or when changes become substantial.
2404: 
2405:   You can make a tags table @dfn{include} another tags table, by
2406: passing the @samp{--include=@var{file}} option to @command{etags}.  It
2407: then covers all the files covered by the included tags file, as well
2408: as its own.
2409: 
2410:   If you specify the source files with relative file names when you run
2411: @command{etags}, the tags file will contain file names relative to the
2412: directory where the tags file was initially written.  This way, you can
2413: move an entire directory tree containing both the tags file and the
2414: source files, and the tags file will still refer correctly to the source
2415: files.  If the tags file is @file{-} or is in the @file{/dev} directory,
2416: however, the file names are
2417: made relative to the current working directory.  This is useful, for
2418: example, when writing the tags to the standard output.
2419: 
2420:   When using a relative file name, it should not be a symbolic link
2421: pointing to a tags file in a different directory, because this would
2422: generally render the file names invalid.
2423: 
2424:   If you specify absolute file names as arguments to @command{etags}, then
2425: the tags file will contain absolute file names.  This way, the tags file
2426: will still refer to the same files even if you move it, as long as the
2427: source files remain in the same place.  Absolute file names start with
2428: @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows.
2429: 
2430:    When you want to make a tags table from a great number of files,
2431: you may have problems listing them on the command line, because some
2432: systems have a limit on its length.  You can circumvent this limit by
2433: telling @command{etags} to read the file names from its standard
2434: input, by typing a dash in place of the file names, like this:
2435: 
2436: @smallexample
2437: find . -name "*.[chCH]" -print | etags -
2438: @end smallexample
2439: 
2440:   @command{etags} recognizes the language used in an input file based on
2441: its file name and contents.  It first tries to match the file's name and
2442: extension to the ones commonly used with certain languages.  Some
2443: languages have interpreters with known names (e.g., @command{perl} for
2444: Perl or @command{pl} for Prolog), so @command{etags} next looks for an
2445: interpreter specification of the form @samp{#!@var{interp}} on the first
2446: line of an input file, and matches that against known interpreters.  If
2447: none of that works, or if you want to override the automatic detection of
2448: the language, you can specify the language explicitly with the
2449: @samp{--language=@var{name}} option.  You can intermix these options with
2450: file names; each one applies to the file names that follow it.  Specify
2451: @samp{--language=auto} to tell @command{etags} to resume guessing the
2452: language from the file names and file contents.  Specify
2453: @samp{--language=none} to turn off language-specific processing entirely;
2454: then @command{etags} recognizes tags by regexp matching alone
2455: (@pxref{Etags Regexps}).  This comes in handy when an input file uses a
2456: language not yet supported by @command{etags}, and you want to avoid
2457: having @command{etags} fall back on Fortran and C as the default
2458: languages.
2459: 
2460:   The option @samp{--parse-stdin=@var{file}} is mostly useful when
2461: calling @command{etags} from programs.  It can be used (only once) in
2462: place of a file name on the command line.  @command{etags} will read from
2463: standard input and mark the produced tags as belonging to the file
2464: @var{file}.
2465: 
2466:   @samp{etags --help} outputs the list of the languages @command{etags}
2467: knows, and the file name rules for guessing the language.  It also prints
2468: a list of all the available @command{etags} options, together with a short
2469: explanation.  If followed by one or more @samp{--language=@var{lang}}
2470: options, it outputs detailed information about how tags are generated for
2471: @var{lang}.
2472: 
2473: @node Etags Regexps
2474: @subsubsection Etags Regexps
2475: 
2476:   The @samp{--regex} option to @command{etags} allows tags to be
2477: recognized by regular expression matching.  You can intermix this
2478: option with file names; each one applies to the source files that
2479: follow it.  If you specify multiple @samp{--regex} options, all of
2480: them are used in parallel.  The syntax is:
2481: 
2482: @smallexample
2483: --regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers}
2484: @end smallexample
2485: 
2486: @noindent
2487: The essential part of the option value is @var{tagregexp}, the regexp
2488: for matching tags.  It is always used anchored, that is, it only
2489: matches at the beginning of a line.  If you want to allow indented
2490: tags, use a regexp that matches initial whitespace; start it with
2491: @samp{[ \t]*}.
2492: 
2493:   In these regular expressions, @samp{\} quotes the next character,
2494: and all the C character escape sequences are supported: @samp{\a} for
2495: bell, @samp{\b} for back space, @samp{\e} for escape, @samp{\f} for
2496: formfeed, @samp{\n} for newline, @samp{\r} for carriage return,
2497: @samp{\t} for tab, and @samp{\v} for vertical tab.  In addition,
2498: @samp{\d} stands for the @code{DEL} character.
2499: 
2500:   Ideally, @var{tagregexp} should not match more characters than are
2501: needed to recognize what you want to tag.  If the syntax requires you
2502: to write @var{tagregexp} so it matches more characters beyond the tag
2503: itself, you should add a @var{nameregexp}, to pick out just the tag.
2504: This will enable Emacs to find tags more accurately and to do
2505: completion on tag names more reliably.  In @var{nameregexp}, it is
2506: frequently convenient to use ``back references'' (@pxref{Regexp
2507: Backslash}) to parenthesized groupings @w{@samp{\( @dots{} \)}} in
2508: @var{tagregexp}.  For example, @samp{\1} refers to the first such
2509: parenthesized grouping.  You can find some examples of this below.
2510: 
2511:   The @var{modifiers} are a sequence of zero or more characters that
2512: modify the way @command{etags} does the matching.  A regexp with no
2513: modifiers is applied sequentially to each line of the input file, in a
2514: case-sensitive way.  The modifiers and their meanings are:
2515: 
2516: @table @samp
2517: @item i
2518: Ignore case when matching this regexp.
2519: @item m
2520: Match this regular expression against the whole file, so that
2521: multi-line matches are possible.
2522: @item s
2523: Match this regular expression against the whole file, and allow
2524: @samp{.} in @var{tagregexp} to match newlines.
2525: @end table
2526: 
2527:   The @samp{-R} option cancels all the regexps defined by preceding
2528: @samp{--regex} options.  It too applies to the file names following
2529: it.  Here's an example:
2530: 
2531: @smallexample
2532: etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \
2533:     bar.ber -R --lang=lisp los.er
2534: @end smallexample
2535: 
2536: @noindent
2537: Here @command{etags} chooses the parsing language for @file{voo.doo} and
2538: @file{bar.ber} according to their contents.  @command{etags} also uses
2539: @var{reg1} to recognize additional tags in @file{voo.doo}, and both
2540: @var{reg1} and @var{reg2} to recognize additional tags in
2541: @file{bar.ber}.  @var{reg1} is checked against each line of
2542: @file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while
2543: @var{reg2} is checked against the whole @file{bar.ber} file,
2544: permitting multi-line matches, in a case-sensitive way.  @command{etags}
2545: uses only the Lisp tags rules, with no user-specified regexp matching,
2546: to recognize tags in @file{los.er}.
2547: 
2548:   You can restrict a @samp{--regex} option to match only files of a
2549: given language by using the optional prefix @var{@{language@}}.
2550: (@samp{etags --help} prints the list of languages recognized by
2551: @command{etags}.)  This is particularly useful when storing many
2552: predefined regular expressions for @command{etags} in a file.  The
2553: following example tags the @code{DEFVAR} macros in the Emacs source
2554: files, for the C language only:
2555: 
2556: @smallexample
2557: --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/'
2558: @end smallexample
2559: 
2560: @noindent
2561: When you have complex regular expressions, you can store the list of
2562: them in a file.  The following option syntax instructs @command{etags} to
2563: read two files of regular expressions.  The regular expressions
2564: contained in the second file are matched without regard to case.
2565: 
2566: @smallexample
2567: --regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file}
2568: @end smallexample
2569: 
2570: @noindent
2571: A regex file for @command{etags} contains one regular expression per
2572: line.  Empty lines, and lines beginning with space or tab are ignored.
2573: When the first character in a line is @samp{@@}, @command{etags} assumes
2574: that the rest of the line is the name of another file of regular
2575: expressions; thus, one such file can include another file.  All the
2576: other lines are taken to be regular expressions.  If the first
2577: non-whitespace text on the line is @samp{--}, that line is a comment.
2578: 
2579:   For example, we can create a file called @samp{emacs.tags} with the
2580: following contents:
2581: 
2582: @smallexample
2583:         -- This is for GNU Emacs C source files
2584: @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/
2585: @end smallexample
2586: 
2587: @noindent
2588: and then use it like this:
2589: 
2590: @smallexample
2591: etags --regex=@@emacs.tags *.[ch] */*.[ch]
2592: @end smallexample
2593: 
2594:   Here are some more examples.  The regexps are quoted to protect them
2595: from shell interpretation.
2596: 
2597: @itemize @bullet
2598: 
2599: @item
2600: Tag Octave files:
2601: 
2602: @smallexample
2603: etags --language=none \
2604:       --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
2605:       --regex='/###key \(.*\)/\1/' \
2606:       --regex='/[ \t]*global[ \t].*/' \
2607:       *.m
2608: @end smallexample
2609: 
2610: @noindent
2611: Note that tags are not generated for scripts, so that you have to add
2612: a line by yourself of the form @samp{###key @var{scriptname}} if you
2613: want to jump to it.
2614: 
2615: @item
2616: Tag Tcl files:
2617: 
2618: @smallexample
2619: etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
2620: @end smallexample
2621: 
2622: @item
2623: Tag VHDL files:
2624: 
2625: @smallexample
2626: etags --language=none \
2627:   --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
2628:   --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
2629:   \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'
2630: @end smallexample
2631: @end itemize
2632: 
2633: @node Select Tags Table
2634: @subsection Selecting a Tags Table
2635: 
2636: @findex visit-tags-table
2637:   Emacs has at any time at most one @dfn{selected} tags table.  All the
2638: commands for working with tags tables use the selected one.  To select
2639: a tags table, type @kbd{M-x visit-tags-table}, which reads the tags
2640: table file name as an argument, with @file{TAGS} in the default
2641: directory as the default.
2642: 
2643: @vindex tags-file-name
2644:   Emacs does not actually read in the tags table contents until you
2645: try to use them; all @code{visit-tags-table} does is store the file
2646: name in the variable @code{tags-file-name}, and not much more.  The
2647: variable's initial value is @code{nil}; that value tells all the
2648: commands for working with tags tables that they must ask for a tags
2649: table file name to use.
2650: 
2651:   Using @code{visit-tags-table} when a tags table is already loaded
2652: gives you a choice: you can add the new tags table to the current list
2653: of tags tables, or start a new list.  The tags commands use all the tags
2654: tables in the current list.  If you start a new list, the new tags table
2655: is used @emph{instead} of others.  If you add the new table to the
2656: current list, it is used @emph{as well as} the others.
2657: 
2658: @vindex tags-table-list
2659:   You can specify a precise list of tags tables by setting the variable
2660: @code{tags-table-list} to a list of strings, like this:
2661: 
2662: @c keep this on two lines for formatting in smallbook
2663: @example
2664: @group
2665: (setq tags-table-list
2666:       '("~/.emacs.d" "/usr/local/lib/emacs/src"))
2667: @end group
2668: @end example
2669: 
2670: @noindent
2671: This tells the tags commands to look at the @file{TAGS} files in your
2672: @file{~/.emacs.d} directory and in the @file{/usr/local/lib/emacs/src}
2673: directory.  The order depends on which file you are in and which tags
2674: table mentions that file.
2675: 
2676:   Do not set both @code{tags-file-name} and @code{tags-table-list}.
2677: 
2678: @node EDE
2679: @section Emacs Development Environment
2680: @cindex EDE (Emacs Development Environment)
2681: @cindex Emacs Development Environment
2682: @cindex Integrated development environment
2683: 
2684: EDE (@dfn{Emacs Development Environment}) is a package that simplifies
2685: the task of creating, building, and debugging large programs with
2686: Emacs.  It provides some of the features of an IDE, or @dfn{Integrated
2687: Development Environment}, in Emacs.
2688: 
2689: This section provides a brief description of EDE usage.
2690: @ifnottex
2691: For full details, see @ref{Top, EDE,, ede, Emacs Development Environment}.
2692: @end ifnottex
2693: @iftex
2694: For full details on Ede, type @kbd{C-h i} and then select the EDE
2695: manual.
2696: @end iftex
2697: 
2698:   EDE is implemented as a global minor mode (@pxref{Minor Modes}).  To
2699: enable it, type @kbd{M-x global-ede-mode} or click on the
2700: @samp{Project Support (EDE)} item in the @samp{Tools} menu.  You can
2701: also enable EDE each time you start Emacs, by adding the following
2702: line to your initialization file:
2703: 
2704: @smallexample
2705: (global-ede-mode t)
2706: @end smallexample
2707: 
2708: @noindent
2709: Activating EDE adds a menu named @samp{Development} to the menu bar.
2710: Many EDE commands, including the ones described below, can be invoked
2711: from this menu.
2712: 
2713:   EDE organizes files into @dfn{projects}, which correspond to
2714: directory trees.  The @dfn{project root} is the topmost directory of a
2715: project.  To define a new project, visit a file in the desired project
2716: root and type @kbd{M-x ede-new}.  This command prompts for a
2717: @dfn{project type}, which refers to the underlying method that EDE
2718: will use to manage the project (@pxref{Creating a project, EDE,, ede,
2719: Emacs Development Environment}).  The most common project types are
2720: @samp{Make}, which uses Makefiles, and @samp{Automake}, which uses GNU
2721: Automake (@pxref{Top, Automake,, automake, Automake}).  In both cases,
2722: EDE also creates a file named @file{Project.ede}, which stores
2723: information about the project.
2724: 
2725:   A project may contain one or more @dfn{targets}.  A target can be an
2726: object file, executable program, or some other type of file, which is
2727: built from one or more of the files in the project.
2728: 
2729:   To add a new @dfn{target} to a project, type @kbd{C-c . t}
2730: (@code{M-x ede-new-target}).  This command also asks if you wish to
2731: add the current file to that target, which means that the target
2732: is to be built from that file.  After you have defined a target, you
2733: can add more files to it by typing @kbd{C-c . a}
2734: (@code{ede-add-file}).
2735: 
2736:   To build a target, type @kbd{C-c . c} (@code{ede-compile-target}).
2737: To build all the targets in the project, type @kbd{C-c . C}
2738: (@code{ede-compile-project}).  EDE uses the file types to guess how
2739: the target should be built.
2740: 
2741: @ifnottex
2742: @include emerge-xtra.texi
2743: @end ifnottex
2744: