Next: Supported Version Control Systems, Up: Introduction to Version Control   [Contents][Index]

30.1.1.1 Understanding the Problems it Addresses ¶

Version control systems provide you with three important capabilities:

• Reversibility: the ability to back up to a previous state if you discover that some modification you did was a mistake or a bad idea.
• Concurrency: the ability to have many people modifying the same collection of files knowing that conflicting modifications can be detected and resolved.
• History: the ability to attach historical data to your data, such as explanatory comments about the intention behind each change. Even for a programmer working solo, change histories are an important aid to memory; for a multi-person project, they are a vitally important form of communication among developers.

Next: Concepts of Version Control, Previous: Understanding the Problems it Addresses, Up: Introduction to Version Control   [Contents][Index]

30.1.1.2 Supported Version Control Systems ¶

VC currently works with many different version control systems, which it refers to as backends:

• Git is a decentralized version control system originally invented by Linus Torvalds to support development of Linux (his kernel). VC supports all the common Git operations, but notably, Git rebases other than simply to edit a commit message must be done from the command line.
• CVS is the free version control system that was, until circa 2008, used by the majority of free software projects. Since then, it has been superseded by newer systems. CVS allows concurrent multi-user development either locally or over the network. Unlike newer systems, it lacks support for atomic commits and file moving/renaming. VC supports all basic editing operations under CVS.
• Subversion (svn) is a free version control system designed to be similar to CVS but without its problems (e.g., it supports atomic commits of filesets, and versioning of directories, symbolic links, meta-data, renames, copies, and deletes).
• SCCS was the first version control system ever built, and was long ago superseded by more advanced ones. VC compensates for certain features missing in SCCS (e.g., tag names for releases) by implementing them itself. Other VC features, such as multiple branches, are simply unavailable. Since SCCS is non-free, we recommend avoiding it.
• CSSC is a free replacement for SCCS. You should use CSSC only if, for some reason, you cannot use a more recent and better-designed version control system.
• RCS is the free version control system around which VC was initially built. It is relatively primitive: it cannot be used over the network, and works at the level of individual files. Almost everything you can do with RCS can be done through VC.
• Mercurial (hg) is a decentralized version control system broadly resembling Git. VC supports most Mercurial commands.
• Bazaar (bzr) is a decentralized version control system that supports both repository-based and decentralized versioning. VC supports most basic editing operations under Bazaar.
• SRC (src) is RCS, reloaded—a specialized version-control system designed for single-file projects worked on by only one person. It allows multiple files with independent version-control histories to exist in one directory, and is thus particularly well suited for maintaining small documents, scripts, and dotfiles. While it uses RCS for revision storage, it presents a modern user interface featuring lockless operation and integer sequential version numbers. VC supports almost all SRC operations.

Next: Merge-based vs Lock-based Version Control, Previous: Supported Version Control Systems, Up: Introduction to Version Control   [Contents][Index]

30.1.1.3 Concepts of Version Control ¶

When a file is under version control, we say that it is registered with the version control system. The system has a repository which stores both the file’s present state and its change history—enough to reconstruct the current version or any earlier version. The repository also contains other information, such as log entries that describe the changes made to each file.

The copy of a version-controlled file that you actually edit is called the work file. You can change each work file as you would an ordinary file. After you are done with a set of changes, you may commit (or check in) the changes; this records the changes in the repository, along with a descriptive log entry.

A directory tree of work files is called a working tree.

Each commit creates a new revision in the repository. The version control system keeps track of all past revisions and the changes that were made in each revision. Each revision is named by a revision ID, whose format depends on the version control system; in the simplest case, it is just an integer.

To go beyond these basic concepts, you will need to understand three aspects in which version control systems differ. As explained in the next three sections, they can be lock-based or merge-based; file-based or changeset-based; and centralized or decentralized. VC handles all these modes of operation, but it cannot hide the differences.

Next: Changeset-based vs File-based Version Control, Previous: Concepts of Version Control, Up: Introduction to Version Control   [Contents][Index]

30.1.1.4 Merge-based vs Lock-based Version Control ¶

A version control system typically has some mechanism to coordinate between users who want to change the same file. There are two ways to do this: merging and locking.

In a version control system that uses merging, each user may modify a work file at any time. The system lets you merge your work file, which may contain changes that have not been committed, with the latest changes that others have committed.

Older version control systems use a locking scheme instead. Here, work files are normally read-only. To edit a file, you ask the version control system to make it writable for you by locking it; only one user can lock a given file at any given time. This procedure is analogous to, but different from, the locking that Emacs uses to detect simultaneous editing of ordinary files (see Protection against Simultaneous Editing). When you commit your changes, that unlocks the file, and the work file becomes read-only again. Other users may then lock the file to make their own changes.

Both locking and merging systems can have problems when multiple users try to modify the same file at the same time. Locking systems have lock conflicts; a user may try to check a file out and be unable to because it is locked. In merging systems, merge conflicts happen when you commit a change to a file that conflicts with a change committed by someone else after your checkout. Both kinds of conflict have to be resolved by human judgment and communication. Experience has shown that merging is superior to locking, both in convenience to developers and in minimizing the number and severity of conflicts that actually occur.

SCCS always uses locking. RCS is lock-based by default but can be told to operate in a merging style. CVS and Subversion are merge-based by default but can be told to operate in a locking mode. Decentralized version control systems, such as Git and Mercurial, are exclusively merging-based.

VC mode supports both locking and merging version control. The terms “commit” and “update” are used in newer version control systems; older lock-based systems use the terms “check in” and “check out”. VC hides the differences between them as much as possible.

Next: Decentralized vs Centralized Repositories, Previous: Merge-based vs Lock-based Version Control, Up: Introduction to Version Control   [Contents][Index]

30.1.1.5 Changeset-based vs File-based Version Control ¶

On SCCS, RCS, CVS, and other early version control systems (and also in SRC), version control operations are file-based: each file has its own comment and revision history separate from that of all other files. Newer systems, beginning with Subversion, are changeset-based: a commit may include changes to several files, and the entire set of changes is handled as a unit. Any comment associated with the change does not belong to a single file, but to the changeset itself.

Changeset-based version control is more flexible and powerful than file-based version control; usually, when a change to multiple files has to be reversed, it’s good to be able to easily identify and remove all of it.

Next: Types of Log File, Previous: Changeset-based vs File-based Version Control, Up: Introduction to Version Control   [Contents][Index]

30.1.1.6 Decentralized vs Centralized Repositories ¶

Early version control systems were designed around a centralized model in which each project has only one repository used by all developers. SCCS, RCS, CVS, Subversion, and SRC share this kind of model. One of its drawbacks is that the repository is a choke point for reliability and efficiency.

GNU Arch pioneered the concept of distributed or decentralized version control, later implemented in Git, Mercurial, and Bazaar. A project may have several different repositories, and these systems support a sort of super-merge between repositories that tries to reconcile their change histories. In effect, there is one repository for each developer, and repository merges take the place of commit operations.

VC helps you manage the traffic between your personal workfiles and a repository. Whether the repository is a single master, or one of a network of peer repositories, is not something VC has to care about.

Previous: Decentralized vs Centralized Repositories, Up: Introduction to Version Control   [Contents][Index]

30.1.1.7 Types of Log File ¶

Projects that use a version control system can have two types of log for changes. One is the log maintained by the version control system: each time you commit a change, you fill out a log entry for the change (see Features of the Log Entry Buffer). This is called the version control log.

The other kind of log is the file ChangeLog (see Change Logs). It provides a chronological record of all changes to a large portion of a program—typically one directory and its subdirectories. A small program would use one ChangeLog file; a large program may have a ChangeLog file in each major directory. See Change Logs. Programmers have used change logs since long before version control systems.

Changeset-based version systems typically maintain a changeset-based modification log for the entire system, which makes change log files somewhat redundant. One advantage that they retain is that it is sometimes useful to be able to view the transaction history of a single directory separately from those of other directories. Another advantage is that mistakes in commit logs can’t be fixed in many version control systems.

A project maintained with version control can use just the version control log, or it can use both kinds of logs. It can handle some files one way and some files the other way. Each project has its policy, which you should follow.

When the policy is to use both, you typically want to write an entry for each change just once, then put it into both logs. You can write the entry in ChangeLog, then copy it to the log buffer with C-c C-a when committing the change (see Features of the Log Entry Buffer). Or you can write the entry in the log buffer while committing the change (with the help of C-c C-w), and later use the C-x v a command to copy it to ChangeLog (see Change Logs and VC).

Next: Basic Version Control with Locking, Up: Basic Editing under Version Control   [Contents][Index]

30.1.3.1 Basic Version Control with Merging ¶

With a modern merging-based version control system (such as Git and Hg; see Merge-based vs Lock-based Version Control), C-x v v does the following when invoked from a buffer that visits a version-controlled file or a VC Directory or Dired buffer:

• If there is more than one file in the VC fileset and the files have inconsistent version control statuses, signal an error. (Note, however, that a fileset is allowed to include both newly-added files, removed files and modified files; see Registering a File for Version Control.) Also signal an error if any files in the fileset are ignored by version control.
• If every file in the VC fileset is registered and unchanged with respect to the last revision, do nothing.
• If none of the files in the VC fileset are registered with a version control system, register the newly-added files in the VC fileset, i.e., place them under version control. See Registering a File for Version Control. If Emacs cannot find a system to register under, it prompts for a repository type, creates a new repository, and registers the VC fileset with it. You can also specify the system explicitly, see Advanced Control in C-x v v. Note that registering the files doesn’t commit them; you must invoke C-x v v again to commit; see the next point.
• If every file in the VC fileset has been either newly-added or modified, commit the changed files. To do this, Emacs pops up a *vc-log* buffer; type the desired log entry for the changes, followed by C-c C-c to commit. See Features of the Log Entry Buffer.

  If C-x v v is invoked from a buffer under Diff mode, the command treats the buffer as holding a set of patches for one or more files. It then applies the changes to the respective files and commits the changes after popping up the *vc-log* buffer to allow you to type a suitable commit log message.

  Once you type C-x v v, the fileset or patches cannot be changed without first canceling the commit by typing C-c C-k in the *vc-log* buffer. For example, if you change which files are marked in the *vc-dir* buffer after Emacs has already popped up the *vc-log* buffer, the old fileset will remain in effect for this commit. (This is in contrast to changes made to the contents of files in the fileset when not committing patches: all such changes will be included in the commit even if they are made after Emacs has popped up the *vc-log* buffer.)

  When you cancel a commit, Emacs saves your log message. This means that if you need to adjust the fileset or patches, it is easy to restart the commit operation again: type C-c C-k C-x v v M-p. Here C-c C-k cancels the commit, C-x v v initiates another with the new fileset or patches, and finally M-p recalls your previous log message.

  With modern decentralized version control systems (Git, Mercurial, etc.), the changes are committed locally and not automatically propagated to the upstream repository (which is usually on a remote host). In these cases, if the repository has been changed since your last update, the commit may fail. In that case, you must update from upstream and then try again. Use C-x v + (see Pulling/Pushing Changes into/from a Branch) or C-x v m (see Merging Branches) for that.

  With a centralized version control system, if the commit fails due to upstream changes, type C-x v v again to merge in the upstream repository changes.

• Finally, if you are using a centralized version control system, if any file in the VC fileset is outdated with respect to the upstream repository, offer to update the fileset from the repository.

These rules also apply when you use RCS in its non-locking mode, except that changes are not automatically merged from the repository. Nothing informs you if another user has committed changes in the same file since you began editing it; when you commit your revision, that other user’s changes are removed (however, they remain in the repository and are thus not irrevocably lost). Therefore, you must verify that the current revision is unchanged before committing your changes. In addition, locking is possible with RCS even in this mode: C-x v v with an unmodified file locks the file, just as it does with RCS in its normal locking mode (see Basic Version Control with Locking).

Next: Advanced Control in C-x v v, Previous: Basic Version Control with Merging, Up: Basic Editing under Version Control   [Contents][Index]

30.1.3.2 Basic Version Control with Locking ¶

With a locking-based version control system (such as SCCS, and RCS in its default mode), C-x v v does the following:

• If there is more than one file in the VC fileset and the files have inconsistent version control statuses, signal an error. Also signal an error if any files in the fileset are ignored by version control.
• If each file in the VC fileset is not registered with a version control system, register the newly-added files in the fileset. See Registering a File for Version Control. If Emacs cannot find a system to register under, it prompts for a repository type, creates a new repository, and registers the VC fileset with it. You can also specify the system explicitly, see Advanced Control in C-x v v.
• If each file is registered and unlocked, check the files out: lock each one and make it writable, so that you can begin to edit it.
• If each file is locked by you and contains changes, commit (a.k.a. “check-in”) the changes. To do this, Emacs pops up a *vc-log* buffer; type the desired log entry for the new revision, followed by C-c C-c to commit (see Features of the Log Entry Buffer).
• If each file is locked by you, but you have not changed it, release the lock and make the file read-only again. This undoes previous check-out operation for files that were not changed since the checkout.
• If each file is locked by another user, ask whether you want to steal the lock. If you say yes, the file becomes locked by you, and a warning message is sent to the user who had formerly locked the file.
• If files in the fileset are unlocked, but have changes with respect to their last revision, offer to claim the lock for each such file or to revert the file to the last checked-in revision. (This situation is exceptional and should not normally happen.)

These rules also apply when you use CVS in locking mode, except that CVS does not support stealing locks.

Previous: Basic Version Control with Locking, Up: Basic Editing under Version Control   [Contents][Index]

30.1.3.3 Advanced Control in C-x v v ¶

When you give a prefix argument to vc-next-action (C-u C-x v v), it still performs the next logical version control operation, but accepts additional arguments to specify precisely how to do the operation.

• You can specify the name of a version control system. This is useful if the fileset can be managed by more than one version control system, and Emacs fails to detect the correct one.
• Otherwise, if using CVS, RCS or SRC, you can specify a revision ID.

  If the fileset is modified (or locked), this makes Emacs commit the files with that revision ID. You can create a new branch by supplying an appropriate revision ID (see Version Control Branches).

  If the fileset is unmodified (and unlocked), this checks out the specified revision into the working tree. You can also specify a revision on another branch by giving its revision or branch ID (see Switching between Branches). An empty argument (i.e., C-u C-x v v RET) checks out the latest (a.k.a. “head”) revision on the current branch.

  Specifying revision ID in this manner is silently ignored by a decentralized version control system. Those systems do not let you specify your own revision IDs, nor do they use the concept of checking out individual files.

Next: VC Directory Commands, Up: VC Directory Mode   [Contents][Index]

30.1.10.1 The VC Directory Buffer ¶

The VC Directory buffer contains a list of version-controlled files and their version control statuses. It lists files in the current directory (the one specified when you called C-x v d) and its subdirectories, but only those with a noteworthy status. Files that are up-to-date (i.e., the same as in the repository) or ignored are omitted. If all the files in a subdirectory are up-to-date, the subdirectory is not listed either. As an exception, if a file has become up-to-date as a direct result of a VC command, it is listed by default.

Here is an example of a VC Directory buffer listing:

                     ./
    edited           configure.ac
*   added            README
    unregistered     temp.txt
                     src/
*   edited           src/main.c

Two work files have been modified but not committed: configure.ac in the current directory, and main.c in the src/ subdirectory. The file named README has been added but is not yet committed, while temp.txt is not under version control (see Registering a File for Version Control).

The ‘*’ characters next to the entries for README and src/main.c indicate that the user has marked these files as the current VC fileset (see VC Directory Commands).

The above example is typical for a decentralized version control system like Bazaar, Git, or Mercurial (see Decentralized vs Centralized Repositories). Other systems can show other statuses. For instance, CVS shows the ‘needs-update’ status if the repository has changes that have not been applied to the work file. RCS and SCCS show the name of the user locking a file as its status.

As mentioned above, by default files and directories which become up-to-date or ignored after the VC Directory buffer is first displayed stay displayed. To automatically remove such files from display, customize the variable vc-dir-auto-hide-up-to-date to the value t. You can also customize it to the value revert, in which case such files will be removed only when you refresh the VC Directory display, e.g., by typing g (see VC Directory Commands).

On CVS, the vc-dir command normally contacts the repository, which may be on a remote machine, to check for updates. If you change the variable vc-cvs-stay-local to nil (see Options specific for CVS), then Emacs avoids contacting a remote repository when generating the VC Directory buffer (it will still contact it when necessary, e.g., when doing a commit). This may be desirable if you are working offline or the network is slow.

The VC Directory buffer omits subdirectories listed in the variable vc-directory-exclusion-list. Its default value contains directories that are used internally by version control systems.

At the top of the buffer Emacs displays some information about the repository, such as the name of the backend in use and the working directory. In addition, for decentralized VCS, if you have outgoing commits (see VC Change Log), Emacs displays a line "Outgoing : N unpushed revisions" where N is a number. You can click on this text to execute the vc-root-log-outgoing command (see VC Change Log).

Emacs tries to use cached information to determine the number of unpushed revisions, but for some backends this isn’t possible. In these cases Emacs must occasionally fetch from the remote repository in order to determine the count. If your connection to the remote repository is slow then this may cause unacceptable slowdowns in refreshing the VC Directory buffer. If this affects you, you can customize vc-dir-show-outgoing-count to nil to disable the unpushed revisions count altogether. You can also set this on a per-repository basis using directory local variables (see Per-Directory Local Variables).

Previous: The VC Directory Buffer, Up: VC Directory Mode   [Contents][Index]

30.1.10.2 VC Directory Commands ¶

Emacs provides several commands for navigating the VC Directory buffer, for marking files as belonging to the current VC fileset, and for operating on the VC fileset.

n

SPC

Move point to the next entry (vc-dir-next-line).

p

Move point to the previous entry (vc-dir-previous-line).

TAB

Move to the next directory entry (vc-dir-next-directory).

S-TAB

Move to the previous directory entry (vc-dir-previous-directory).

RET

f

Visit the file or directory listed on the current line (vc-dir-find-file).

o

Visit the file or directory on the current line, in a separate window (vc-dir-find-file-other-window).

m

Mark the file or directory on the current line (vc-dir-mark), putting it in the current VC fileset. If the region is active, mark all files in the region.

A file cannot be marked with this command if it is already in a marked directory, or one of its subdirectories. Similarly, a directory cannot be marked with this command if any file in its tree is marked.

M

If point is on a file entry, mark all files with the same status; if point is on a directory entry, mark all files in that directory tree (vc-dir-mark-all-files). With a prefix argument, mark all listed files and directories.

% m ¶

* %

You can use this command to mark files by regexp (vc-dir-mark-by-regexp). If given a prefix, unmark files instead.

* r ¶

You can use this command to mark files that are in one of registered states, including edited, added or removed. (vc-dir-mark-registered-files).

G

Add the file under point to the list of files that the VC should ignore (vc-dir-ignore). For instance, if the VC is Git, it will append this file to the .gitignore file. If given a prefix, do this with all the marked files.

@

Discard all the changes you have made to the current fileset (vc-revert).

V

Take the next logical version control operation on all files shown in the VC Directory buffer (vc-dir-root-next-action). This is like C-x v v (see Basic Editing under Version Control) except that it ignores any marks and the position of point.

u

Unmark the file or directory on the current line. If the region is active, unmark all the files in the region (vc-dir-unmark).

U

If point is on a file entry, unmark all files with the same status; if point is on a directory entry, unmark all files in that directory tree (vc-dir-unmark-all-files). With a prefix argument, unmark all files and directories.

x

Hide files with ‘up-to-date’ or ‘ignored’ status (vc-dir-hide-up-to-date). With a prefix argument, hide items whose state is that of the item at point.

g

Refresh the VC Directory buffer display (revert-buffer).

q

Quit the VC Directory buffer, and bury it (quit-window).

While in the VC Directory buffer, all the files that you mark with m (vc-dir-mark) or M (vc-dir-mark-all-files) are in the current VC fileset. If you mark a directory entry with m, all the listed files in that directory tree are in the current VC fileset. The files and directories that belong to the current VC fileset are indicated with a ‘*’ character in the VC Directory buffer, next to their VC status. In this way, you can set up a multi-file VC fileset to be acted on by VC commands like C-x v v (see Basic Editing under Version Control), C-x v = (see Examining And Comparing Old Revisions), and C-x v u (see Undoing Version Control Actions).

The VC Directory buffer also defines some single-key shortcuts for VC commands with the C-x v prefix: =, +, l, i, D, L, G, I, O, and v.

For example, you can commit a set of edited files by opening a VC Directory buffer, where the files are listed with the ‘edited’ status; marking the files; and typing v or C-x v v (vc-next-action). If the version control system is changeset-based, Emacs will commit the files in a single revision.

While in the VC Directory buffer, you can also perform search and replace on the current VC fileset, with the following commands:

S

Search the fileset (vc-dir-search).

Q

Do a regular expression query replace on the fileset (vc-dir-query-replace-regexp).

M-s a C-s

Do an incremental search on the fileset (vc-dir-isearch).

M-s a C-M-s

Do an incremental regular expression search on the fileset (vc-dir-isearch-regexp).

Apart from acting on multiple files, these commands behave much like their single-buffer counterparts (see Searching and Replacement).

The VC Directory buffer additionally defines some branch-related commands starting with the prefix b:

b c

Create a new branch (vc-create-branch). See Creating New Branches.

b L

Prompt for the name of a branch and display the change history of that branch (vc-print-root-branch-log).

b s

Switch to a branch (vc-switch-branch). See Switching between Branches.

d

Delete the marked files, or the current file if no marks (vc-dir-delete-file). If the files are registered, they will be marked as deleted in the version control system.

The above commands are also available via the menu bar, and via a context menu invoked by mouse-2. Furthermore, some VC backends use the menu to provide extra backend-specific commands. For example, Git and Bazaar allow you to manipulate stashes and shelves (which are a way to temporarily put aside uncommitted changes, and bring them back at a later time).

Next: Pulling/Pushing Changes into/from a Branch, Up: Version Control Branches   [Contents][Index]

30.1.11.1 Switching between Branches ¶

The various version control systems differ in how branches are implemented, and these differences cannot be entirely concealed by VC.

On some decentralized version control systems, including Bazaar and Mercurial in its normal mode of operation, each branch has its own working directory tree, so switching between branches just involves switching directories. On Git, branches are normally co-located in the same directory, and switching between branches is done using the git checkout command, which changes the contents of the working tree to match the branch you switch to. Bazaar also supports co-located branches, in which case the bzr switch command will switch branches in the current directory. With Subversion, you switch to another branch using the svn switch command. With Mercurial, command hg update is used to switch to another branch.

The VC command to switch to another branch in the current directory is C-x v b s branch-name RET (vc-switch-branch).

On centralized version control systems, you can also switch between branches by typing C-u C-x v v in an up-to-date work file (see Advanced Control in C-x v v), and entering the revision ID for a revision on another branch. On CVS, for instance, revisions on the trunk (the main line of development) normally have IDs of the form 1.1, 1.2, 1.3, …, while the first branch created from (say) revision 1.2 has revision IDs 1.2.1.1, 1.2.1.2, …, the second branch created from revision 1.2 has revision IDs 1.2.2.1, 1.2.2.2, …, and so forth. You can also specify the branch ID, which is a branch revision ID omitting its final component (e.g., 1.2.1), to switch to the latest revision on that branch.

On a locking-based system, switching to a different branch also unlocks (write-protects) the working tree.

Once you have switched to a branch, VC commands will apply to that branch until you switch away; for instance, any VC filesets that you commit will be committed to that specific branch.

Next: Merging Branches, Previous: Switching between Branches, Up: Version Control Branches   [Contents][Index]

30.1.11.2 Pulling/Pushing Changes into/from a Branch ¶

C-x v P ¶

With a decentralized version control system, update another repository with locally-committed changes from the current branch (a.k.a. push changes). This concept does not exist for centralized version control systems

C-x v + ¶

With a decentralized version control system, update the current branch of the local repository by pulling in changes from another repository.

With a centralized version control system, update the current VC fileset from the repository.

On a decentralized version control system, the command C-x v P (vc-push) updates another location, commonly known as the upstream repository, with locally-committed changes from the current branch. With a prefix argument, it prompts for the exact version control command to run, which lets you specify where to push changes; the default is bzr push with Bazaar, git push with Git, and hg push with Mercurial. The default commands always push to the repository in the default location determined by the version control system from your branch configuration.

Prior to pushing, you can use C-x v O (vc-root-log-outgoing) to view a log buffer of the changes to be sent upstream. See VC Change Log.

This command is currently supported only by Bazaar, Git, and Mercurial. The concept of “pushing” does not exist for centralized version control systems, where this operation is a part of committing a changeset, so invoking this command on a centralized VCS signals an error. This command also signals an error when attempted in a Bazaar bound branch, where committing a changeset automatically pushes the changes to the remote repository to which the local branch is bound.

With a decentralized version control system, the command C-x v + (vc-pull) updates the current branch of the local repository and it working tree with changes made in the upstream repository. It is typically used to update a copy (a.k.a. clone) of a remote branch. If you supply a prefix argument, the command prompts for the exact version control command to use, which lets you specify where to pull changes from. Otherwise, it pulls from the repository in the default location determined by the version control system from your branch configuration.

Amongst decentralized version control systems, C-x v + is currently supported only by Bazaar, Git, and Mercurial. With Bazaar, it calls bzr pull for ordinary branches (to pull from a master branch into a mirroring branch), and bzr update for a bound branch (to pull from a central repository). With Git, it calls git pull to fetch changes from a remote repository and merge it into the current branch. With Mercurial, it calls hg pull -u to fetch changesets from the default remote repository and update the working directory.

Prior to pulling, you can use C-x v I (vc-root-log-incoming) to view a log buffer of the changes to be applied. See VC Change Log.

With a centralized version control system like CVS, C-x v + updates the current VC fileset from the repository.

Next: Creating New Branches, Previous: Pulling/Pushing Changes into/from a Branch, Up: Version Control Branches   [Contents][Index]

30.1.11.3 Merging Branches ¶

C-x v m

With a decentralized version control system, merge changes from another branch into the current one.

With a centralized version control system, merge changes from another branch into the current VC fileset.

While developing a branch, you may sometimes need to merge in changes that have already been made in another branch. This is not a trivial operation, as overlapping and conflicting changes may have been made to the two branches.

With a decentralized version control system, you merge changes with the command C-x v m (vc-merge). With Bazaar, this prompts for the exact arguments to pass to the bzr merge command, offering a sensible default if possible. With Git, this prompts for the name of a branch to merge from, with completion (based on the branch names known to the current repository). With Mercurial, this prompts for argument to pass to hg merge. The output from running the merge command is shown in a separate buffer.

With a centralized version control system like CVS, C-x v m prompts for a branch ID, or a pair of revision IDs (see Switching between Branches); then it finds the changes from that branch, or the changes between the two revisions you specified, and merges those changes into the current VC fileset. If you just type RET at the prompt, Emacs simply merges any changes that were made on the same branch since you checked the file out.

Immediately after performing a merge, only the working tree is modified, and you can review the changes produced by the merge with C-x v D and related commands (see Examining And Comparing Old Revisions). If the two branches contained overlapping changes, merging produces a conflict; a warning appears in the output of the merge command, and conflict markers are inserted into each affected work file, surrounding the two sets of conflicting changes. You must then resolve the conflict by editing the conflicted files; by default, Emacs will place buffers with VC conflicts in the special Smerge mode, which provides special commands for resolving the merge conflicts. Once you are done with resolving the conflicts and have saved the files with resolved conflicts, those files must be committed in the usual way for the merge to take effect (see Basic Editing under Version Control).

Next: Copying Changes Made By Revisions Between Branches, Previous: Merging Branches, Up: Version Control Branches   [Contents][Index]

30.1.11.4 Creating New Branches ¶

On centralized version control systems like CVS, Emacs supports creating new branches as part of a commit operation. When committing a modified VC fileset, type C-u C-x v v (vc-next-action with a prefix argument; see Advanced Control in C-x v v). Then Emacs prompts for a revision ID for the new revision. You should specify a suitable branch ID for a branch starting at the current revision. For example, if the current revision is 2.5, the branch ID should be 2.5.1, 2.5.2, and so on, depending on the number of existing branches at that point.

This procedure will not work for distributed version control systems like Git or Mercurial. For those systems you should use the command vc-create-branch (C-x v b c branch-name RET) instead.

To create a new branch at an older revision (one that is no longer the head of a branch), first select that revision (see Switching between Branches). Your procedure will then differ depending on whether you are using a locking or merging-based VCS.

On a locking VCS, you will need to lock the old revision branch with C-x v v. You’ll be asked to confirm, when you lock the old revision, that you really mean to create a new branch—if you say no, you’ll be offered a chance to lock the latest revision instead. On a merging-based VCS you will skip this step.

Then make your changes and type C-x v v again to commit a new revision. This creates a new branch starting from the selected revision.

After the branch is created, subsequent commits create new revisions on that branch. To leave the branch, you must explicitly select a different revision with C-u C-x v v.

Previous: Creating New Branches, Up: Version Control Branches   [Contents][Index]

30.1.11.5 Copying Changes Made By Revisions Between Branches ¶

M-x vc-cherry-pick

Copy a single revision to branch checked out in this working tree.

Sometimes it is useful to copy a revision from one branch to another. This means creating a new revision with the same changes, log message and authorship information as an existing revision that can be found on another branch. This is often called cherry-picking the revision from one branch to another.

The most common case is copying a revision from a branch that won’t be merged (see Merging Branches) into your current branch. For example, your project might have a feature-frozen branch that accepts only bug fixes. Someone (possibly you) fixes a bug on the main development branch. You can then cherry-pick that revision onto the feature-frozen branch in order to fix the bug there, too. This is called backporting the revision, or backporting the fix.

You can use the command M-x vc-cherry-pick to cherry-pick revisions. It prompts for a revision to cherry-pick. It then pops up a buffer for you to edit the log message for the new revision. Normally the VC backend generates a log message including a reference to the revision you want to copy, so that the copy can be traced. If you wish, you can delete this reference before typing C-c C-c to conclude the cherry-pick.

Alternatively you can invoke the command with a prefix argument, i.e. C-u M-x vc-cherry-pick. In this case the log message from the source revision is used unmodified, and the cherry-pick happens immediately, without popping up a buffer for log message edits.

An alternative way to access this functionality is the log-view-cherry-pick command, bound to C in Log View mode buffers (see VC Change Log). Compared to using M-x vc-cherry-pick directly, this can make it easier to be sure you are cherry-picking the revision you intend.

Next: Deleting and Renaming Version-Controlled Files, Up: Miscellaneous Commands and Features of VC   [Contents][Index]

30.1.12.1 Change Logs and VC ¶

If you use RCS or CVS for a program with a ChangeLog file (see Change Logs), you can generate change log entries from the version control log entries of previous commits.

Note that this only works with RCS or CVS. This procedure would be particularly incorrect on a modern changeset-based version control system, where changes to the ChangeLog file would normally be committed as part of a changeset. In that case, you should write the change log entries first, then pull them into the ‘*vc-log*’ buffer when you commit (see Features of the Log Entry Buffer).

C-x v a ¶

Visit the current directory’s ChangeLog file and, for registered files in that directory, create new entries for versions committed since the most recent change log entry (vc-update-change-log).

C-u C-x v a

As above, but only find entries for the current buffer’s file.

For example, suppose the first line of ChangeLog is dated 1999-04-10, and that the only check-in since then was by Nathaniel Bowditch to rcs2log on 1999-05-22 with log entry ‘Ignore log messages that start with '#'.’. Then C-x v a inserts this ChangeLog entry:

1999-05-22  Nathaniel Bowditch  <nat@apn.org>

        * rcs2log: Ignore log messages that start with '#'.

If the version control log entry specifies a function name (in parenthesis at the beginning of a line), that is reflected in the ChangeLog entry. For example, if a log entry for vc.el is ‘(vc-do-command): Check call-process status.’, the ChangeLog entry is:

1999-05-06  Nathaniel Bowditch  <nat@apn.org>

        * vc.el (vc-do-command): Check call-process status.

When C-x v a adds several change log entries at once, it groups related log entries together if they all are checked in by the same author at nearly the same time. If the log entries for several such files all have the same text, it coalesces them into a single entry.

Next: Revision Tags, Previous: Change Logs and VC, Up: Miscellaneous Commands and Features of VC   [Contents][Index]

30.1.12.2 Deleting and Renaming Version-Controlled Files ¶

C-x v x

Prompt for a file name, delete the file from the working tree, and schedule the deletion for committing.

C-x v R

Prompt for two file names, old and new, rename them in the working tree, and schedule the renaming for committing. The old file defaults to the current buffer’s file name if it is under VC.

If you wish to delete a version-controlled file, type C-x v x (vc-delete-file). This prompts for the file name, and deletes it via the version control system. The file is removed from the working tree, and in the VC Directory buffer (see VC Directory Mode), it is displayed with the ‘removed’ status. When you commit it, the deletion takes effect in the repository.

To rename a version-controlled file, type C-x v R (vc-rename-file). This prompts for two arguments: the name of the file you wish to rename, and the new name; then it performs the renaming via the version control system. The renaming takes effect immediately in the working tree, and takes effect in the repository when you commit the renamed file.

On modern version control systems that have built-in support for renaming, the renamed file retains the full change history of the original file. On CVS and older version control systems, the vc-rename-file command actually works by creating a copy of the old file under the new name, registering it, and deleting the old file. In this case, the change history is not preserved.

Next: Merge Bases, Previous: Deleting and Renaming Version-Controlled Files, Up: Miscellaneous Commands and Features of VC   [Contents][Index]

30.1.12.3 Revision Tags ¶

Most version control systems allow you to apply a revision tag to a specific version of a version-controlled tree. On modern changeset-based version control systems, a revision tag is simply a symbolic name for a particular revision. On older file-based systems like CVS, each tag is added to the entire set of version-controlled files, allowing them to be handled as a unit. Revision tags are commonly used to identify releases that are distributed to users.

There are two basic commands for tags; one makes a tag with a given name, the other retrieves a named tag.

C-x v s name RET ¶

Define the working revision of every registered file in or under the current directory as a tag named name (vc-create-tag).

C-x v r name RET ¶

For all registered files at or below the current directory level, retrieve the tagged revision name. This command will switch to a branch if name is a branch name and your VCS distinguishes branches from tags. (vc-retrieve-tag).

This command reports an error if any files are locked at or below the current directory, without changing anything; this is to avoid overwriting work in progress.

You can give a tag or branch name as an argument to C-x v = or C-x v ~ (see Examining And Comparing Old Revisions). Thus, you can use it to compare a tagged version against the current files, or two tagged versions against each other.

On SCCS, VC implements tags itself; these tags are visible only through VC. Most later systems (including CVS, Subversion, bzr, git, and hg) have a native tag facility, and VC uses it where available; those tags will be visible even when you bypass VC.

In file-based version control systems, when you rename a registered file you need to rename its master along with it; the command C-x v R (vc-rename-file) will do this automatically (see Deleting and Renaming Version-Controlled Files). If you are using SCCS, you must also update the records of the tag, to mention the file by its new name (C-x v R does this, too). An old tag that refers to a master file that no longer exists under the recorded name is invalid; VC can no longer retrieve it. It would be beyond the scope of this manual to explain enough about RCS and SCCS to explain how to update the tags by hand. Using C-x v R makes the tag remain valid for retrieval, but it does not solve all problems. For example, some of the files in your program probably refer to others by name. At the very least, the makefile probably mentions the file that you renamed. If you retrieve an old tag, the renamed file is retrieved under its new name, which is not the name that the makefile expects. So the program won’t really work as retrieved.

Next: Commands to see all unintegrated changes, Previous: Revision Tags, Up: Miscellaneous Commands and Features of VC   [Contents][Index]

30.1.12.4 Merge Bases ¶

C-x v M D

Report diffs of changes on a branch since it diverged from another (vc-diff-mergebase).

C-x v M L

Display log messages for revisions on a branch since it diverged from another (vc-log-mergebase).

The merge base of two branches is the most recent revision that exists on both branches. If neither of the branches was ever merged into the other (see Merging Branches), then the merge base is the revision that the older of the two branches was at when the newer branch was created from it (see Creating New Branches). If one of the branches was ever merged into the other, then the merge base is the most recent merge point.

The commands described in this section are currently implemented only for decentralized version control systems (see Decentralized vs Centralized Repositories).

Merge bases are useful to make certain comparisons between branches, and Emacs provides two commands for doing so. Each of C-x v M D (vc-diff-mergebase) and C-x v M L (vc-log-mergebase) prompts for two branches, finds their merge base, and then compares that merge base with the second of the two branches. The commands report diffs and display change history, respectively.

The typical use case for these commands is when one of the branches was originally created from the other and you or a collaborator have made merges of one of the branches into the other at least once. Then you can use these commands to see what changes on one branch have not yet been merged into the other.

Call the branch which has the changes you are interested in the “source branch” and the branch into which these changes have not yet been merged the “target branch”. Specify the target branch when prompted for the “older revision” and the source branch when prompted for the “newer revision”.²⁰ Then C-x v M D shows you a preview of what would change on the target branch if you were to merge the source branch into it, and C-x v M L shows you a log of the changes on the source branch not yet merged into the target branch.

Next: Multiple Working Trees for One Repository, Previous: Merge Bases, Up: Miscellaneous Commands and Features of VC   [Contents][Index]

30.1.12.5 Commands to see all unintegrated changes ¶

C-x v T =

Display diffs of changes to the VC fileset since the merge base of this branch and its upstream counterpart (vc-diff-unintegrated).

C-x v T D

Display a diff of all changes since the merge base of this branch and its upstream counterpart (vc-root-diff-unintegrated).

C-x v T l

Display log messages for changes to the VC fileset since the merge base of this branch and its upstream counterpart (vc-log-unintegrated).

C-x v T L

Display log messages for all changes since the merge base of this branch and its upstream counterpart (vc-root-log-unintegrated).

C-x v T R =

Display diffs of remote changes to the VC fileset since the merge base of this topic branch and its upstream counterpart (vc-diff-remote-unintegrated).

C-x v T R D

Display a diff of all remote changes since the merge base of this topic branch and its upstream counterpart (vc-root-diff-remote-unintegrated).

C-x v T R l

Display log messages for remote changes to the VC fileset since the merge base of this topic branch and its upstream counterpart (vc-log-remote-unintegrated).

C-x v T R L

Display log messages for all remote changes since the merge base of this topic branch and its upstream counterpart (vc-root-log-remote-unintegrated).

For decentralized version control systems (see Decentralized vs Centralized Repositories), these commands provide specialized versions of C-x v M L and C-x v M D (see see Merge Bases) which also take into account the state of upstream repositories. These commands are useful both when working on a single branch and when developing features on a separate branch (see Version Control Branches). These two cases are conceptually distinct, and so we will introduce them separately.

First, consider working on a single branch. Unintegrated changes are those which you haven’t yet pushed upstream. This includes both unpushed commits and uncommitted changes in your working tree. In many cases the reason these changes are not pushed yet is that they are not finished: the changes committed so far don’t make sense in isolation.

Type C-x v T D (vc-root-diff-unintegrated) to display a summary of all these changes, committed and uncommitted. This summary is in the form of a diff of what committing and pushing (see Pulling/Pushing Changes into/from a Branch) all these changes would do to the upstream repository. You can use C-x v T = (vc-diff-unintegrated) instead to limit the display of changes to the current VC fileset. (The difference between C-x v T D and C-x v T = is like the difference between C-x v D and C-x v = (see Examining And Comparing Old Revisions).)²¹

Type C-x v T L (vc-root-log-unintegrated) to display a summary of the same changes in the form of a revision log; this does not include uncommitted changes. You can use C-x v T l (vc-log-unintegrated) instead to limit the display of changes to the current VC fileset.

Second, consider developing a feature on a separate branch. Call this the topic branch,²² and call the branch from which the topic branch was originally created the trunk or development trunk.

In this case, unintegrated changes is a more specific notion than just unpushed and uncommitted changes on the topic branch. You’re not finished sharing changes with your collaborators until they have been merged into the trunk, and pushed. Therefore, in this example, unintegrated changes are those which haven’t yet been included in the upstream repository’s development trunk. That means committed changes on the topic branch that haven’t yet been merged into the trunk, plus uncommitted changes.

When the current branch is a topic branch and you type C-x v T D, Emacs displays a summary of all the changes that are outstanding against the trunk to which the current branch will be merged. This summary is in the form of a diff of what committing and pushing all the changes, and subsequently merging the topic branch, would do to the trunk. As above, you can use C-x v T = instead to limit the display of changes to the current VC fileset. C-x v T L and C-x v T l show the corresponding revision logs, excluding uncommitted changes as above.

On topic branches, it is sometimes also useful to see the same information but for the remote repository’s version of the topic branch. This is the outstanding work on the topic branch that has been pushed, but not yet merged. It is visible to your collaborators but is otherwise still unintegrated. We call such work remote unintegrated changes. There is a command corresponding to each of the four commands discussed so far but which operates on the remote repository’s version of the current topic branch: C-x v R T = (vc-diff-remote-unintegrated), C-x v R T D (vc-root-diff-remote-unintegrated), C-x v R T l (vc-log-remote-unintegrated), and C-x v R T L (vc-root-log-remote-unintegrated).

All this functionality relies on Emacs correctly detecting whether the current branch is a trunk or a topic branch, and in the latter case, correctly determining the branch to which the topic branch will eventually be merged. If the autodetection doesn’t produce the right results, there are several options to tweak and override it.

The variables vc-trunk-branch-regexps and vc-topic-branch-regexps contain lists of regular expressions matching the names of branches that should always be considered trunk and topic branches, respectively. You can also specify prefix arguments to C-x v T …. Here is a summary of how to use these controls:

1. If the problem is that Emacs thinks your topic branch is a trunk, you can add either its name, or a regular expression matching its name (see Syntax of Regular Expressions), to the vc-topic-branch-regexps variable. There are a few special kinds of value to simplify common use cases:
   • If an element contains no characters that are special in regular expressions, then the regular expression is implictly anchored at both ends, i.e., it matches only a branch with exactly that name.
   • If the first element of vc-topic-branch-regexps is the symbol not, then the meaning of vc-topic-branch-regexps is inverted, in that Emacs treats all branches whose names don’t match any element of vc-topic-branch-regexps to be topic branches.
   • If instead of a list of regular expressions the vc-topic-branch-regexps variable has the special value t, then Emacs treats as a topic branch any branch that the vc-trunk-branch-regexps variable doesn’t positively identify as a trunk.

   See Per-Directory Local Variables, regarding how to specify values of vc-topic-branch-regexps and vc-trunk-branch-regexps for a single VC repository.

2. If the problem is that Emacs thinks your trunk is a topic branch, you can add either its name, or a regular expression matching its name, to the vc-trunk-branch-regexps variable. This works just like vc-topic-branch-regexps with the same special values we just described. E.g., if the value of vc-trunk-branch-regexps is t, Emacs treats as a trunk any branch that the vc-topic-branch-regexps variable doesn’t identify as a topic branch.
3. Supply a double prefix argument, i.e. C-u C-u C-x v T …, and Emacs will treat the current branch as a trunk, no matter what. This is useful when you simply want to obtain a diff of all outgoing changes (see VC Change Log) plus uncommitted changes.
4. Finally, you can take full manual control by supplying a single prefix argument, i.e. C-u C-x v T …. Emacs will prompt you for the outgoing base, which is the upstream location for which the changes are destined once they are no longer outstanding.

   To treat the current branch as a trunk specify a reference to the upstream version of the current branch, to which you and your collaborators push finished work. To treat the current branch as a topic branch specify a reference to the upstream version of the trunk to which the topic branch will later be merged.

   Exactly how to specify a reference to the upstream version of a branch depends on the version control system in use. For example, with Git, to refer to the upstream version of a branch foo, you would supply origin/foo. So if foo is the current branch then you would enter an outgoing base of origin/foo to treat foo as a trunk, or an outgoing base of origin/bar to treat foo as a topic branch which will later be merged into a trunk named bar.

   If there is a default option, it is what Emacs thinks you need to enter in order to treat the current branch as a topic branch. If there is no default, then entering nothing at the prompt means to treat the current branch as a trunk.

Next: Inserting Version Control Headers, Previous: Commands to see all unintegrated changes, Up: Miscellaneous Commands and Features of VC   [Contents][Index]

30.1.12.6 Multiple Working Trees for One Repository ¶

Some VCS support more than one working tree with the same backing repository or revisions store. This means that you can have different revisions or branches (see Version Control Branches) checked out simultaneously, in different working trees, but with all revision history, branches, tags and other metadata shared.

Suppose your project has a trunk where you’re developing the new version 3 of your software, and a stable release branch from which you make point releases of version 2. Someone sends you a patch fixing a bug that’s present in version 2. Your main working tree has version 3 checked out, and you’re in the middle of a big refactor that you don’t want to disturb. So you type C-x v w c (see below) and create a new working tree, following the prompts to check out the version 2 branch there.

You apply the patch to that working tree using C-x v w a (see below), build and test it. Satisfied, you use C-x v P (see Pulling/Pushing Changes into/from a Branch) in the other working tree. In the course of testing the patch, you’ve realized that the bug exists in version 3 of the software, too. So you switch back to your first working tree, and use C-x v m (see Merging Branches) to merge the branch you have checked out in the other working tree. Now your version of the trunk has all of version 2’s fixes merged into it, but you haven’t pushed it yet because you’re still refactoring. You’ll use C-x v P later.

Ordinary VC commands like C-x v v (see Basic Editing under Version Control) and C-x v d (see VC Directory Mode) don’t work any differently when there exist other working trees, except that the commits, branches and other VC artifacts they create will be visible from all working trees. Another way to put this is that any action taken in any working tree which creates new artifacts in the VCS backing store will be visible from other working trees, but actions which only affect workfiles won’t be. So if you apply a patch to some workfiles in one working tree, that only affects that working tree. But if you commit the changes made by applying the patch, then that creates a new revision in the backing store, and so this action affects other working trees in the sense that their view of the repository’s history will now have an additional commit in it.

The following special commands let you switch between and modify different working trees. It is an error to use them other than from within a VC working tree; that is, from a buffer visiting a VCS-controlled file, or otherwise from a buffer whose default-directory (see File Names) is within a VC working tree.

C-x v w c

Add a new working tree.

C-x v w w

Visit this file or directory in another working tree.

C-x v w k

Kill buffers visiting this file in other working trees.

C-x v w s

Invoke C-x p p (project-switch-project) but limited to other working trees.

C-x v w a

Copy or move fileset changes to another working tree.

C-x v w A

Copy or move all changes to another working tree.

C-x v w x

Delete a working tree you no longer need.

C-x v w R

Relocate a working tree to another file name.

You can start using multiple working trees by using the command C-x v w c (vc-add-working-tree) to create a new working tree. This prompts you to specify a destination directory, which identifies the working tree, and which will hold the new set of workfiles.

Different VCS have different rules about what may and must be checked out in other working trees, so there may be additional prompts depending on the VCS in use. For example, Git requires that each branch be checked out in only one working tree at a time, so when using Git, Emacs will also prompt you for the name of the branch to be checked out in the new working tree.

Once your repository has other working trees, you can use the command C-x v w w (vc-switch-working-tree) to switch between them. It tries to find the analogue of the current buffer’s file or directory under another working tree. Typically the sets of workfiles under different working trees differ more in file contents than in which files do and do not exist. In other words, the file or directory the current buffer visits probably exists in other working trees too, and this command lets you switch to those versions of the file.

C-x v w w also works in Diff mode (see Diff Mode) and Log View mode (see VC Change Log). Instead of switching to a different buffer, the command changes the default directory of the buffer to the corresponding directory under another working tree. This is particularly useful from Log View mode buffers generated by commands like C-x v L (see VC Change Log). After using C-x v w w to change the default directory of the Log View buffer, you can move point to a revision of interest and type = (log-view-diff) to open a Diff mode buffer with that revision’s changes. Then you can use standard Diff mode commands like C-c C-a (diff-apply-hunk) to apply hunks to the other working tree.

After using C-x v w w in file-visiting buffers you will have multiple buffers visiting identically named files (see Making Buffer Names Unique). You can kill all but one of these buffers by typing C-x v w k (vc-kill-other-working-tree-buffers). This command kills buffers visiting versions of the current buffer’s file in other working trees, preserving the current buffer. It does not work in non-file-visiting buffers.

An alternative way to switch between working trees is C-x v w s (vc-working-tree-switch-project). This prompts you to select a working tree, and then displays a menu of commands to operate on it. This is in fact just C-x p p (project-switch-project) (see Switching Projects) but with the selection of projects limited to other working trees. The main difference between C-x v w w and C-x v w s is that the former looks for an analogue of the current buffer in the other working tree while the latter considers the other working tree as a whole, independent project.

The command C-x v w a (vc-apply-to-other-working-tree) prompts you to select another working tree, then copies changes from the current working tree to that other working tree. With a prefix argument, it moves changes instead of just copying them. Usually the command operates on local (uncommitted) changes to the current VC fileset. When invoked in a buffer under Diff mode (see Diff Mode), it operates on the changes specified by the contents of that buffer. The command stops and does nothing if any of the changes don’t apply to the target working tree.

C-x v w a is useful to copy changes to a temporary working tree in order to test them. It is also useful to copy fixes back to your main working tree for checking in. For example, you might hack away at a bug in a temporary working tree, and fix it. You’d then want to copy or move the fix back to your main working tree to check it in and push it.

The command C-x v w A works similarly, except that it always copies or moves all local changes to the whole working tree, not just changes to the current VC fileset or changes represented by the contents of a Diff mode buffer. With two prefix arguments, this command shows a preview of changes to be copied, leaving you to apply them using standard Diff mode commands like C-c C-a and C-c <RET> a (see Diff Mode). (C-u C-u C-x v w A is roughly equivalent to typing C-x v D followed by C-x v w w.)

The commands C-x v w x (vc-delete-working-tree) and C-x v w R (vc-move-working-tree) are for performing maintenance tasks on other working trees, letting you delete, move and rename them. Deleting other working trees is particular useful because a common use for multiple working trees is to create throwaway copies of the repository to quickly test changes, without interfering with any work-in-progress you may have in your primary working trees.

Next: Editing VC Commands, Previous: Multiple Working Trees for One Repository, Up: Miscellaneous Commands and Features of VC   [Contents][Index]

30.1.12.7 Inserting Version Control Headers ¶

On Subversion, CVS, RCS, and SCCS, you can put certain special strings called version headers into a work file. When the file is committed, the version control system automatically puts the revision number, the name of the user who made the commit, and other relevant information into the version header.

VC does not normally use the information in the version headers. As an exception, when using RCS, Emacs uses the version header, if there is one, to determine the file version, since it is often more reliable than the RCS master file. To inhibit using the version header this way, change the variable vc-consult-headers to nil. VC then always uses the file permissions (if it is supposed to trust them), or else checks the master file.

To insert a suitable header string into the current buffer, use the command M-x vc-insert-headers. This command works only on Subversion, CVS, RCS, and SCCS. The variable vc-backend-header contains the list of keywords to insert into the version header; for instance, CVS uses vc-cvs-header, whose default value is '("\$Id\$") (see Keyword substitution in CVS–Concurrent Versions System). (The extra backslashes prevent the string constant from being interpreted as a header, if the Emacs Lisp file defining it is maintained with version control.) The vc-insert-headers command inserts each keyword in the list on a new line at point, surrounded by tabs, and inside comment delimiters if necessary.

The variable vc-static-header-alist specifies further strings to add based on the name of the buffer. Its value should be a list of elements of the form (regexp . format). Whenever regexp matches the buffer name, format is also inserted as part of the version header. A ‘%s’ in format is replaced with the file’s version control type.

Next: Preparing Patches, Previous: Inserting Version Control Headers, Up: Miscellaneous Commands and Features of VC   [Contents][Index]

30.1.12.8 Editing VC Commands ¶

You can use the C-x v ! (vc-edit-next-command) prefix command to edit the shell command line that VC is about to run. This is primarily intended to make it possible to add optional command-line arguments to VCS commands without unnecessary complications of the VC command set and its interfaces with the backend.

For example, Git can produce logs of more than one branch, but C-x v b L (vc-print-root-branch-log) prompts for the name of just one branch. To obtain a log of more than one branch, you can type C-x v ! C-x v b L and then append the names of additional branches to the end of the ‘git log’ command that VC is about to run.

Next: Auto-Reverting Buffers That Visit Tracked Files, Previous: Editing VC Commands, Up: Miscellaneous Commands and Features of VC   [Contents][Index]

30.1.12.9 Preparing Patches ¶

When collaborating on projects it is common to send patches via email, to share changes. You can do this using VC with the vc-prepare-patch command. This will prompt you for the revisions you wish to share, and which destination email address(es) to use. Separate the revisions using the value of crm-separator, commas by default. The command will then prepare those revisions using your MUA (Mail User Agent) for you to review and send.

When invoked interactively in a Log View buffer with marked revisions, those marked revisions will be used.

Depending on the value of the user option vc-prepare-patches-separately, vc-prepare-patch will generate one or more messages. The default value t means prepare and display a message for each revision, one after another. A value of nil means to generate a single message with all patches attached in the body.

If you expect to contribute patches on a regular basis, you can set the user option vc-default-patch-addressee to the address(es) you wish to use. This will be used as the default value when invoking vc-prepare-patch. Project maintainers may consider setting this as a directory local variable (see Per-Directory Local Variables).

Next: Rewinding Branches, Previous: Preparing Patches, Up: Miscellaneous Commands and Features of VC   [Contents][Index]

30.1.12.10 Auto-Reverting Buffers That Visit Tracked Files ¶

When Emacs executes VCS operations that it knows may change the contents of tracked files, it reverts buffers visiting those files (see Reverting a Buffer). It does this in a VCS-aware fashion that retains the positions of point and the mark even when the VCS operation causes VCS keywords to be expanded (see Inserting Version Control Headers).

An important limitation of this feature is that Emacs won’t know to revert buffers when you execute additional VCS operations outside of Emacs, such as at a shell prompt, or by means of scripts. If you regularly do this, and you don’t use a VCS with keyword expansion (all modern VCS, absent special configuration), you may wish to enable vc-auto-revert-mode instead, by customizing that variable to a non-nil value.

This mode is just like global-auto-revert-mode (see Auto Revert: Keeping buffers automatically up-to-date) except limited to files visiting VCS-tracked files. It ensures that Emacs will always revert buffers when VCS operations change their contents, regardless of whether Emacs initiated those operations.

See Version Control and the Mode Line, for details regarding Auto Revert mode in buffers visiting tracked files (which is what vc-auto-revert-mode enables).

Previous: Auto-Reverting Buffers That Visit Tracked Files, Up: Miscellaneous Commands and Features of VC   [Contents][Index]

30.1.12.11 Rewinding Branches ¶

M-x vc-delete-revisions-from-end

Delete revisions from the end of the current branch.

M-x vc-uncommit-revisions-from-end

Delete revisions from the end of the current branch without touching the working tree.

For decentralized version control systems (see Decentralized vs Centralized Repositories), these commands provide ways to move the current branch back to an earlier revision. vc-delete-revisions-from-end prompts for a revision, then removes all revisions from the end of the branch up to but not including the specified revision. We say that the branch is rewound back to the specified revision.

This command removes the changes made by the revisions from the working tree. Therefore, if there are any uncommitted changes, they must be reverted, first (see Undoing Version Control Actions). This command will prompt you to do that if necessary. If you supply a prefix argument, Emacs will delete uncommitted changes without prompting.

To “uncommit” a revision means to remove it from the revision history without removing its changes from the working tree. It is as though you had made the changes but had not yet checked them in. The command vc-uncommit-revisions-from-end prompts for a revision, and then uncommits all revisions from the end of the branch up to but not including the specified revision. The branch is rewound back to the specified revision but the changes are left behind in the working tree.

When rewinding the current branch, if all the revisions deleted from the revision history are among those you have pulled or pushed, then these operations do not permanently delete anything: a simple C-x v + (see Pulling/Pushing Changes into/from a Branch) will bring the revisions back. On the other hand, if there are new revisions on the end of the branch that have not yet been pushed, then these commands will delete them permanently. Emacs tries to detect this situation and ask you if you are sure you want to delete them.

Alternative ways to access this functionality are the log-view-uncommit-revisions-from-end and log-view-delete-revisions-from-end commands, bound to x and X, respectively, in Log View mode buffers (see VC Change Log). Compared to using the commands described here directly, the Log View mode commands can make it easier to be sure you are rewinding back to the revision you intend.

Next: Options for RCS and SCCS, Up: Customizing VC   [Contents][Index]

30.1.13.1 General Options ¶

Emacs normally does not save backup files for source files that are maintained with version control. If you want to make backup files even for files that use version control, set the variable vc-make-backup-files to a non-nil value.

Editing a version-controlled file through a symbolic link may cause unexpected results, if you are unaware that the underlying file is version-controlled. The variable vc-follow-symlinks controls what Emacs does if you try to visit a symbolic link pointing to a version-controlled file. If the value is ask (the default), Emacs asks for confirmation. If it is nil, Emacs just displays a warning message. If it is t, Emacs automatically follows the link and visits the real file instead.

If vc-suppress-confirm is non-nil, then C-x v v and C-x v i can save the current buffer without asking, and C-x v u also operates without asking for confirmation.

VC mode does much of its work by running the shell commands for the appropriate version control system. If vc-command-messages has the value log, VC logs messages to the *Messages* buffer to indicate which shell commands it runs, and logs additional messages when the commands finish. If the variable has any other non-nil value, Emacs both logs and displays these messages.

VC mode runs certain shell commands asynchronously, allowing you to continue to use Emacs for other purposes while the command completes. This is mostly used for commands which access the network, such as pulling and pushing for distributed VCS (see Pulling/Pushing Changes into/from a Branch). When the command starts, VC displays a buffer into which the commands output will be written. If vc-display-failed-async-commands is non-nil, VC will additionally ensure that this buffer is displayed when the command finishes running but failed. This means you can freely close the window displaying the command’s buffer and know that it’ll pop up again in the case that running the command failed.

Normally checkin operations are done synchronously; that is, Emacs waits until the checkin has completed before doing anything else. This can be inconvenient for repositories in which the checkin operation is slow, such as Git repositories where you check in changes to very large files, or Mercurial repositories with a very large number of files.

For those backends which support it, setting vc-async-checkin to non-nil switches to doing checkin operations asynchronously. This is particularly useful as a directory local variable in repositories where checkin operations are slow (see Directory Local Variables in GNU Emacs Lisp Reference Manual).

While an asynchronous checkin operation is in progress, if you use C-x C-s to save a buffer visiting any file within the current VC tree, then the operation reverts to a synchronous checkin and Emacs waits for it to complete before saving the buffer. This is to avoid nondeterminism regarding exactly what changes get checked in.

Next: Options specific for CVS, Previous: General Options, Up: Customizing VC   [Contents][Index]

30.1.13.2 Options for RCS and SCCS ¶

By default, RCS uses locking to coordinate the activities of several users, but there is a mode called non-strict locking in which you can check-in changes without locking the file first. Use ‘rcs -U’ to switch to non-strict locking for a particular file, see the rcs manual page for details.

When deducing the version control state of an RCS file, VC first looks for an RCS version header string in the file (see Inserting Version Control Headers). If there is no header string, VC normally looks at the file permissions of the work file; this is fast. But there might be situations when the file permissions cannot be trusted. In this case the master file has to be consulted, which is rather expensive. Also the master file can only tell you if there’s any lock on the file, but not whether your work file really contains that locked version.

You can tell VC not to use version headers to determine the file status by setting vc-consult-headers to nil. VC then always uses the file permissions (if it is supposed to trust them), or else checks the master file.

VC determines the version control state of files under SCCS much as with RCS. It does not consider SCCS version headers, though. Thus, the variable vc-consult-headers does not affect SCCS use.

Previous: Options for RCS and SCCS, Up: Customizing VC   [Contents][Index]

30.1.13.3 Options specific for CVS ¶

You can specify additional command line options to pass to all CVS operations in the variable vc-cvs-global-switches. These switches are inserted immediately after the cvs command, before the name of the operation to invoke.

When using a CVS repository on a remote machine, VC can try keeping network interactions to a minimum. This is controlled by the variable vc-cvs-stay-local. If vc-cvs-stay-local is only-file (the default), VC determines the version control status of each file using only the entry in the local CVS subdirectory and the information returned by previous CVS commands. As a consequence, if you have modified a file and somebody else has checked in other changes, you will not be notified of the conflict until you try to commit.

If you change vc-cvs-stay-local to nil, VC queries the remote repository before it decides what to do in vc-next-action (C-x v v), just as it does for local repositories.

You can also set vc-cvs-stay-local to a regular expression that is matched against the repository host name; VC then stays local only for repositories from hosts that match the pattern.

When using a remote repository, Emacs normally makes automatic version backups of the original versions of each edited file. These local backups are made whenever you save the first changes to a file, and they are removed after you commit your changes to the repository. (Note that these are not the same as ordinary Emacs backup files; see Backup Files.) Commands like C-x v = and C-x v u make use of automatic version backups, if possible, to avoid having to access the network.

Setting vc-cvs-stay-local to nil disables the making of automatic version backups.

Automatic version backups have names of the form file.~version.~. This is similar to the name that C-x v ~ saves old versions to (see Examining And Comparing Old Revisions), except for the additional dot (‘.’) after the version. The relevant VC commands can use both kinds of version backups. The main difference is that the manual version backups made by C-x v ~ are not deleted automatically when you commit.

CVS does not use locking by default, but there are ways to enable locking-like behavior using its CVSREAD or watch feature; see the CVS documentation for details. If that case, you can use C-x v v in Emacs to toggle locking, as you would for a locking-based version control system (see Basic Version Control with Locking).

Next: Commands Available in the *xref* Buffer, Up: Find Identifiers   [Contents][Index]

30.4.1.1 Looking Up Identifiers ¶

The most important thing that xref enables you to do is to find the definition of a specific identifier.

M-.

Find definitions of an identifier (xref-find-definitions).

C-M-. pattern RET

Find all identifiers whose name matches pattern (xref-find-apropos).

C-x 4 . RET

Find definitions of identifier, but display it in another window (xref-find-definitions-other-window).

C-x 5 . RET

Find definition of identifier, and display it in a new frame (xref-find-definitions-other-frame).

M-x xref-find-definitions-at-mouse

Find definition of identifier at mouse click.

M-,

Go back to where you previously invoked M-. and friends (xref-go-back).

C-M-,

Go forward to where you previously invoked M-, (xref-go-forward).

M-x xref-etags-mode

Switch xref to use the etags backend.

M-. (xref-find-definitions) shows the definition of the identifier at point. With a prefix argument, or if there’s no identifier at point, it prompts for the identifier. (If you want it to always prompt, customize xref-prompt-for-identifier to t.)

When entering the identifier argument to M-., you can use the usual minibuffer completion commands (see Completion), with the known identifier names being the completion candidates.

It uses the current Xref backend, and will signal an error when there is none configured, with some recommendations.

Like most commands that can switch buffers, xref-find-definitions has a variant that displays the new buffer in another window (see How display-buffer works), and one that makes a new frame for it. The former is C-x 4 . (xref-find-definitions-other-window), and the latter is C-x 5 . (xref-find-definitions-other-frame).

The command xref-find-definitions-at-mouse works like xref-find-definitions, but it looks for the identifier name at or around the place of a mouse event. The xref-mouse-mode minor mode binds the command to C-mouse-1.

The command C-M-. (xref-find-apropos) is like apropos for tags (see Apropos). It displays a list of identifiers in the selected tags table whose names match the specified regexp. This is just like M-., except that it does regexp matching of identifiers instead of matching symbol names as fixed strings. By default, the command pops up the *xref* buffer, like M-., but you can display additional output by customizing the variable tags-apropos-additional-actions; see its documentation for details.

If any of the above commands finds more than one matching definition, it by default pops up the *xref* buffer showing the matching candidates and selects that buffer’s window. (C-M-. always pops up the *xref* buffer if it finds at least one match.) Each candidate is normally shown in that buffer as the name of a file and the matching identifier(s) in that file. In that buffer, you can select any of the candidates for display, and you have several additional commands, described in Commands Available in the *xref* Buffer. However, if the value of the variable xref-auto-jump-to-first-definition is move, Emacs automatically moves point to the first of these candidates in the *xref* buffer, so just typing RET will display the definition of that candidate. If the value of the variable is t or show, the first candidate is automatically shown in its own window; t also selects the window showing the first candidate’s definition, while show leaves the window of the *xfer* buffer selected. The default value is nil, which just shows the candidates in the *xref* buffer, but neither selects any of them nor shows their definition, until you select a candidate in the *xref* buffer.

If you switch away of the window showing the *xref* buffer which displays several candidates, you can move from one candidate to another using the commands M-g M-n (next-error) and M-g M-p (previous-error). See Compilation Mode.

To go back to places from where you’ve displayed the definition, use M-, (xref-go-back). It jumps back to the point of the last invocation of M-.. Thus you can find and examine the definition of something with M-. and then return to where you were with M-,. M-, allows you to retrace the steps you made forward in the history of places, all the way to the first place in history, where you first invoked M-., or to any place in-between.

If you previously went back too far with M-,, or want to re-examine a place from which you went back, you can use C-M-, (xref-go-forward) to go forward again. This is similar to using M-., except that you don’t need on each step to move point to the identifier whose definition you want to look up. C-M-, allows you to retrace all the steps you made back in the history of places, all the way to the last place in history, where you invoked M-,, or to any place in-between.

Some major modes install xref support facilities that might sometimes fail to find certain identifiers. For example, in Emacs Lisp mode (see Evaluating Emacs Lisp Expressions) M-. will by default find only functions and variables from Lisp packages which are loaded into the current Emacs session or are auto-loaded (see Autoload in The Emacs Lisp Reference Manual). If M-. fails to find some identifiers, you can try forcing xref to use the etags backend (see Find Identifier References). To this end, turn on the Xref Etags minor mode with M-x xref-etags-mode, then invoke M-. again. (For this to work, be sure to run etags to create the tags table in the directory tree of the source files, see Creating Tags Tables.)

Next: Searching and Replacing with Identifiers, Previous: Looking Up Identifiers, Up: Find Identifiers   [Contents][Index]

30.4.1.2 Commands Available in the *xref* Buffer ¶

The following commands are provided in the *xref* buffer by the special Xref mode:

RET

mouse-1

Display the reference on the current line (xref-goto-xref). With prefix argument, also bury the *xref* buffer.

mouse-2 ¶

The same as mouse-1, but make the window displaying the *xref* buffer the selected window (xref-select-and-show-xref).

n ¶

.

Move to the next reference and display it in the other window (xref-next-line).

N ¶

Move to the first reference of the next reference group and display it in the other window (xref-next-group).

p ¶

,

Move to the previous reference and display it in the other window (xref-prev-line).

P ¶

Move to the first reference of the previous reference group and display it in the other window (xref-prev-group).

C-o ¶

Display the reference on the current line in the other window (xref-show-location-at-point).

r pattern RET replacement RET

Perform interactive query-replace on references that match pattern (xref-query-replace-in-results), replacing the match with replacement. This command can only be used in *xref* buffers that show all the matches for an identifier in all the relevant files. See Searching and Replacing with Identifiers.

g ¶

Refresh the contents of the *xref* buffer (revert-buffer). See Reverting a Buffer.

M-, ¶

Quit the window showing the *xref* buffer, and then jump to the previous Xref stack location (xref-quit-and-pop-marker-stack).

q ¶

Quit the window showing the *xref* buffer (xref-quit).

In addition, the usual navigation commands, such as the arrow keys, C-n, and C-p are available for moving around the buffer without displaying the references.

Next: Identifier Inquiries, Previous: Commands Available in the *xref* Buffer, Up: Find Identifiers   [Contents][Index]

30.4.1.3 Searching and Replacing with Identifiers ¶

The commands in this section perform various search and replace operations either on identifiers themselves or on files that reference them.

M-?

Find all the references for the identifier at point.

r

M-x xref-query-replace-in-results RET replacement RET

C-u M-x xref-query-replace-in-results RET regexp RET replacement RET

Interactively replace regexp with replacement in the names of all the identifiers shown in the *xref* buffer.

M-x xref-find-references-and-replace RET from RET to RET

Interactively rename all instances of the identifier from to the new name to.

M-x tags-search RET regexp RET

Search for regexp through the files in the selected tags table.

M-x tags-query-replace RET regexp RET replacement RET

Perform a query-replace-regexp on each file in the selected tags table.

M-x fileloop-continue

Restart one of the last 2 commands above, from the current location of point.

M-? finds all the references for the identifier at point, prompting for the identifier as needed, with completion. Depending on the current backend (see Find Identifier References), the command may prompt even if it finds a valid identifier at point. When invoked with a prefix argument, it always prompts for the identifier. (If you want it to prompt always, customize the value of the variable xref-prompt-for-identifier to t; or set it to nil to prompt only if there’s no usable identifier at point.) The command then presents the *xref* buffer with all the references to the identifier, showing the file name and the line where the identifier is referenced. The Xref mode commands are available in this buffer, see Commands Available in the *xref* Buffer.

When invoked in a buffer whose major mode uses the etags backend, M-? searches files and buffers whose major mode matches that of the original buffer. It guesses that mode from file extensions, so if M-? seems to be skipping relevant buffers or files, try customizing either the variable semantic-symref-filepattern-alist (if your buffer’s major mode already has an entry in it), or auto-mode-alist (if not), thereby informing xref of the missing extensions (see Choosing File Modes).

If the value of the variable xref-auto-jump-to-first-xref is t, xref-find-references automatically jumps to the first result in the *xref* buffer and selects the window where that reference is displayed; you can select the other results with M-g M-n (next-error) and M-g M-p (previous-error) (see Compilation Mode). If the value is show, the first result is displayed, but the window showing the *xref* buffer is left selected. If the value is move, the first result is selected in the *xref* buffer, but is not displayed; you can then use RET to actually display the reference. The default value is nil, which just shows the results in the *xref* buffer, but doesn’t select any of them, and doesn’t display the reference itself.

r (xref-query-replace-in-results) reads a replacement string, just like ordinary M-x query-replace-regexp. It then renames the identifiers shown in the *xref* buffer in all the places in all the files where these identifiers are referenced, such that their new name is replacement. This is useful when you rename your identifiers as part of refactoring. This command should be invoked in the *xref* buffer generated by M-?. By default, the command replaces the entire name of each identifier with replacement, but if invoked with a prefix argument, the command prompts for a regexp to match identifier names, and replaces only the matches of that regexp in the names of the identifiers with replacement.

M-x xref-find-references-and-replace works similarly to xref-query-replace-in-results, but is more convenient when you want to rename a single identifier specified by its name from.

Typing e in the *xref* buffer makes the buffer writable and enters the Xref Edit mode. Similar to Occur Edit mode (see Other Search-and-Loop Commands), you can edit the matching lines reported by Xref backend and have those changes reflected in the buffer visiting the originating file. Type C-c C-c to leave the Xref Edit mode and return to the Xref mode.

M-x tags-search reads a regexp using the minibuffer, then searches for matches in all the files in the selected tags table, one file at a time. It displays the name of the file being searched so you can follow its progress. As soon as it finds an occurrence, tags-search returns. This command requires tags tables to be available (see Tags Tables).

Having found one match with tags-search, you probably want to find all the rest. M-x fileloop-continue resumes the tags-search, finding one more match. This searches the rest of the current buffer, followed by the remaining files of the tags table.

M-x tags-query-replace performs a single query-replace-regexp through all the files in the tags table. It reads a regexp to search for and a string to replace with, just like ordinary M-x query-replace-regexp. It searches much like M-x tags-search, but repeatedly, processing matches according to your input. See Query Replace, for more information on query replace.

You can control the case-sensitivity of tags search commands by customizing the value of the variable tags-case-fold-search. The default is to use the same setting as the value of case-fold-search (see Lax Matching During Searching).

It is possible to get through all the files in the tags table with a single invocation of M-x tags-query-replace. But often it is useful to exit temporarily, which you can do with any input event that has no special query replace meaning. You can resume the query replace subsequently by typing M-x fileloop-continue; this command resumes the last tags search or replace command that you did. For instance, to skip the rest of the current file, you can type M-> M-x fileloop-continue.

Note that the commands described above carry out much broader searches than the xref-find-definitions family. The xref-find-definitions commands search only for definitions of identifiers that match your string or regexp. The commands xref-find-references, tags-search, and tags-query-replace find every occurrence of the identifier or regexp, as ordinary search commands and replace commands do in the current buffer.

As an alternative to xref-find-references and tags-search, you can run grep as a subprocess and have Emacs show you the matching lines one by one. See Searching with Grep under Emacs.

Previous: Searching and Replacing with Identifiers, Up: Find Identifiers   [Contents][Index]

30.4.1.4 Identifier Inquiries ¶

C-M-i

M-TAB

Perform completion on the text around point, possibly using the selected tags table if one is loaded (completion-at-point).

M-x list-tags RET file RET

Display a list of the identifiers defined in the program file file.

C-M-. regexp RET

Display a list of all identifiers matching regexp (xref-find-apropos). See Looking Up Identifiers.

M-x tags-next-file

Visit files recorded in the selected tags table.

In most programming language modes, you can type C-M-i or M-TAB (completion-at-point) to complete the symbol at point. Some modes provide specialized completion for this command tailored to the mode; for those that don’t, if there is a tags table loaded, this command can use it to generate completion candidates. See Completion for Symbol Names.

M-x list-tags reads the name of one of the files covered by the selected tags table, with completion, and displays the list of tags defined in that file; it offers the current buffer’s file name as the default file whose tags to list. Do not include a directory as part of the file name unless the file name recorded in the tags table includes a directory. This command works only with the etags backend, and requires a tags table for the project to be available. See Tags Tables.

M-x tags-next-file visits files covered by the selected tags table. The first time it is called, it visits the first file covered by the table. Each subsequent call visits the next covered file, unless a prefix argument is supplied, in which case it returns to the first file. This command requires a tags table to be selected.

Next: Creating Tags Tables, Up: Tags Tables   [Contents][Index]

30.4.2.1 Source File Tag Syntax ¶

Here is how tag syntax is defined for the most popular languages:

• In C code, any C function or typedef is a tag, and so are definitions of struct, union and enum. #define macro definitions, #undef and enum constants are also tags, unless you specify ‘--no-defines’ when making the tags table. Similarly, global variables are tags, unless you specify ‘--no-globals’, and so are struct members, unless you specify ‘--no-members’. Use of ‘--no-globals’, ‘--no-defines’ and ‘--no-members’ can make the tags table file much smaller.

  You can tag function declarations and external variables in addition to function definitions by giving the ‘--declarations’ option to etags.

• In C++ code, in addition to all the tag constructs of C code, member functions are also recognized; member variables are also recognized, unless you use the ‘--no-members’ option. operator definitions have tag names like ‘operator+’. If you specify the ‘--class-qualify’ option, tags for variables and functions in classes are named ‘class::variable’ and ‘class::function’. By default, class methods and members are not class-qualified, which facilitates identifying their names in the sources more accurately.
• In Java code, tags include all the constructs recognized in C++, plus the interface, extends and implements constructs. Tags for variables and functions in classes are named ‘class.variable’ and ‘class.function’.
• In LaTeX documents, the arguments for \chapter, \section, \subsection, \subsubsection, \eqno, \label, \ref, \Ref, \footref, \cite, \bibitem, \part, \appendix, \entry, \index, \def, \edef, \gdef, \xdef, \newcommand, \renewcommand, \newenvironment, \renewenvironment, \DeclareRobustCommand, \newrobustcmd, \renewrobustcmd, \providecommand, \providerobustcmd, \NewDocumentCommand, \RenewDocumentCommand, \ProvideDocumentCommand, \DeclareDocumentCommand, \NewExpandableDocumentCommand, \RenewExpandableDocumentCommand, \ProvideExpandableDocumentCommand, \DeclareExpandableDocumentCommand, \NewDocumentEnvironment, \RenewDocumentEnvironment, \ProvideDocumentEnvironment, \DeclareDocumentEnvironment, \csdef, \csedef, \csgdef, \csxdef, \csletcs, \cslet, \letcs, \let, \cs_new_protected_nopar, \cs_new_protected, \cs_new_nopar, \cs_new_eq, \cs_new, \cs_set_protected_nopar, \cs_set_protected, \cs_set_nopar, \cs_set_eq, \cs_set, \cs_gset_protected_nopar, \cs_gset_protected, \cs_gset_nopar, \cs_gset_eq, \cs_gset, \cs_generate_from_arg_count, and \cs_generate_variant are tags. So too are the arguments of any starred variants of these commands.

  Other commands can make tags as well, if you specify them in the environment variable TEXTAGS before invoking etags. The value of this environment variable should be a colon-separated list of command names. For example,

  TEXTAGS="mycommand:myothercommand"
  export TEXTAGS
  

  specifies (using Bourne shell syntax) that the commands ‘\mycommand’ and ‘\myothercommand’ also define tags.

• In Lisp code, any function defined with defun, any variable defined with defvar or defconst, and in general the first argument of any expression that starts with ‘(def’ in column zero is a tag. As an exception, expressions of the form (defvar foo) are treated as declarations, and are only tagged if the ‘--declarations’ option is given.
• In Scheme code, tags include anything defined with def or with a construct whose name starts with ‘def’. They also include variables set with set! at top level in the file.

Several other languages are also supported:

• In Ada code, functions, procedures, packages, tasks and types are tags. Use the ‘--packages-only’ option to create tags for packages only.

  In Ada, the same name can be used for different kinds of entity (e.g., for a procedure and for a function). Also, for things like packages, procedures and functions, there is the spec (i.e., the interface) and the body (i.e., the implementation). To make it easier to pick the definition you want, Ada tag names have suffixes indicating the type of entity:

  ‘/b’

  package body.

  ‘/f’

  function.

  ‘/k’

  task.

  ‘/p’

  procedure.

  ‘/s’

  package spec.

  ‘/t’

  type.

  Thus, M-x find-tag RET bidule/b RET will go directly to the body of the package bidule, while M-x find-tag RET bidule RET will just search for any tag bidule.

• In assembler code, labels appearing at the start of a line, followed by a colon, are tags.
• In Bison or Yacc input files, each rule defines as a tag the nonterminal it constructs. The portions of the file that contain C code are parsed as C code.
• In Cobol code, tags are paragraph names; that is, any word starting in column 8 and followed by a period.
• In Erlang code, the tags are the functions, records and macros defined in the file.
• In Fortran code, functions, subroutines and block data are tags.
• In Go code, packages, functions, and types are tags.
• In HTML input files, the tags are the title and the h1, h2, h3 headers. Also, tags are name= in anchors and all occurrences of id=.
• In Lua input files, all functions are tags.
• In makefiles, targets are tags; additionally, variables are tags unless you specify ‘--no-globals’.
• In Objective C code, tags include Objective C definitions for classes, class categories, methods and protocols. Tags for variables and functions in classes are named ‘class::variable’ and ‘class::function’.
• In Pascal code, the tags are the functions and procedures defined in the file.
• In Perl code, the tags are the packages, subroutines and variables defined by the package, sub, use constant, my, and local keywords. Use ‘--globals’ if you want to tag global variables. Tags for subroutines are named ‘package::sub’. The name for subroutines defined in the default package is ‘main::sub’.
• In PHP code, tags are functions, classes and defines. Vars are tags too, unless you use the ‘--no-members’ option.
• In PostScript code, the tags are the functions.
• In Prolog code, tags are predicates and rules at the beginning of line.
• In Python code, def or class at the beginning of a line generate a tag.
• In Ruby code, def or class or module at the beginning of a line generate a tag. Constants also generate tags.
• In Rust code, tags anything defined with fn, enum, struct or macro_rules!.

You can also generate tags based on regexp matching (see Etags Regexps) to handle other formats and languages.

Next: Etags Regexps, Previous: Source File Tag Syntax, Up: Tags Tables   [Contents][Index]

30.4.2.2 Creating Tags Tables ¶

The etags program is used to create a tags table file. It knows the syntax of several languages, as described in Source File Tag Syntax. Here is how to run etags:

etags inputfiles...

The etags program reads the specified files, and writes a tags table named TAGS in the current working directory. You can optionally specify a different file name for the tags table by using the ‘--output=file’ option; specifying - as a file name prints the tags table to standard output. You can also append the newly created tags table to an existing file by using the ‘--append’ option.

If the specified files don’t exist, etags looks for compressed versions of them and uncompresses them to read them. Under MS-DOS, etags also looks for file names like mycode.cgz if it is given ‘mycode.c’ on the command line and mycode.c does not exist.

If the tags table becomes outdated due to changes in the files described in it, you can update it by running the etags program again. If the tags table does not record a tag, or records it for the wrong file, then Emacs will not be able to find that definition until you update the tags table. But if the position recorded in the tags table becomes a little bit wrong (due to other editing), Emacs will still be able to find the right position, with a slight delay.

Thus, there is no need to update the tags table after each edit. You should update a tags table when you define new tags that you want to have listed, or when you move tag definitions from one file to another, or when changes become substantial.

If the etags-regen-mode minor mode, described below, is enabled, Emacs will automatically keep the tags tables up-to-date as needed.

You can make a tags table include another tags table, by passing the ‘--include=file’ option to etags. It then covers all the files covered by the included tags file, as well as its own.

If you specify the source files with relative file names when you run etags, the tags file will contain file names relative to the directory where the tags file was initially written. This way, you can move an entire directory tree containing both the tags file and the source files, and the tags file will still refer correctly to the source files. If the tags file is - or is in the /dev directory, however, the file names are made relative to the current working directory. This is useful, for example, when writing the tags to the standard output.

When using a relative file name, it should not be a symbolic link pointing to a tags file in a different directory, because this would generally render the file names invalid.

If you specify absolute file names as arguments to etags, then the tags file will contain absolute file names. This way, the tags file will still refer to the same files even if you move it, as long as the source files remain in the same place. Absolute file names start with ‘/’, or with ‘device:/’ on MS-DOS and MS-Windows.

When you want to make a tags table from a great number of files, you may have problems listing them on the command line, because some systems have a limit on its length. You can circumvent this limit by telling etags to read the file names from its standard input, by typing a dash in place of the file names, like this:

find . -name "*.[chCH]" -print | etags -

etags recognizes the language used in an input file based on its file name and contents. It first tries to match the file’s name and extension to the ones commonly used with certain languages. Some languages have interpreters with known names (e.g., perl for Perl or pl for Prolog), so etags next looks for an interpreter specification of the form ‘#!interp’ on the first line of an input file, and matches that against known interpreters. If none of that works, or if you want to override the automatic detection of the language, you can specify the language explicitly with the ‘--language=name’ option. You can intermix these options with file names; each one applies to the file names that follow it. Specify ‘--language=auto’ to tell etags to resume guessing the language from the file names and file contents. Specify ‘--language=none’ to turn off language-specific processing entirely; then etags recognizes tags by regexp matching alone (see Etags Regexps). This comes in handy when an input file uses a language not yet supported by etags, and you want to avoid having etags fall back on Fortran and C as the default languages.

You can also prevent etags from falling back on Fortran and C if you specify the ‘--no-fallback-lang’ option. The option ‘--fallback-lang’ countermands that.

The option ‘--parse-stdin=file’ is mostly useful when calling etags from programs. It can be used (only once) in place of a file name on the command line. etags will read from standard input and mark the produced tags as belonging to the file file.

For C and C++, if the source files don’t observe the GNU Coding Standards’ convention if having braces (‘{’ and ‘}’) in column zero only for top-level definitions, like functions and struct definitions, we advise that you use the ‘--ignore-indentation’ option, to prevent etags from incorrectly interpreting closing braces in column zero.

‘etags --help’ outputs the list of the languages etags knows, and the file name rules for guessing the language. It also prints a list of all the available etags options, together with a short explanation. If followed by one or more ‘--language=lang’ options, it outputs detailed information about how tags are generated for lang.

By default, etags includes in the tags table it produces all the files it scans, including files where it found no tags at all. Specify ‘--no-empty-file-entries’ to prevent that; then files with no tags will not be mentioned in the tags table. However, note that commands which process files mentioned in the tags table, such as tags-search (see Searching and Replacing with Identifiers), will process files which were thus omitted from the tags table. The option ‘--empty-file-entries’ countermands that.

Instead of creating and updating the tags table by manually invoking etags, you can ask Emacs to do it for you automatically. The global minor mode etags-regen-mode, if enabled, generates tags tables automatically as needed, and takes care of updating them when you edit any of the source files that contribute tags. This mode uses the current project configuration (see Working with Projects) to determine which files to submit to etags for regenerating the tags table for the project. You can customize how this minor mode works using the following user options:

etags-regen-program ¶

The program to regenerate tags table; defaults to etags.

etags-regen-program-options ¶

Command-line options to pass to the program which regenerates tags tables.

etags-regen-ignores ¶

List of glob wildcard patterns which specify files to ignore when regenerating tags tables.

If you select a tags table manually, with M-x visit-tags-table (see Selecting a Tags Table), etags-regen-mode effectively disables itself: it will no longer automatically create and update tags tables, assuming that you prefer managing your tags tables manually. You can cancel this effect of using visit-tags-table by invoking the command tags-reset-tags-tables.

Previous: Creating Tags Tables, Up: Tags Tables   [Contents][Index]

30.4.2.3 Etags Regexps ¶

The ‘--regex’ option to etags allows tags to be recognized by regular expression matching. You can intermix this option with file names; each one applies to the source files that follow it. If you specify multiple ‘--regex’ options, all of them are used in parallel. The syntax is:

--regex=[{language}]/tagregexp/[nameregexp/]modifiers

The essential part of the option value is tagregexp, the regexp for matching tags. It is always used anchored, that is, it only matches at the beginning of a line. If you want to allow indented tags, use a regexp that matches initial whitespace; start it with ‘[ \t]*’.

In these regular expressions, ‘\’ quotes the next character, and all the C character escape sequences are supported: ‘\a’ for bell, ‘\b’ for back space, ‘\e’ for escape, ‘\f’ for formfeed, ‘\n’ for newline, ‘\r’ for carriage return, ‘\t’ for tab, and ‘\v’ for vertical tab. In addition, ‘\d’ stands for the DEL character. Otherwise, the regular expression syntax is the same as Emacs except that backslash escapes are the same as GNU grep (which means, for example, that shy groups are not supported), and ‘[:ascii:]’, ‘[:multibyte:]’, ‘[:nonascii:]’, ‘[:word:]’, and ‘[:unibyte:]’ are not supported.

Ideally, tagregexp should not match more characters than are needed to recognize what you want to tag. If the syntax requires you to write tagregexp so it matches more characters beyond the tag itself, you should add a nameregexp, to pick out just the tag. This will enable Emacs to find tags more accurately and to do completion on tag names more reliably. In nameregexp, it is frequently convenient to use “back references” (see Backslash in Regular Expressions) to parenthesized groupings ‘\( … \)’ in tagregexp. For example, ‘\1’ refers to the first such parenthesized grouping. You can find some examples of this below.

The modifiers are a sequence of zero or more characters that modify the way etags does the matching. A regexp with no modifiers is applied sequentially to each line of the input file, in a case-sensitive way. The modifiers and their meanings are:

‘i’

Ignore case when matching this regexp.

‘m’

Match this regular expression against the whole file, so that multi-line matches are possible.

‘s’

Match this regular expression against the whole file, and allow ‘.’ in tagregexp to match newlines.

The ‘-R’ option cancels all the regexps defined by preceding ‘--regex’ options. It too applies to the file names following it. Here’s an example:

etags --regex=/reg1/i voo.doo --regex=/reg2/m \
    bar.ber -R --lang=lisp los.er

Here etags chooses the parsing language for voo.doo and bar.ber according to their contents. etags also uses reg1 to recognize additional tags in voo.doo, and both reg1 and reg2 to recognize additional tags in bar.ber. reg1 is checked against each line of voo.doo and bar.ber, in a case-insensitive way, while reg2 is checked against the whole bar.ber file, permitting multi-line matches, in a case-sensitive way. etags uses only the Lisp tags rules, with no user-specified regexp matching, to recognize tags in los.er.

You can restrict a ‘--regex’ option to match only files of a given language by using the optional prefix {language}. (‘etags --help’ prints the list of languages recognized by etags.) This is particularly useful when storing many predefined regular expressions for etags in a file. The following example tags the DEFVAR macros in the Emacs source files, for the C language only:

--regex='{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/'

When you have complex regular expressions, you can store the list of them in a file. The following option syntax instructs etags to read two files of regular expressions. The regular expressions contained in the second file are matched without regard to case.

--regex=@case-sensitive-file --ignore-case-regex=@ignore-case-file

A regex file for etags contains one regular expression per line. Empty lines, and lines beginning with space or tab are ignored. When the first character in a line is ‘@’, etags assumes that the rest of the line is the name of another file of regular expressions; thus, one such file can include another file. All the other lines are taken to be regular expressions. If the first non-whitespace text on the line is ‘--’, that line is a comment.

For example, we can create a file called ‘emacs.tags’ with the following contents:

        -- This is for GNU Emacs C source files
{c}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/

and then use it like this:

etags --regex=@emacs.tags *.[ch] */*.[ch]

Here are some more examples. The regexps are quoted to protect them from shell interpretation.

• Tag Octave files:

  etags --language=none \
        --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \
        --regex='/###key \(.*\)/\1/' \
        --regex='/[ \t]*global[ \t].*/' \
        *.m
  

  Note that tags are not generated for scripts, so that you have to add a line by yourself of the form ‘###key scriptname’ if you want to jump to it.

• Tag Tcl files:

  etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl
  

• Tag VHDL files:

  etags --language=none \
    --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \
    --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\
    \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/'