Commit | Line | Data |
---|---|---|
8cf51b2c GM |
1 | @c This is part of the Emacs manual. |
2 | @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, | |
6ed161e1 | 3 | @c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 |
e5136377 | 4 | @c Free Software Foundation, Inc. |
8cf51b2c GM |
5 | @c See file emacs.texi for copying conditions. |
6 | @node Maintaining, Abbrevs, Building, Top | |
7 | @chapter Maintaining Large Programs | |
8 | ||
9 | This chapter describes Emacs features for maintaining large | |
05c5ad63 | 10 | programs. |
8cf51b2c GM |
11 | |
12 | @menu | |
05c5ad63 | 13 | * Version Control:: Using version control systems. |
8cf51b2c | 14 | * Change Log:: Maintaining a change history for your program. |
4d120d6a | 15 | * Tags:: Go directly to any function in your program in one |
8cf51b2c GM |
16 | command. Tags remembers which file it is in. |
17 | @ifnottex | |
18 | * Emerge:: A convenient way of merging two versions of a program. | |
19 | @end ifnottex | |
20 | @end menu | |
21 | ||
05c5ad63 CY |
22 | @node Version Control |
23 | @section Version Control | |
24 | @cindex version control | |
25 | ||
26 | A @dfn{version control system} is a package that can record multiple | |
27 | versions of a source file, storing information such as the creation | |
28 | time of each version, who created it, and a description of what was | |
29 | changed in that version. | |
30 | ||
31 | The Emacs version control interface is called VC. Its commands work | |
32 | with several different version control systems; currently, it supports | |
33 | GNU Arch, Bazaar, CVS, Git, Mercurial, Monotone, RCS, SCCS/CSSC, and | |
34 | Subversion. Of these, the GNU project distributes CVS, GNU Arch, RCS, | |
35 | and Bazaar. | |
36 | ||
37 | VC is enabled automatically whenever you visit a file that is | |
38 | governed by a version control system. To disable VC entirely, set the | |
39 | customizable variable @code{vc-handled-backends} to @code{nil} | |
40 | @iftex | |
41 | (@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). | |
42 | @end iftex | |
43 | @ifnottex | |
44 | (@pxref{Customizing VC}). | |
45 | @end ifnottex | |
46 | ||
47 | @menu | |
48 | * Introduction to VC:: How version control works in general. | |
49 | * VC Mode Line:: How the mode line shows version control status. | |
50 | * Basic VC Editing:: How to edit a file under version control. | |
51 | * Old Revisions:: Examining and comparing old versions. | |
52 | * Secondary VC Commands:: The commands used a little less frequently. | |
53 | * VC Directory Mode:: Listing files managed by version control. | |
54 | * Branches:: Multiple lines of development. | |
55 | @ifnottex | |
56 | * Remote Repositories:: Efficient access to remote CVS servers. | |
57 | * Revision Tags:: Symbolic names for revisions | |
58 | * Miscellaneous VC:: Various other commands and features of VC. | |
59 | * Customizing VC:: Variables that change VC's behavior. | |
60 | @end ifnottex | |
61 | @end menu | |
62 | ||
63 | @node Introduction to VC | |
64 | @subsection Introduction to Version Control | |
65 | ||
66 | VC allows you to use a version control system from within Emacs, | |
67 | integrating the version control operations smoothly with editing. | |
68 | Though VC cannot completely bridge the gaps between version control | |
69 | systems with widely differing capabilities, it does provide a uniform | |
70 | interface to many version control operations. Regardless of which | |
71 | version control system is in use, you will be able to do basic | |
72 | operations in much the same way. | |
73 | ||
74 | This section provides a general overview of version control, and | |
75 | describes the version control systems that VC supports. You can skip | |
76 | this section if you are already familiar with the version control system | |
77 | you want to use. | |
78 | ||
79 | @menu | |
80 | * Why Version Control?:: Understanding the problems it addresses | |
81 | * Version Control Systems:: Supported version control back-end systems. | |
82 | * VCS Concepts:: Words and concepts related to version control. | |
83 | * Types of Log File:: The VCS log in contrast to the ChangeLog. | |
84 | @end menu | |
85 | ||
86 | @node Why Version Control? | |
87 | @subsubsection Understanding the problems it addresses | |
88 | ||
89 | Version control systems provide you with three important | |
90 | capabilities: | |
91 | ||
92 | @itemize @bullet | |
93 | @item | |
94 | @dfn{Reversibility}: the ability to back up to a previous state if you | |
95 | discover that some modification you did was a mistake or a bad idea. | |
96 | ||
97 | @item | |
98 | @dfn{Concurrency}: the ability to have many people modifying the same | |
99 | collection of files knowing that conflicting modifications can be | |
100 | detected and resolved. | |
101 | ||
102 | @item | |
103 | @dfn{History}: the ability to attach historical data to your data, | |
104 | such as explanatory comments about the intention behind each change to | |
105 | it. Even for a programmer working solo, change histories are an | |
106 | important aid to memory; for a multi-person project, they are a | |
107 | vitally important form of communication among developers. | |
108 | @end itemize | |
109 | ||
110 | @node Version Control Systems | |
111 | @subsubsection Supported Version Control Systems | |
112 | ||
113 | @cindex back end (version control) | |
114 | VC currently works with many different version control systems or | |
115 | @dfn{back ends}: | |
116 | ||
117 | @itemize @bullet | |
118 | ||
119 | @cindex SCCS | |
120 | @item | |
121 | SCCS was the first version control system ever built, and was long ago | |
122 | superseded by more advanced ones. VC compensates for certain features | |
123 | missing in SCCS (e.g., tag names for releases) by implementing them | |
124 | itself. Other VC features, such as multiple branches, are simply | |
125 | unavailable. Since SCCS is non-free, we recommend avoiding it. | |
126 | ||
127 | @cindex CSSC | |
128 | @item | |
129 | CSSC is a free replacement for SCCS. You should use CSSC only if, for | |
130 | some reason, you cannot use a more recent and better-designed version | |
131 | control system. | |
132 | ||
133 | @cindex RCS | |
134 | @item | |
135 | RCS is the free version control system around which VC was initially | |
136 | built. Almost everything you can do with RCS can be done through VC. | |
137 | However, you cannot use RCS over the network, and it only works at the | |
138 | level of individual files rather than projects. | |
139 | ||
140 | @cindex CVS | |
141 | @item | |
142 | CVS is the free version control system that was, until recently (circa | |
143 | 2008), used by the majority of free software projects. Nowadays, it | |
144 | is slowly being superseded by newer systems. CVS allows concurrent | |
145 | multi-user development either locally or over the network. It lacks | |
146 | support for atomic commits or file moving/renaming. VC supports all | |
147 | basic editing operations under CVS. For some less common tasks, you | |
148 | still need to call CVS from the command line. Note also that before | |
149 | using CVS you must set up a repository, which is a subject too complex | |
150 | to treat here. | |
151 | ||
152 | @cindex SVN | |
153 | @cindex Subversion | |
154 | @item | |
155 | Subversion (SVN) is a free version control system designed to be | |
156 | similar to CVS but without its problems. It supports atomic commits | |
157 | of filesets, and versioning of directories, symbolic links, meta-data, | |
158 | renames, copies, and deletes. | |
159 | ||
160 | @cindex GNU Arch | |
161 | @cindex Arch | |
162 | @item | |
163 | GNU Arch is a version control system designed for distributed work. | |
164 | It differs in many ways from older systems like CVS and RCS. It | |
165 | provides different methods for interoperating between users, support | |
166 | for offline operations, and good branching and merging features. It | |
167 | also supports atomic commits of filesets and file moving/renaming. VC | |
168 | does not support all operations provided by GNU Arch, so you must | |
169 | sometimes invoke it from the command line. | |
170 | ||
171 | @cindex git | |
172 | @item | |
173 | Git is a distributed version control system invented by Linus Torvalds to support | |
a11d3737 | 174 | development of Linux (his kernel). It supports atomic commits of filesets and |
05c5ad63 CY |
175 | file moving/renaming. One significant feature of git is that it |
176 | largely abolishes the notion of a single centralized repository; | |
177 | instead, each working copy of a git project is its own repository and | |
178 | coordination is done through repository-sync operations. VC supports | |
179 | most git operations, with the exception of news merges and repository | |
180 | syncing; these must be done from the command line. | |
181 | ||
182 | @cindex hg | |
183 | @cindex Mercurial | |
184 | @item | |
185 | Mercurial (hg) is a distributed version control system broadly | |
186 | resembling GNU Arch and git, with atomic fileset commits and file | |
187 | moving/renaming. Like git, it is fully decentralized. VC supports | |
188 | most Mercurial commands, with the exception of repository sync | |
189 | operations; this needs to be done from the command line. | |
190 | ||
191 | @cindex bzr | |
192 | @cindex Bazaar | |
193 | @item | |
194 | Bazaar (bzr) is a distributed version control system that supports both | |
195 | repository-based and distributed versioning, with atomic fileset | |
196 | commits and file moving/renaming. VC supports most basic editing | |
197 | operations under Bazaar. | |
198 | @end itemize | |
199 | ||
200 | Previous versions of VC supported a version control system known as | |
201 | Meta-CVS. This support has been dropped because of limited interest | |
202 | from users and developers. | |
203 | ||
204 | @node VCS Concepts | |
205 | @subsubsection Concepts of Version Control | |
206 | ||
207 | @cindex repository | |
208 | @cindex registered file | |
209 | When a file is under version control, we say that it is | |
210 | @dfn{registered} in the version control system. The system has a | |
211 | @dfn{repository} which stores both the file's present state and its | |
212 | change history---enough to reconstruct the current version or any | |
213 | earlier version. The repository also contains other information, such | |
214 | as @dfn{log entries} that describe the changes made to each file. | |
215 | ||
216 | @cindex work file | |
217 | @cindex checking out files | |
218 | A file @dfn{checked out} of a repository is called the @dfn{work | |
219 | file}. You edit the work file and make changes in it, as you would | |
220 | with an ordinary file. After you are done with a set of changes, you | |
221 | @dfn{check in} or @dfn{commit} the file; this records the changes in | |
222 | the repository, along with a log entry for those changes. | |
223 | ||
224 | @cindex revision | |
225 | @cindex revision ID | |
226 | A copy of a file stored in a repository is called a @dfn{revision}. | |
227 | The history of a file is a sequence of revisions. Each revisions is | |
228 | named by a @dfn{revision ID}. The format of the revision ID depends | |
229 | on the version control system; in the simplest case, it is just an | |
230 | integer. | |
231 | ||
232 | To go beyond these basic concepts, you will need to understand three | |
a11d3737 | 233 | aspects in which version control systems differ. |
05c5ad63 CY |
234 | They can be locking-based or merging-based; they can be file-based or |
235 | changeset-based; and they can be centralized or decentralized. VC | |
a11d3737 | 236 | handles all these modes of operation, but it cannot hide the differences. |
05c5ad63 CY |
237 | |
238 | @cindex locking versus merging | |
239 | A version control system typically has some mechanism to coordinate | |
240 | between users who want to change the same file. There are two ways to | |
241 | do this: merging and locking. | |
242 | ||
243 | In a version control system that uses merging, each user may check | |
244 | out and modify a work file at any time. The system lets you | |
245 | @dfn{merge} your work file, which may contain changes that have not | |
246 | been checked in, with the latest changes that others have checked into | |
247 | the repository. | |
248 | ||
249 | Older version control systems use a @dfn{locking} scheme instead. | |
250 | Here, work files are normally read-only. To edit a file, you ask the | |
251 | version control system to make it writable for you by @dfn{locking} | |
252 | it; only one user can lock a given file at any given time. This | |
253 | procedure is analogous to, but different from, the locking that Emacs | |
254 | uses to detect simultaneous editing of ordinary files | |
255 | (@pxref{Interlocking}). When you check in your changes, that unlocks | |
256 | the file, and the work file becomes read-only again. Other users may | |
257 | then lock the file to make their own changes. | |
258 | ||
259 | Both locking and merging systems can have problems when multiple | |
260 | users try to modify the same file at the same time. Locking systems | |
261 | have @dfn{lock conflicts}; a user may try to check a file out and be | |
262 | unable to because it is locked. In merging systems, @dfn{merge | |
263 | conflicts} happen when you check in a change to a file that conflicts | |
264 | with a change checked in by someone else after your checkout. Both | |
265 | kinds of conflict have to be resolved by human judgment and | |
a11d3737 RS |
266 | communication. Experience has shown that merging is superior to |
267 | locking, both in convenience to developers and in minimizing the | |
268 | number and severity of conflicts that actually occur. | |
05c5ad63 CY |
269 | |
270 | SCCS always uses locking. RCS is lock-based by default but can be | |
271 | told to operate in a merging style. CVS and Subversion are | |
272 | merge-based by default but can be told to operate in a locking mode. | |
273 | Distributed version control systems, such as GNU Arch, git, and | |
a11d3737 | 274 | Mercurial, are exclusively merging-based. |
05c5ad63 | 275 | |
a11d3737 RS |
276 | VC mode supports both locking and merging version control. The |
277 | terms ``checkin'' and ``checkout'' come from locking-based version | |
278 | control systems; newer version control systems have slightly different | |
279 | operations usually called ``commit'' and ``update'', but VC hides the | |
280 | differences between them as much as possible. | |
05c5ad63 CY |
281 | |
282 | @cindex files versus changesets. | |
283 | On SCCS, RCS, CVS, and other early version control systems, version | |
284 | control operations are @dfn{file-based}: each file has its own comment | |
285 | and revision history separate from that of all other files in the | |
286 | system. Later systems, beginning with Subversion, are | |
287 | @dfn{changeset-based}: a checkin may include changes to several files, | |
288 | and the entire set of changes is treated as a unit by the system. Any | |
289 | comment associated with the change does not belong to a single file, | |
290 | but to the changeset itself. | |
291 | ||
292 | Changeset-based version control is more flexible and powerful than | |
293 | file-based version control; usually, when a change to multiple files | |
294 | has to be reversed, it's good to be able to easily identify and remove | |
a11d3737 | 295 | all of it. |
05c5ad63 CY |
296 | |
297 | @cindex centralized vs. decentralized version control | |
298 | Early version control systems were designed around a | |
299 | @dfn{centralized} model in which each project has only one repository | |
300 | used by all developers. SCCS, RCS, CVS, and Subversion share this | |
a11d3737 RS |
301 | kind of model. One of its drawbacks is that the repository is a choke |
302 | point for reliability and efficiency. | |
05c5ad63 | 303 | |
a11d3737 RS |
304 | GNU Arch pioneered the concept of @dfn{decentralized} version |
305 | control, later implemented in git, Mercurial, and Bazaar. A project | |
306 | may have several different repositories, and these systems support a | |
307 | sort of super-merge between repositories that tries to reconcile their | |
308 | change histories. At the limit, each developer has his/her own | |
309 | repository, and repository merges replace checkin/commit operations. | |
05c5ad63 CY |
310 | |
311 | VC's job is to help you manage the traffic between your personal | |
312 | workfiles and a repository. Whether that repository is a single | |
313 | master or one of a network of peer repositories is not something VC | |
314 | has to care about. Thus, the difference between a centralized and a | |
315 | decentralized version control system is invisible to VC mode. | |
316 | ||
317 | @node Types of Log File | |
318 | @subsubsection Types of Log File | |
319 | @cindex types of log file | |
320 | @cindex log File, types of | |
321 | @cindex version control log | |
322 | ||
323 | Projects that use a version control system can have two types of log | |
324 | for changes. One is the log maintained by the version control system: | |
325 | each time you check in a change, you fill out a @dfn{log entry} for | |
326 | the change (@pxref{Log Buffer}). This is called the @dfn{version | |
327 | control log}. | |
328 | ||
329 | The other kind of log is the file @file{ChangeLog} (@pxref{Change | |
330 | Log}). It provides a chronological record of all changes to a large | |
331 | portion of a program---typically one directory and its subdirectories. | |
332 | A small program would use one @file{ChangeLog} file; a large program | |
333 | may have a @file{ChangeLog} file in each major directory. | |
a11d3737 RS |
334 | @xref{Change Log}. Programmers have used change logs since long |
335 | before version control systems. | |
336 | ||
337 | Changeset-based version systems typically maintain a changeset-based | |
338 | modification log for the entire system, which makes change log files | |
339 | somewhat redundant. One advantage that they retain is that it is | |
340 | sometimes useful to be able to view the transaction history of a | |
341 | single directory separately from those of other directories. | |
05c5ad63 CY |
342 | |
343 | A project maintained with version control can use just the version | |
344 | control log, or it can use both kinds of logs. It can handle some | |
345 | files one way and some files the other way. Each project has its | |
346 | policy, which you should follow. | |
347 | ||
348 | When the policy is to use both, you typically want to write an entry | |
349 | for each change just once, then put it into both logs. You can write | |
350 | the entry in @file{ChangeLog}, then copy it to the log buffer with | |
351 | @kbd{C-c C-a} when checking in the change (@pxref{Log Buffer}). Or | |
352 | you can write the entry in the log buffer while checking in the | |
353 | change, and later use the @kbd{C-x v a} command to copy it to | |
354 | @file{ChangeLog} | |
355 | @iftex | |
356 | (@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}). | |
357 | @end iftex | |
358 | @ifnottex | |
359 | (@pxref{Change Logs and VC}). | |
360 | @end ifnottex | |
361 | ||
362 | @node VC Mode Line | |
363 | @subsection Version Control and the Mode Line | |
364 | ||
365 | When you visit a file that is under version control, Emacs indicates | |
366 | this on the mode line. For example, @samp{RCS-1.3} says that RCS is | |
367 | used for that file, and the current version is 1.3. | |
368 | ||
369 | The character between the back-end name and the revision ID | |
370 | indicates the version control status of the file. @samp{-} means that | |
371 | the work file is not locked (if locking is in use), or not modified (if | |
372 | locking is not in use). @samp{:} indicates that the file is locked, or | |
373 | that it is modified. If the file is locked by some other user (for | |
374 | instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}. | |
375 | ||
376 | On a graphical display, you can move the mouse over this mode line | |
377 | indicator to pop up a ``tool-tip'', which displays a more verbose | |
378 | description of the version control status. Pressing @kbd{Mouse-1} | |
379 | over the indicator pops up a menu of VC commands. This menu is | |
a11d3737 | 380 | identical to the @samp{Tools / Version Control} menu item. |
05c5ad63 CY |
381 | |
382 | @vindex auto-revert-check-vc-info | |
383 | When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is | |
384 | under version control, it updates the version control information in | |
385 | the mode line. However, Auto Revert mode may not properly update this | |
386 | information if the version control status changes without changes to | |
387 | the work file, from outside the current Emacs session. If you set | |
388 | @code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates | |
389 | the version control status information every | |
390 | @code{auto-revert-interval} seconds, even if the work file itself is | |
391 | unchanged. The resulting CPU usage depends on the version control | |
392 | system, but is usually not excessive. | |
393 | ||
394 | @node Basic VC Editing | |
395 | @subsection Basic Editing under Version Control | |
396 | ||
a11d3737 | 397 | @cindex filesets, VC |
05c5ad63 | 398 | Most VC commands operate on @dfn{VC filesets}. A VC fileset is a |
a11d3737 RS |
399 | collection of one or more files that a VC operation acts on. When you |
400 | type VC commands in a buffer visiting a version-controlled file, the | |
401 | VC fileset is simply that one file. When you type them in a VC | |
402 | Directory buffer, and some files in it are marked, the VC fileset | |
05c5ad63 CY |
403 | consists of the marked files (@pxref{VC Directory Mode}). |
404 | ||
405 | The principal VC command is an all-purpose command, @kbd{C-x v v} | |
406 | (@code{vc-next-action}), that performs either locking, merging or a | |
a11d3737 RS |
407 | check-in (depending on the situation) on the current VC fileset. You |
408 | can use @kbd{C-x v v} in a file-visiting buffer or in a VC Directory | |
409 | buffer. | |
05c5ad63 CY |
410 | |
411 | @table @kbd | |
412 | @itemx C-x v v | |
a11d3737 | 413 | Perform the appropriate next version control operation on the VC fileset. |
05c5ad63 CY |
414 | @end table |
415 | ||
416 | @findex vc-next-action | |
417 | @kindex C-x v v | |
418 | The precise action of @kbd{C-x v v} depends on the state of the VC | |
419 | fileset, and whether the version control system uses locking or | |
420 | merging. This is described in detail in the subsequent sections. | |
421 | ||
422 | VC filesets are the way that VC mode bridges the gap between | |
423 | file-based and changeset-based version control systems. They are, | |
424 | essentially, a way to pass multiple file arguments as a group to | |
425 | version control commands. For example, on Subversion, a checkin with | |
426 | a multi-file VC fileset becomes a joint commit, as though you had | |
427 | typed @command{svn commit} with those file arguments at the shell | |
428 | command line. All files in a VC fileset must be under the same | |
429 | version control system; if they are not, Emacs signals an error when | |
430 | you attempt to execute a command on the fileset. | |
431 | ||
a11d3737 RS |
432 | Support for VC filesets and changeset-based version control systems |
433 | is the main improvement to VC in Emacs 23. When you mark multi-file | |
434 | VC in a VC Directory buffer, VC operations treat them as a VC fileset, | |
435 | and operate on them all at once if the version control system is | |
f42c443c | 436 | changeset-based. @xref{VC Directory Mode}. |
05c5ad63 CY |
437 | |
438 | VC filesets are distinct from the ``named filesets'' used for | |
439 | viewing and visiting files in functional groups (@pxref{Filesets}). | |
440 | Unlike named filesets, VC filesets are not named and don't persist | |
441 | across sessions. | |
442 | ||
443 | @menu | |
444 | * VC With A Merging VCS:: Without locking: default mode for CVS. | |
445 | * VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS. | |
446 | * Advanced C-x v v:: Advanced features available with a prefix argument. | |
447 | * Log Buffer:: Features available in log entry buffers. | |
448 | @end menu | |
449 | ||
450 | @node VC With A Merging VCS | |
451 | @subsubsection Basic Version Control with Merging | |
452 | ||
453 | When your version control system is merging-based (the default for | |
454 | CVS and all newer version control systems), work files are always | |
455 | writable; you need not do anything special to begin editing a file. | |
456 | The status indicator on the mode line is @samp{-} if the file is | |
457 | unmodified; it flips to @samp{:} as soon as you save any changes | |
458 | (@pxref{VC Mode Line}). | |
459 | ||
460 | Here is what @kbd{C-x v v} does when using a merging-based system: | |
461 | ||
462 | @itemize @bullet | |
463 | @item | |
464 | If the work file is the same as in the repository, it does nothing. | |
465 | ||
466 | @item | |
467 | If you have not changed the work file, but some other user has checked | |
468 | in changes to the repository, @kbd{C-x v v} merges those changes into | |
469 | the work file. | |
470 | ||
471 | @item | |
472 | If you have made modifications to the work file, @kbd{C-x v v} | |
473 | attempts to check in your changes. To do this, Emacs first reads the | |
474 | log entry for the new revision (@pxref{Log Buffer}). If some other | |
475 | user has checked in changes to the repository since you last checked | |
476 | it out, the checkin fails. In that case, type @kbd{C-x v v} again to | |
477 | merge those changes into your own work file; this puts the work file | |
478 | into a ``conflicted'' state. Type @kbd{C-x v v} to clear the | |
479 | ``conflicted'' state; VC then regards the file as up-to-date and | |
480 | modified, and you can try to check it in again. | |
481 | ||
482 | To pick up any recent changes from the repository @emph{without} | |
483 | trying to commit your own changes, type @kbd{C-x v m @key{RET}}. | |
484 | @xref{Merging}. | |
485 | @end itemize | |
486 | ||
487 | These rules also apply when you use RCS in its ``non-locking'' mode, | |
488 | except that changes will not be automatically merged from the | |
489 | repository. Nothing informs you if another user has checked in | |
490 | changes in the same file since you began editing it; when you check in | |
491 | your revision, his changes are removed (however, they remain in the | |
492 | repository and are thus not irrevocably lost). Therefore, you must | |
493 | verify that the current revision is unchanged before checking in your | |
494 | changes. In addition, locking is possible with RCS even in this mode: | |
495 | @kbd{C-x v v} with an unmodified file locks the file, just as it does | |
496 | with RCS in its normal locking mode (@pxref{VC With A Locking VCS}). | |
497 | ||
498 | @node VC With A Locking VCS | |
499 | @subsubsection Basic Version Control with Locking | |
500 | ||
501 | Under a locking-based version control system (such as SCCS, and RCS | |
502 | in its default mode), @kbd{C-x v v} does the following: | |
503 | ||
504 | @itemize @bullet | |
505 | @item | |
506 | If the file is not locked, @kbd{C-x v v} locks it, and makes it | |
507 | writable so that you can change it. | |
508 | ||
509 | @item | |
510 | If the file is locked by you, and contains changes, @kbd{C-x v v} | |
511 | checks in the changes. In order to do this, it first reads the log | |
512 | entry for the new revision. @xref{Log Buffer}. | |
513 | ||
514 | @item | |
515 | If the file is locked by you, but you have not changed it since you | |
516 | locked it, @kbd{C-x v v} releases the lock and makes the file | |
517 | read-only again. | |
518 | ||
519 | @item | |
520 | If the file is locked by some other user, @kbd{C-x v v} asks you whether | |
521 | you want to ``steal the lock'' from that user. If you say yes, the file | |
522 | becomes locked by you, but a message is sent to the person who had | |
523 | formerly locked the file, to inform him of what has happened. | |
524 | @end itemize | |
525 | ||
526 | These rules also apply when you use CVS in locking mode, except | |
527 | that there is no such thing as stealing a lock. | |
528 | ||
529 | @node Advanced C-x v v | |
530 | @subsubsection Advanced Control in @kbd{C-x v v} | |
531 | ||
532 | @cindex revision ID to check in/out | |
533 | When you give a prefix argument to @code{vc-next-action} (@kbd{C-u | |
534 | C-x v v}), it still performs the next logical version control | |
535 | operation, but accepts additional arguments to specify precisely how | |
536 | to do the operation. | |
537 | ||
538 | @itemize @bullet | |
539 | @item | |
540 | If the file is modified (or locked), you can specify the revision ID | |
541 | to use for the new version that you check in. This is one way | |
542 | to create a new branch (@pxref{Branches}). | |
543 | ||
544 | @item | |
545 | If the file is not modified (and unlocked), you can specify the | |
546 | revision to select; this lets you start working from an older | |
547 | revision, or on another branch. If you do not enter any revision, | |
548 | that takes you to the highest (``head'') revision on the current | |
549 | branch; therefore @kbd{C-u C-x v v @key{RET}} is a convenient way to | |
550 | get the latest version of a file from the repository. | |
551 | ||
552 | @item | |
553 | @cindex specific version control system | |
554 | Instead of the revision ID, you can also specify the name of a | |
555 | version control system. This is useful when one file is being managed | |
556 | with two version control systems at the same time | |
557 | @iftex | |
558 | (@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs | |
559 | Features}). | |
560 | @end iftex | |
561 | @ifnottex | |
562 | (@pxref{Local Version Control}). | |
563 | @end ifnottex | |
564 | ||
565 | @end itemize | |
566 | ||
567 | @node Log Buffer | |
568 | @subsubsection Features of the Log Entry Buffer | |
569 | ||
570 | When you check in changes, Emacs pops up a buffer called | |
571 | @samp{*VC-Log*} for you to enter a log entry. | |
572 | ||
573 | After you have finished editing the log message, type @kbd{C-c C-c} | |
574 | to exit the buffer and commit the change. | |
575 | ||
576 | @findex log-edit-show-files | |
577 | @findex log-edit-show-diff | |
578 | In the @samp{*VC-Log*} buffer, typing @kbd{C-c C-f} | |
579 | (@code{log-edit-show-files}) displays a list of files in the VC | |
580 | fileset you are committing. If you called @kbd{C-x v v} directly from | |
581 | a work file, the VC fileset consists of that single file, so this | |
582 | command is not very useful. If you called @kbd{C-x v v} from a VC | |
583 | directory buffer, the VC fileset may consist of multiple files | |
584 | (@pxref{VC Directory Mode}). | |
585 | ||
586 | @findex log-edit-insert-changelog | |
587 | Type @kbd{C-c C-d} (@code{log-edit-show-diff}) to show a ``diff'' of | |
588 | the changes you have made (i.e., the differences between the work file | |
589 | and the repository revision from which you started editing the file). | |
590 | The diff is displayed in a special buffer in another window. | |
591 | @xref{Comparing Files}. | |
592 | ||
593 | If you have written an entry in the @file{ChangeLog} (@pxref{Change | |
594 | Log}), type @kbd{C-c C-a} (@code{log-edit-insert-changelog}) to pull | |
595 | it into the @samp{*VC-Log*} buffer. If the topmost item in the | |
596 | @file{ChangeLog} was made under your user name on the current date, | |
597 | this command searches that item for entries that match the file(s) to | |
598 | be committed; if found, these entries are inserted. | |
599 | @iftex | |
600 | @xref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}, | |
601 | @end iftex | |
602 | @ifnottex | |
603 | @xref{Change Logs and VC}, | |
604 | @end ifnottex | |
605 | for the opposite way of working---generating ChangeLog entries from | |
606 | the revision control log. | |
607 | ||
608 | To abort a check-in, just @strong{don't} type @kbd{C-c C-c} in that | |
609 | buffer. You can switch buffers and do other editing. As long as you | |
610 | don't try to check in another file, the entry you were editing remains | |
611 | in the @samp{*VC-Log*} buffer, and you can go back to that buffer at | |
612 | any time to complete the check-in. | |
613 | ||
614 | If you change several source files for the same reason, it is often | |
615 | convenient to specify the same log entry for many of the files. (This | |
616 | is the normal way to do things on a changeset-oriented system, where | |
617 | comments are attached to changesets rather than the history of | |
618 | individual files.) The most convenient way to do this is to mark all | |
619 | the files in VC Directory Mode and check in from there; the log buffer | |
620 | will carry the fileset information with it and do a group commit when | |
621 | you type @kbd{C-c C-c}. | |
622 | ||
623 | You can also browse the history of previous log entries to duplicate | |
624 | a checkin comment. This can be useful when you want several files to | |
625 | have checkin comments that vary only slightly from each other. The | |
626 | commands @kbd{M-n}, @kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this | |
627 | work just like the minibuffer history commands (except that these | |
628 | versions are used outside the minibuffer). | |
629 | ||
630 | @vindex vc-log-mode-hook | |
631 | Each time you check in a change, the log entry buffer is put into VC | |
632 | Log Edit mode, which involves running two hooks: @code{text-mode-hook} | |
633 | and @code{vc-log-mode-hook}. @xref{Hooks}. | |
634 | ||
635 | @node Old Revisions | |
636 | @subsection Examining And Comparing Old Revisions | |
637 | ||
638 | One of the convenient features of version control is the ability | |
639 | to examine any revision of a file, or compare two revisions. | |
640 | ||
641 | @table @kbd | |
642 | @item C-x v ~ @var{revision} @key{RET} | |
643 | Examine revision @var{revision} of the visited file, in a buffer of its | |
644 | own. | |
645 | ||
646 | @item C-x v = | |
647 | Compare the buffer contents associated with the current | |
648 | fileset with the working revision(s) from which you started editing. | |
649 | ||
650 | @item C-u C-x v = @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET} | |
651 | Compare the specified two repository revisions of the current fileset. | |
652 | ||
653 | @item C-x v g | |
654 | Display an annotated version of the file: for each line, show the | |
655 | latest revision in which it was modified. | |
656 | @end table | |
657 | ||
658 | @findex vc-revision-other-window | |
659 | @kindex C-x v ~ | |
660 | To examine an old revision, visit the work file and type @kbd{C-x v | |
661 | ~ @var{revision} @key{RET}} (@code{vc-revision-other-window}). Here, | |
662 | @var{revision} is either the desired revision ID (@pxref{VCS | |
663 | Concepts}), or the name of a tag or branch | |
664 | @iftex | |
665 | (@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}). | |
666 | @end iftex | |
667 | @ifnottex | |
668 | (@pxref{Tags}). | |
669 | @end ifnottex | |
670 | This command puts the text of the old revision in a file named | |
671 | @file{@var{filename}.~@var{revision}~}, and visits it in its own | |
672 | buffer in a separate window. | |
673 | ||
674 | @findex vc-diff | |
675 | @kindex C-x v = | |
676 | @kbd{C-x v =} (@code{vc-diff}) compares the current buffer contents | |
677 | of each file in the current VC fileset (saving them if necessary) with | |
678 | the repository revision from which you started editing. Note that the | |
679 | latter may or may not be the latest revision of the file(s). The diff | |
680 | is displayed in a special buffer in another window. @xref{Comparing | |
681 | Files}. | |
682 | ||
683 | @findex vc-diff | |
684 | @kindex C-u C-x v = | |
685 | To compare two arbitrary revisions of the current VC fileset, call | |
686 | @code{vc-diff} with a prefix argument: @kbd{C-u C-x v =}. This | |
687 | prompts for two revision IDs, using the minibuffer, and displays the | |
688 | diff in a special buffer in another window. Instead of providing a | |
689 | revision ID, you can give an empty input, which specifies the current | |
690 | contents of the work file; or a tag or branch name | |
691 | @iftex | |
692 | (@pxref{Tags,,,emacs-xtra, Specialized Emacs Features}). | |
693 | @end iftex | |
694 | @ifnottex | |
695 | (@pxref{Tags}). | |
696 | @end ifnottex | |
697 | If your version control system is file-based (e.g. CVS) rather than | |
698 | changeset-based (Subversion, GNU Arch, git, Mercurial), supplying a | |
699 | revision ID for a multi-file fileset (as opposed to a symbolic tag | |
700 | name) is unlikely to return diffs that are connected in any meaningful | |
701 | way. | |
702 | ||
703 | If you invoke @kbd{C-x v =} or @kbd{C-u C-x v =} from a buffer that | |
704 | is neither visiting a version-controlled file nor a VC directory | |
705 | buffer, these commands generate a diff of all registered files in the | |
706 | current directory and its subdirectories. | |
707 | ||
708 | @vindex vc-diff-switches | |
709 | @vindex vc-rcs-diff-switches | |
710 | @kbd{C-x v =} works by running a variant of the @code{diff} utility | |
a9253a1e GM |
711 | designed to work with the version control system in use. The options |
712 | to pass to the @code{diff} command are taken from the first non-@code{nil} | |
713 | value of @code{vc-@var{backend}-diff-switches}, @code{vc-diff-switches}, | |
714 | and @code{diff-switches} (@pxref{Comparing Files}), in that order. | |
715 | Since @code{nil} means to check the next variable in the sequence, | |
716 | either of the first two may use the value @code{t} to mean no switches at all. | |
e5136377 GM |
717 | Most of the @samp{vc@dots{}diff-switches} variables default to |
718 | @code{nil}, but some default to @code{t}. These are for those version | |
719 | control systems (e.g. SVN) whose @code{diff} implementations do not | |
720 | accept common options (e.g. @samp{-c}) likely to be in | |
721 | @code{diff-switches}. | |
05c5ad63 CY |
722 | |
723 | The buffer produced by @kbd{C-x v =} supports the commands of | |
724 | Compilation mode (@pxref{Compilation Mode}), such as @kbd{C-x `} and | |
725 | @kbd{C-c C-c}, in both the ``old'' and ``new'' text, and they always | |
726 | find the corresponding locations in the current work file. (Older | |
727 | revisions are not, in general, present as files on your disk.) | |
728 | ||
729 | @findex vc-annotate | |
730 | @kindex C-x v g | |
731 | For some back ends, you can display the file @dfn{annotated} with | |
732 | per-line revision information, by typing @kbd{C-x v g} | |
733 | (@code{vc-annotate}). This creates a new buffer (the ``annotate | |
734 | buffer'') displaying the file's text, with each part colored to show | |
735 | how old it is. Text colored red is new, blue means old, and | |
736 | intermediate colors indicate intermediate ages. By default, the color | |
737 | is scaled over the full range of ages, such that the oldest changes | |
738 | are blue, and the newest changes are red. | |
739 | ||
740 | When you give a prefix argument to this command, Emacs reads two | |
741 | arguments using the minibuffer: the ID of which revision to display and | |
742 | annotate (instead of the current file contents), and the time span in | |
743 | days the color range should cover. | |
744 | ||
745 | From the annotate buffer, these and other color scaling options are | |
746 | available from the @samp{VC-Annotate} menu. In this buffer, you can | |
747 | also use the following keys to browse the annotations of past revisions, | |
748 | view diffs, or view log entries: | |
749 | ||
750 | @table @kbd | |
751 | @item p | |
752 | Annotate the previous revision, that is to say, the revision before | |
753 | the one currently annotated. A numeric prefix argument is a repeat | |
754 | count, so @kbd{C-u 10 p} would take you back 10 revisions. | |
755 | ||
756 | @item n | |
757 | Annotate the next revision---the one after the revision currently | |
758 | annotated. A numeric prefix argument is a repeat count. | |
759 | ||
760 | @item j | |
761 | Annotate the revision indicated by the current line. | |
762 | ||
763 | @item a | |
764 | Annotate the revision before the one indicated by the current line. | |
765 | This is useful to see the state the file was in before the change on | |
766 | the current line was made. | |
767 | ||
768 | @item f | |
769 | Show in a buffer the file revision indicated by the current line. | |
770 | ||
771 | @item d | |
772 | Display the diff between the current line's revision and the previous | |
773 | revision. This is useful to see what the current line's revision | |
774 | actually changed in the file. | |
775 | ||
776 | @item D | |
777 | Display the diff between the current line's revision and the previous | |
778 | revision for all files in the changeset (for VC systems that support | |
779 | changesets). This is useful to see what the current line's revision | |
780 | actually changed in the tree. | |
781 | ||
782 | @item l | |
783 | Show the log of the current line's revision. This is useful to see | |
784 | the author's description of the changes in the revision on the current | |
785 | line. | |
786 | ||
787 | @item w | |
788 | Annotate the working revision--the one you are editing. If you used | |
789 | @kbd{p} and @kbd{n} to browse to other revisions, use this key to | |
790 | return to your working revision. | |
791 | ||
792 | @item v | |
793 | Toggle the annotation visibility. This is useful for looking just at | |
794 | the file contents without distraction from the annotations. | |
795 | @end table | |
796 | ||
797 | @node Secondary VC Commands | |
798 | @subsection The Secondary Commands of VC | |
799 | ||
800 | This section explains the secondary commands of VC. | |
801 | ||
802 | @menu | |
803 | * Registering:: Putting a file under version control. | |
804 | * VC Status:: Viewing the VC status of files. | |
805 | * VC Undo:: Canceling changes before or after check-in. | |
806 | @end menu | |
807 | ||
808 | @node Registering | |
809 | @subsubsection Registering a File for Version Control | |
810 | ||
811 | @kindex C-x v i | |
812 | @findex vc-register | |
813 | You can put any file under version control by simply visiting it, and | |
814 | then typing @w{@kbd{C-x v i}} (@code{vc-register}). | |
815 | ||
816 | @table @kbd | |
817 | @item C-x v i | |
818 | Register the visited file for version control. | |
819 | @end table | |
820 | ||
821 | To register the file, Emacs must choose which version control system | |
822 | to use for it. If the file's directory already contains files | |
823 | registered in a version control system, Emacs uses that system. If | |
824 | there is more than one system in use for a directory, Emacs uses the | |
825 | one that appears first in @code{vc-handled-backends} | |
826 | @iftex | |
827 | (@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). | |
828 | @end iftex | |
829 | @ifnottex | |
830 | (@pxref{Customizing VC}). | |
831 | @end ifnottex | |
832 | On the other hand, if there are no files already registered, Emacs uses | |
833 | the first system from @code{vc-handled-backends} that could register | |
834 | the file (for example, you cannot register a file under CVS if its | |
835 | directory is not already part of a CVS tree); with the default value | |
836 | of @code{vc-handled-backends}, this means that Emacs uses RCS in this | |
837 | situation. | |
838 | ||
839 | If locking is in use, @kbd{C-x v i} leaves the file unlocked and | |
840 | read-only. Type @kbd{C-x v v} if you wish to start editing it. After | |
841 | registering a file with CVS, you must subsequently commit the initial | |
842 | revision by typing @kbd{C-x v v}. Until you do that, the revision ID | |
843 | appears as @samp{@@@@} in the mode line. | |
844 | ||
845 | @vindex vc-default-init-revision | |
846 | @cindex initial revision ID to register | |
847 | The default initial revision ID for a newly registered file | |
848 | varies by what VCS you are using; normally it will be 1.1 on VCSes | |
849 | that use dot-pair revision IDs and 1 on VCSes that use monotonic IDs. | |
850 | You can specify a different default by setting the variable | |
851 | @code{vc-default-init-revision}, or you can give @kbd{C-x v i} a | |
852 | numeric argument; then it reads the initial revision ID for this | |
853 | particular file using the minibuffer. | |
854 | ||
855 | @vindex vc-initial-comment | |
856 | If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an | |
857 | initial comment to describe the purpose of this source file. Reading | |
858 | the initial comment works like reading a log entry (@pxref{Log Buffer}). | |
859 | ||
860 | @node VC Status | |
861 | @subsubsection VC Status Commands | |
862 | ||
863 | @table @kbd | |
864 | @item C-x v l | |
865 | Display revision control state and change history. | |
866 | @end table | |
867 | ||
868 | @kindex C-x v l | |
869 | @findex vc-print-log | |
870 | To view the detailed revision control status and history of a file, | |
871 | type @kbd{C-x v l} (@code{vc-print-log}). This pops up a special | |
872 | buffer named @samp{*vc-change-log*}, in a new window, that displays | |
873 | the history of changes to the current file, including the text of the | |
874 | log entries. The point is centered at the revision of the file that | |
875 | is currently being visited. | |
876 | ||
877 | In the @samp{*vc-change-log*} buffer, you can use the following keys | |
878 | to move between the logs of revisions and of files, to view past | |
879 | revisions, to modify change comments, to view annotations and to view | |
880 | diffs: | |
881 | ||
882 | @table @kbd | |
883 | @item p | |
884 | Move to the previous revision-item in the buffer. (Revision entries in the log | |
885 | buffer are usually in reverse-chronological order, so the previous | |
886 | revision-item usually corresponds to a newer revision.) A numeric | |
887 | prefix argument is a repeat count. | |
888 | ||
889 | @item n | |
890 | Move to the next revision-item (which most often corresponds to the | |
891 | previous revision of the file). A numeric prefix argument is a repeat | |
892 | count. | |
893 | ||
894 | @item P | |
895 | Move to the log of the previous file, when the logs of multiple files | |
896 | are in the log buffer (@pxref{VC Directory Mode}). Otherwise, just | |
897 | move to the beginning of the log. A numeric prefix argument is a | |
898 | repeat count, so @kbd{C-u 10 P} would move backward 10 files. | |
899 | ||
900 | @item N | |
901 | Move to the log of the next file, when the logs of multiple files are | |
902 | in the log buffer (@pxref{VC Directory Mode}). It also takes a | |
903 | numeric prefix argument as a repeat count. | |
904 | ||
905 | @item a | |
906 | Annotate the revision indicated by the current line. | |
907 | ||
908 | @item e | |
909 | Modify the change comment displayed at point. Note that not all VC | |
910 | systems support modifying change comments. | |
911 | ||
912 | @item f | |
913 | Visit the revision indicated at the current line, like typing @kbd{C-x | |
914 | v ~} and specifying this revision's ID (@pxref{Old Revisions}). | |
915 | ||
916 | @item d | |
917 | Display the diff (@pxref{Comparing Files}) between the revision | |
918 | indicated at the current line and the next earlier revision. This is | |
919 | useful to see what actually changed in the file when the revision | |
920 | indicated on the current line was committed. | |
921 | ||
922 | @item D | |
923 | Display the changeset diff (@pxref{Comparing Files}) between the | |
924 | revision indicated at the current line and the next earlier revision. | |
925 | This is useful to see all the changes to all files that the revision | |
926 | indicated on the current line did when it was committed. | |
927 | @end table | |
928 | ||
929 | @node VC Undo | |
930 | @subsubsection Undoing Version Control Actions | |
931 | ||
932 | @table @kbd | |
933 | @item C-x v u | |
934 | Revert the buffer and the file to the working revision from which you started | |
935 | editing the file. | |
936 | ||
937 | @item C-x v c | |
938 | Remove the last-entered change from the master for the visited file. | |
939 | This undoes your last check-in. | |
940 | @end table | |
941 | ||
942 | @kindex C-x v u | |
943 | @findex vc-revert-buffer | |
944 | If you want to discard your current set of changes and revert to the | |
945 | working revision from which you started editing the file, use @kbd{C-x | |
946 | v u} (@code{vc-revert-buffer}). If the version control system is | |
947 | locking-based, this leaves the file unlocked, and you must lock it | |
948 | again before making new changes. @kbd{C-x v u} requires confirmation, | |
949 | unless it sees that you haven't made any changes with respect to the | |
950 | master copy of the working revision. | |
951 | ||
952 | @kbd{C-x v u} is also the command to unlock a file if you lock it and | |
953 | then decide not to change it. | |
954 | ||
955 | @kindex C-x v c | |
956 | @findex vc-rollback | |
957 | To cancel a change that you already checked in, use @kbd{C-x v c} | |
958 | (@code{vc-rollback}). This command discards all record of the most | |
959 | recent checked-in revision, but only if your work file corresponds to | |
960 | that revision---you cannot use @kbd{C-x v c} to cancel a revision that | |
961 | is not the latest on its branch. Note that many version control | |
962 | systems do not support rollback at all; this command is something of a | |
963 | historical relic. | |
964 | ||
965 | @node VC Directory Mode | |
966 | @subsection VC Directory Mode | |
967 | ||
968 | @kindex C-x v d | |
969 | @findex vc-dir | |
970 | When you are working on a large program, it is often useful to find | |
971 | out which files have changed within an entire directory tree, or to | |
972 | view the status of all files under version control at once, and to | |
973 | perform version control operations on collections of files. You can | |
974 | use the command @kbd{C-x v d} (@code{vc-dir}) to make a directory | |
975 | listing that includes only files relevant for version control. This | |
976 | creates a @dfn{VC Directory buffer} and displays it in a separate | |
977 | window. | |
978 | ||
979 | @cindex PCL-CVS | |
980 | @pindex cvs | |
981 | @cindex CVS directory mode | |
a11d3737 RS |
982 | The VC Directory buffer works with all the version control systems |
983 | that VC supports. For CVS, Emacs also offers a more powerful facility | |
984 | called PCL-CVS. @xref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The | |
985 | Emacs Front-End to CVS}. | |
986 | ||
987 | @menu | |
988 | * Buffer: VC Directory Buffer. What the buffer looks like and means. | |
989 | * Commands: VC Directory Commands. Commands to use in a VC directory buffer. | |
990 | @end menu | |
991 | ||
992 | @node VC Directory Buffer | |
993 | @subsubsection The VC Directory Buffer | |
05c5ad63 CY |
994 | |
995 | The VC Directory buffer contains a list of version-controlled files | |
996 | in the current directory and its subdirectories. Files which are | |
997 | up-to-date (have no local differences from the repository copy) are | |
a11d3737 RS |
998 | usually hidden; if all files in a subdirectory are up-to-date, the |
999 | subdirectory is hidden as well. There is an exception to this rule: | |
1000 | if VC mode detects that a file has changed to an up-to-date state | |
1001 | since you last looked at it, that file and its state are shown. | |
05c5ad63 CY |
1002 | |
1003 | If a directory uses more that one version control system, you can | |
1004 | select which system to use for the @code{vc-dir} command by invoking | |
1005 | @code{vc-dir} with a prefix argument: @kbd{C-u C-x v d}. | |
1006 | ||
1007 | The line for an individual file shows the version control state of | |
1008 | the file. Under RCS and SCCS, the name of the user locking the file | |
1009 | is shown; under CVS, an abbreviated version of the @samp{cvs status} | |
1010 | output is used. Here is an example using CVS: | |
1011 | ||
1012 | @smallexample | |
1013 | @group | |
1014 | ./ | |
1015 | modified file1.c | |
1016 | needs-update file2.c | |
1017 | needs-merge file3.c | |
1018 | @end group | |
1019 | @end smallexample | |
1020 | ||
1021 | @noindent | |
1022 | In this example, @samp{file1.c} is modified with respect to the | |
1023 | repository, and @samp{file2.c} is not. @samp{file3.c} is modified, | |
1024 | but other changes have also been checked in to the repository---you | |
1025 | need to merge them with the work file before you can check it in. | |
1026 | ||
1027 | @vindex vc-stay-local | |
1028 | @vindex vc-cvs-stay-local | |
1029 | In the above, if the repository were on a remote machine, VC only | |
1030 | contacts it when the variable @code{vc-stay-local} (or | |
a11d3737 | 1031 | @code{vc-cvs-stay-local}) is @code{nil} (@pxref{CVS Options}). This is |
05c5ad63 CY |
1032 | because access to the repository may be slow, or you may be working |
1033 | offline and not have access to the repository at all. As a | |
1034 | consequence, VC would not be able to tell you that @samp{file3.c} is | |
1035 | in the ``merge'' state; you would learn that only when you try to | |
1036 | check-in your modified copy of the file, or use a command such as | |
1037 | @kbd{C-x v m}. | |
1038 | ||
1039 | In practice, this is not a problem because CVS handles this case | |
1040 | consistently whenever it arises. In VC, you'll simply get prompted to | |
1041 | merge the remote changes into your work file first. The benefits of | |
1042 | less network communication usually outweigh the disadvantage of not | |
1043 | seeing remote changes immediately. | |
1044 | ||
1045 | @vindex vc-directory-exclusion-list | |
1046 | When a VC directory displays subdirectories it omits some that | |
1047 | should never contain any files under version control. By default, | |
1048 | this includes Version Control subdirectories such as @samp{RCS} and | |
1049 | @samp{CVS}; you can customize this by setting the variable | |
1050 | @code{vc-directory-exclusion-list}. | |
1051 | ||
05c5ad63 CY |
1052 | @node VC Directory Commands |
1053 | @subsubsection VC Directory Commands | |
1054 | ||
1055 | VC Directory mode has a full set of navigation and marking commands | |
1056 | for picking out filesets. Some of these are also available in a | |
1057 | context menu invoked by the @kbd{mouse-2} button. | |
1058 | ||
1059 | Up- and down-arrow keys move in the buffer; @kbd{n} and @kbd{p} also | |
1060 | move vertically as in other list-browsing modes. @key{SPC} and | |
1061 | @key{TAB} behave like down-arrow, and @key{BackTab} behaves like | |
1062 | up-arrow. | |
1063 | ||
1064 | Both @kbd{C-m} and @kbd{f} visit the file on the current | |
1065 | line. @kbd{o} visits that file in another window. @kbd{q} dismisses | |
1066 | the directory buffer. | |
1067 | ||
1068 | @kbd{x} toggles hiding of up-to-date files. | |
1069 | ||
1070 | @kbd{m} marks the file or directory on the current line. If the | |
1071 | region is active, @kbd{m} marks all the files in the region. There | |
1072 | are some restrictions when marking: a file cannot be marked if any of | |
1073 | its parent directories are marked, and a directory cannot be marked if | |
1074 | any files in it or in its child directories are marked. | |
1075 | ||
1076 | @kbd{M} marks all the files with the same VC state as the current | |
1077 | file if the cursor is on a file. If the cursor is on a directory, it | |
1078 | marks all child files. With a prefix argument: marks all files and | |
1079 | directories. | |
1080 | ||
1081 | @kbd{u} unmarks the file or directory on the current line. If the | |
1082 | region is active, it unmarks all the files in the region. | |
1083 | ||
1084 | @kbd{U} marks all the files with the same VC state as the current file | |
1085 | if the cursor is on a file. If the cursor is on a directory, it | |
1086 | unmarks all child files. With a prefix argument: unmarks all marked | |
1087 | files and directories. | |
1088 | ||
1089 | It is possible to do search, search and replace, incremental search, | |
1090 | and incremental regexp search on multiple files. These commands will | |
1091 | work on all the marked files or the current file if nothing is marked. | |
1092 | If a directory is marked, the files in that directory shown in the VC | |
1093 | directory buffer will be used. | |
1094 | ||
1095 | @kbd{S} searches the marked files. | |
1096 | ||
1097 | @kbd{Q} does a query replace on the marked files. | |
1098 | ||
1099 | @kbd{M-s a C-s} does an incremental search on the marked files. | |
1100 | ||
1101 | @kbd{M-s a C-M-s} does an incremental search on the marked files. | |
1102 | ||
1103 | Commands are also accessible from the VC-dir menu. Note that some VC | |
1104 | backends use the VC-dir menu to make available extra backend specific | |
1105 | commands. | |
1106 | ||
1107 | Normal VC commands with the @kbd{C-x v} prefix work in VC directory | |
1108 | buffers. Some single-key shortcuts are available as well; @kbd{=}, | |
1109 | @kbd{+}, @kbd{l}, @kbd{i}, and @kbd{v} behave as through prefixed with | |
1110 | @kbd{C-x v}. | |
1111 | ||
1112 | The command @kbd{C-x v v} (@code{vc-next-action}) operates on all the | |
1113 | marked files, so that you can check in several files at once. | |
1114 | If the underlying VC supports atomic commits of multiple-file | |
1115 | changesets, @kbd{C-x v v} with a selected set of modified but not | |
1116 | committed files will commit all of them at once as a single changeset. | |
1117 | ||
a11d3737 RS |
1118 | When @kbd{C-x v v} (@code{vc-next-action}) operates on multiple |
1119 | files, all of those files must be either in the same state or in | |
1120 | compatible states (added, modified and removed states are considered | |
1121 | compatible). Otherwise it signals an error. This differs from the | |
1122 | behavior of older versions of VC, which did not have fileset | |
1123 | operations and simply did @code{vc-next-action} on each file | |
05c5ad63 CY |
1124 | individually. |
1125 | ||
1126 | If any files are in a state that calls for commit, @kbd{C-x v v} reads a | |
1127 | single log entry and uses it for the changeset as a whole. If the | |
1128 | underling VCS is file- rather than changeset-oriented, the log entry | |
1129 | will be replicated into the history of each file. | |
1130 | ||
1131 | @node Branches | |
1132 | @subsection Multiple Branches of a File | |
1133 | @cindex branch (version control) | |
1134 | @cindex trunk (version control) | |
1135 | ||
1136 | One use of version control is to maintain multiple ``current'' | |
1137 | revisions of a file. For example, you might have different revisions of a | |
1138 | program in which you are gradually adding various unfinished new | |
1139 | features. Each such independent line of development is called a | |
1140 | @dfn{branch}. VC allows you to create branches, switch between | |
1141 | different branches, and merge changes from one branch to another. | |
1142 | Please note, however, that branches are not supported for SCCS. | |
1143 | ||
1144 | A file's main line of development is usually called the @dfn{trunk}. | |
1145 | You can create multiple branches from the trunk. How the difference | |
1146 | between trunk and branch is made visible is dependent on whether the | |
1147 | VCS uses dot-pair or monotonic version IDs. | |
1148 | ||
1149 | In VCSes with dot-pair revision IDs, the revisions on the trunk are | |
1150 | normally IDed 1.1, 1.2, 1.3, etc. At any such revision, you can | |
1151 | start an independent branch. A branch starting at revision 1.2 would | |
1152 | have revision ID 1.2.1.1, and consecutive revisions on this branch | |
1153 | would have IDs 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on. If there is | |
1154 | a second branch also starting at revision 1.2, it would consist of | |
1155 | revisions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc. | |
1156 | ||
1157 | In VCSes with monotonic revision IDs, trunk revisions are IDed as | |
1158 | 1, 2, 3, etc. A branch from (say) revision 2 might start with 2.1 and | |
1159 | continue through 2.2, 2.3, etc. But naming conventions for branches | |
1160 | and subbranches vary widely on these systems, and some (like | |
1161 | Mercurial) never depart from the monotonic integer sequence at all. | |
1162 | Consult the documentation of the VCS you are using. | |
1163 | ||
1164 | @cindex head revision | |
1165 | If you omit the final component of a dot-pair revision ID, that is called a | |
1166 | @dfn{branch ID}. It refers to the highest existing revision on that | |
1167 | branch---the @dfn{head revision} of that branch. The branches in the | |
1168 | dot-pair example above have branch IDs 1.2.1 and 1.2.2. | |
1169 | ||
1170 | @menu | |
1171 | * Switching Branches:: How to get to another existing branch. | |
1172 | * Creating Branches:: How to start a new branch. | |
1173 | * Merging:: Transferring changes between branches. | |
1174 | * Multi-User Branching:: Multiple users working at multiple branches | |
1175 | in parallel. | |
1176 | @end menu | |
1177 | ||
1178 | @node Switching Branches | |
1179 | @subsubsection Switching between Branches | |
1180 | ||
1181 | To switch between branches, type @kbd{C-u C-x v v} and specify the | |
1182 | revision ID you want to select. On a locking-based system, this | |
1183 | version is then visited @emph{unlocked} (write-protected), so you can | |
1184 | examine it before locking it. Switching branches in this way is allowed | |
1185 | only when the file is not locked. | |
1186 | ||
1187 | On a VCS with dot-pair IDs, you can omit the minor part, thus giving | |
1188 | only the branch ID; this takes you to the head version on the | |
1189 | chosen branch. If you only type @key{RET}, Emacs goes to the highest | |
1190 | version on the trunk. | |
1191 | ||
1192 | After you have switched to any branch (including the main branch), you | |
1193 | stay on it for subsequent VC commands, until you explicitly select some | |
1194 | other branch. | |
1195 | ||
1196 | @node Creating Branches | |
1197 | @subsubsection Creating New Branches | |
1198 | ||
1199 | To create a new branch from a head revision (one that is the latest in | |
1200 | the branch that contains it), first select that revision if necessary, | |
1201 | lock it with @kbd{C-x v v}, and make whatever changes you want. Then, | |
1202 | when you check in the changes, use @kbd{C-u C-x v v}. This lets you | |
1203 | specify the revision ID for the new revision. You should specify a | |
1204 | suitable branch ID for a branch starting at the current revision. | |
1205 | For example, if the current revision is 2.5, the branch ID should be | |
1206 | 2.5.1, 2.5.2, and so on, depending on the number of existing branches at | |
1207 | that point. | |
1208 | ||
1209 | To create a new branch at an older revision (one that is no longer the | |
1210 | head of a branch), first select that revision (@pxref{Switching | |
1211 | Branches}). Your procedure will then differ depending on whether you | |
1212 | are using a locking or merging-based VCS. | |
1213 | ||
1214 | On a locking VCS, you will need to lock the old revision branch with | |
1215 | @kbd{C-x v v}. You'll be asked to confirm, when you lock the old | |
1216 | revision, that you really mean to create a new branch---if you say no, | |
1217 | you'll be offered a chance to lock the latest revision instead. On | |
1218 | a merging-based VCS you will skip this step. | |
1219 | ||
1220 | Then make your changes and type @kbd{C-x v v} again to check in a new | |
1221 | revision. This automatically creates a new branch starting from the | |
1222 | selected revision. You need not specially request a new branch, because | |
1223 | that's the only way to add a new revision at a point that is not the head | |
1224 | of a branch. | |
1225 | ||
1226 | After the branch is created, you ``stay'' on it. That means that | |
1227 | subsequent check-ins create new revisions on that branch. To leave the | |
1228 | branch, you must explicitly select a different revision with @kbd{C-u C-x | |
1229 | v v}. To transfer changes from one branch to another, use the merge | |
1230 | command, described in the next section. | |
1231 | ||
1232 | @node Merging | |
1233 | @subsubsection Merging Branches | |
1234 | ||
1235 | @cindex merging changes | |
1236 | When you have finished the changes on a certain branch, you will | |
1237 | often want to incorporate them into the file's main line of development | |
1238 | (the trunk). This is not a trivial operation, because development might | |
1239 | also have proceeded on the trunk, so that you must @dfn{merge} the | |
1240 | changes into a file that has already been changed otherwise. VC allows | |
1241 | you to do this (and other things) with the @code{vc-merge} command. | |
1242 | ||
1243 | @table @kbd | |
1244 | @item C-x v m (vc-merge) | |
1245 | Merge changes into the work file. | |
1246 | @end table | |
1247 | ||
1248 | @kindex C-x v m | |
1249 | @findex vc-merge | |
1250 | @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it | |
1251 | into the current version of the work file. It firsts asks you in the | |
1252 | minibuffer where the changes should come from. If you just type | |
1253 | @key{RET}, Emacs merges any changes that were made on the same branch | |
1254 | since you checked the file out (we call this @dfn{merging the news}). | |
1255 | This is the common way to pick up recent changes from the repository, | |
1256 | regardless of whether you have already changed the file yourself. | |
1257 | ||
1258 | You can also enter a branch ID or a pair of revision IDs in | |
1259 | the minibuffer. Then @kbd{C-x v m} finds the changes from that | |
1260 | branch, or the differences between the two revisions you specified, and | |
1261 | merges them into the current revision of the current file. | |
1262 | ||
1263 | As an example, suppose that you have finished a certain feature on | |
1264 | branch 1.3.1. In the meantime, development on the trunk has proceeded | |
1265 | to revision 1.5. To merge the changes from the branch to the trunk, | |
1266 | first go to the head revision of the trunk, by typing @kbd{C-u C-x v v | |
1267 | @key{RET}}. Revision 1.5 is now current. If locking is used for the file, | |
1268 | type @kbd{C-x v v} to lock revision 1.5 so that you can change it. Next, | |
1269 | type @kbd{C-x v m 1.3.1 @key{RET}}. This takes the entire set of changes on | |
1270 | branch 1.3.1 (relative to revision 1.3, where the branch started, up to | |
1271 | the last revision on the branch) and merges it into the current revision | |
1272 | of the work file. You can now check in the changed file, thus creating | |
1273 | revision 1.6 containing the changes from the branch. | |
1274 | ||
1275 | It is possible to do further editing after merging the branch, before | |
1276 | the next check-in. But it is usually wiser to check in the merged | |
1277 | revision, then lock it and make the further changes. This will keep | |
1278 | a better record of the history of changes. | |
1279 | ||
1280 | @cindex conflicts | |
1281 | @cindex resolving conflicts | |
1282 | When you merge changes into a file that has itself been modified, the | |
1283 | changes might overlap. We call this situation a @dfn{conflict}, and | |
1284 | reconciling the conflicting changes is called @dfn{resolving a | |
1285 | conflict}. | |
1286 | ||
1287 | Whenever conflicts occur during merging, VC detects them, tells you | |
1288 | about them in the echo area, and asks whether you want help in merging. | |
1289 | If you say yes, it starts an Ediff session (@pxref{Top, | |
1290 | Ediff, Ediff, ediff, The Ediff Manual}). | |
1291 | ||
1292 | If you say no, the conflicting changes are both inserted into the | |
1293 | file, surrounded by @dfn{conflict markers}. The example below shows how | |
1294 | a conflict region looks; the file is called @samp{name} and the current | |
1295 | master file revision with user B's changes in it is 1.11. | |
1296 | ||
1297 | @c @w here is so CVS won't think this is a conflict. | |
1298 | @smallexample | |
1299 | @group | |
1300 | @w{<}<<<<<< name | |
1301 | @var{User A's version} | |
1302 | ======= | |
1303 | @var{User B's version} | |
1304 | @w{>}>>>>>> 1.11 | |
1305 | @end group | |
1306 | @end smallexample | |
1307 | ||
1308 | @cindex vc-resolve-conflicts | |
1309 | Then you can resolve the conflicts by editing the file manually. Or | |
1310 | you can type @code{M-x vc-resolve-conflicts} after visiting the file. | |
1311 | This starts an Ediff session, as described above. Don't forget to | |
1312 | check in the merged version afterwards. | |
1313 | ||
1314 | @node Multi-User Branching | |
1315 | @subsubsection Multi-User Branching | |
1316 | ||
1317 | It is often useful for multiple developers to work simultaneously on | |
1318 | different branches of a file. CVS and later systems allow this by | |
1319 | default; for RCS, it is possible if you create multiple source | |
1320 | directories. Each source directory should have a link named | |
1321 | @file{RCS} which points to a common directory of RCS master files. | |
1322 | Then each source directory can have its own choice of selected | |
1323 | revisions, but all share the same common RCS records. | |
1324 | ||
1325 | This technique works reliably and automatically, provided that the | |
1326 | source files contain RCS version headers | |
1327 | @iftex | |
1328 | (@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}). | |
1329 | @end iftex | |
1330 | @ifnottex | |
1331 | (@pxref{Version Headers}). | |
1332 | @end ifnottex | |
1333 | The headers enable Emacs to be sure, at all times, which revision | |
1334 | ID is present in the work file. | |
1335 | ||
1336 | If the files do not have version headers, you must instead tell Emacs | |
1337 | explicitly in each session which branch you are working on. To do this, | |
1338 | first find the file, then type @kbd{C-u C-x v v} and specify the correct | |
1339 | branch ID. This ensures that Emacs knows which branch it is using | |
1340 | during this particular editing session. | |
1341 | ||
1342 | @ifnottex | |
1343 | @include vc1-xtra.texi | |
1344 | @end ifnottex | |
1345 | ||
8cf51b2c GM |
1346 | @node Change Log |
1347 | @section Change Logs | |
1348 | ||
a11d3737 | 1349 | @cindex change log |
8cf51b2c GM |
1350 | A change log file contains a chronological record of when and why you |
1351 | have changed a program, consisting of a sequence of entries describing | |
1352 | individual changes. Normally it is kept in a file called | |
1353 | @file{ChangeLog} in the same directory as the file you are editing, or | |
1354 | one of its parent directories. A single @file{ChangeLog} file can | |
1355 | record changes for all the files in its directory and all its | |
1356 | subdirectories. | |
1357 | ||
a11d3737 RS |
1358 | @menu |
1359 | * Change Log Commands:: Commands for editing change log files. | |
1360 | * Format of ChangeLog:: What the change log file looks like. | |
1361 | @end menu | |
1362 | ||
1363 | @node Change Log Commands | |
1364 | @subsection Change Log Commands | |
1365 | ||
8cf51b2c GM |
1366 | @kindex C-x 4 a |
1367 | @findex add-change-log-entry-other-window | |
1368 | The Emacs command @kbd{C-x 4 a} adds a new entry to the change log | |
1369 | file for the file you are editing | |
1370 | (@code{add-change-log-entry-other-window}). If that file is actually | |
1371 | a backup file, it makes an entry appropriate for the file's | |
1372 | parent---that is useful for making log entries for functions that | |
1373 | have been deleted in the current version. | |
1374 | ||
1375 | @kbd{C-x 4 a} visits the change log file and creates a new entry | |
1376 | unless the most recent entry is for today's date and your name. It | |
1377 | also creates a new item for the current file. For many languages, it | |
1378 | can even guess the name of the function or other object that was | |
1379 | changed. | |
1380 | ||
1381 | @vindex add-log-keep-changes-together | |
1382 | When the variable @code{add-log-keep-changes-together} is | |
1383 | non-@code{nil}, @kbd{C-x 4 a} adds to any existing item for the file | |
1384 | rather than starting a new item. | |
1385 | ||
1386 | @vindex add-log-always-start-new-record | |
1387 | If @code{add-log-always-start-new-record} is non-@code{nil}, | |
1388 | @kbd{C-x 4 a} always makes a new entry, even if the last entry | |
1389 | was made by you and on the same date. | |
1390 | ||
1391 | @vindex change-log-version-info-enabled | |
1392 | @vindex change-log-version-number-regexp-list | |
1393 | @cindex file version in change log entries | |
1394 | If the value of the variable @code{change-log-version-info-enabled} | |
1395 | is non-@code{nil}, @kbd{C-x 4 a} adds the file's version number to the | |
1396 | change log entry. It finds the version number by searching the first | |
1397 | ten percent of the file, using regular expressions from the variable | |
1398 | @code{change-log-version-number-regexp-list}. | |
1399 | ||
1400 | @cindex Change Log mode | |
1401 | @findex change-log-mode | |
1402 | The change log file is visited in Change Log mode. In this major | |
1403 | mode, each bunch of grouped items counts as one paragraph, and each | |
1404 | entry is considered a page. This facilitates editing the entries. | |
1405 | @kbd{C-j} and auto-fill indent each new line like the previous line; | |
1406 | this is convenient for entering the contents of an entry. | |
1407 | ||
d8ff7692 TZ |
1408 | You can use the @code{next-error} command (by default bound to |
1409 | @kbd{C-x `}) to move between entries in the Change Log, when Change | |
1410 | Log mode is on. You will jump to the actual site in the file that was | |
1411 | changed, not just to the next Change Log entry. You can also use | |
1412 | @code{previous-error} to move back in the same list. | |
1413 | ||
8cf51b2c GM |
1414 | @findex change-log-merge |
1415 | You can use the command @kbd{M-x change-log-merge} to merge other | |
1416 | log files into a buffer in Change Log Mode, preserving the date | |
1417 | ordering of entries. | |
1418 | ||
fef3436e CY |
1419 | Version control systems are another way to keep track of changes in |
1420 | your program and keep a change log. In the VC log buffer, typing | |
1421 | @kbd{C-c C-a} (@code{log-edit-insert-changelog}) inserts the relevant | |
1422 | Change Log entry, if one exists (@pxref{Log Buffer}). You can also | |
1423 | insert a VC log entry into a Change Log buffer by typing @kbd{C-x v a} | |
1424 | (@code{vc-update-change-log}) in the Change Log buffer | |
1425 | @iftex | |
1426 | (@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}). | |
1427 | @end iftex | |
1428 | @ifnottex | |
1429 | (@pxref{Change Logs and VC}). | |
1430 | @end ifnottex | |
8cf51b2c GM |
1431 | |
1432 | @node Format of ChangeLog | |
05c5ad63 | 1433 | @subsection Format of ChangeLog |
8cf51b2c GM |
1434 | |
1435 | A change log entry starts with a header line that contains the current | |
1436 | date, your name, and your email address (taken from the variable | |
1437 | @code{add-log-mailing-address}). Aside from these header lines, every | |
1438 | line in the change log starts with a space or a tab. The bulk of the | |
1439 | entry consists of @dfn{items}, each of which starts with a line starting | |
1440 | with whitespace and a star. Here are two entries, both dated in May | |
1441 | 1993, with two items and one item respectively. | |
1442 | ||
1443 | @iftex | |
1444 | @medbreak | |
1445 | @end iftex | |
1446 | @smallexample | |
1447 | 1993-05-25 Richard Stallman <rms@@gnu.org> | |
1448 | ||
1449 | * man.el: Rename symbols `man-*' to `Man-*'. | |
1450 | (manual-entry): Make prompt string clearer. | |
1451 | ||
1452 | * simple.el (blink-matching-paren-distance): | |
1453 | Change default to 12,000. | |
1454 | ||
1455 | 1993-05-24 Richard Stallman <rms@@gnu.org> | |
1456 | ||
1457 | * vc.el (minor-mode-map-alist): Don't use it if it's void. | |
1458 | (vc-cancel-version): Doc fix. | |
1459 | @end smallexample | |
1460 | ||
1461 | One entry can describe several changes; each change should have its | |
1462 | own item, or its own line in an item. Normally there should be a | |
1463 | blank line between items. When items are related (parts of the same | |
1464 | change, in different places), group them by leaving no blank line | |
1465 | between them. | |
1466 | ||
1467 | You should put a copyright notice and permission notice at the | |
1468 | end of the change log file. Here is an example: | |
1469 | ||
1470 | @smallexample | |
1471 | Copyright 1997, 1998 Free Software Foundation, Inc. | |
1472 | Copying and distribution of this file, with or without modification, are | |
1473 | permitted provided the copyright notice and this notice are preserved. | |
1474 | @end smallexample | |
1475 | ||
1476 | @noindent | |
1477 | Of course, you should substitute the proper years and copyright holder. | |
1478 | ||
1479 | @node Tags | |
1480 | @section Tags Tables | |
7ff926e0 | 1481 | @cindex tags and tag tables |
8cf51b2c GM |
1482 | |
1483 | A @dfn{tags table} is a description of how a multi-file program is | |
1484 | broken up into files. It lists the names of the component files and the | |
1485 | names and positions of the functions (or other named subunits) in each | |
1486 | file. Grouping the related files makes it possible to search or replace | |
1487 | through all the files with one command. Recording the function names | |
1488 | and positions makes possible the @kbd{M-.} command which finds the | |
1489 | definition of a function by looking up which of the files it is in. | |
1490 | ||
1491 | Tags tables are stored in files called @dfn{tags table files}. The | |
1492 | conventional name for a tags table file is @file{TAGS}. | |
1493 | ||
1494 | Each entry in the tags table records the name of one tag, the name of the | |
1495 | file that the tag is defined in (implicitly), and the position in that | |
1496 | file of the tag's definition. When a file parsed by @code{etags} is | |
1497 | generated from a different source file, like a C file generated from a | |
1498 | Cweb source file, the tags of the parsed file reference the source | |
1499 | file. | |
1500 | ||
1501 | Just what names from the described files are recorded in the tags table | |
1502 | depends on the programming language of the described file. They | |
1503 | normally include all file names, functions and subroutines, and may | |
1504 | also include global variables, data types, and anything else | |
1505 | convenient. Each name recorded is called a @dfn{tag}. | |
1506 | ||
1507 | @cindex C++ class browser, tags | |
1508 | @cindex tags, C++ | |
1509 | @cindex class browser, C++ | |
1510 | @cindex Ebrowse | |
1511 | See also the Ebrowse facility, which is tailored for C++. | |
1512 | @xref{Top,, Ebrowse, ebrowse, Ebrowse User's Manual}. | |
1513 | ||
1514 | @menu | |
1515 | * Tag Syntax:: Tag syntax for various types of code and text files. | |
1516 | * Create Tags Table:: Creating a tags table with @code{etags}. | |
1517 | * Etags Regexps:: Create arbitrary tags using regular expressions. | |
1518 | * Select Tags Table:: How to visit a tags table. | |
1519 | * Find Tag:: Commands to find the definition of a specific tag. | |
1520 | * Tags Search:: Using a tags table for searching and replacing. | |
1521 | * List Tags:: Listing and finding tags defined in a file. | |
1522 | @end menu | |
1523 | ||
1524 | @node Tag Syntax | |
1525 | @subsection Source File Tag Syntax | |
1526 | ||
1527 | Here is how tag syntax is defined for the most popular languages: | |
1528 | ||
1529 | @itemize @bullet | |
1530 | @item | |
1531 | In C code, any C function or typedef is a tag, and so are definitions of | |
1532 | @code{struct}, @code{union} and @code{enum}. | |
1533 | @code{#define} macro definitions, @code{#undef} and @code{enum} | |
1534 | constants are also | |
1535 | tags, unless you specify @samp{--no-defines} when making the tags table. | |
1536 | Similarly, global variables are tags, unless you specify | |
1537 | @samp{--no-globals}, and so are struct members, unless you specify | |
1538 | @samp{--no-members}. Use of @samp{--no-globals}, @samp{--no-defines} | |
1539 | and @samp{--no-members} can make the tags table file much smaller. | |
1540 | ||
1541 | You can tag function declarations and external variables in addition | |
1542 | to function definitions by giving the @samp{--declarations} option to | |
1543 | @code{etags}. | |
1544 | ||
1545 | @item | |
1546 | In C++ code, in addition to all the tag constructs of C code, member | |
1547 | functions are also recognized; member variables are also recognized, | |
1548 | unless you use the @samp{--no-members} option. Tags for variables and | |
1549 | functions in classes are named @samp{@var{class}::@var{variable}} and | |
1550 | @samp{@var{class}::@var{function}}. @code{operator} definitions have | |
1551 | tag names like @samp{operator+}. | |
1552 | ||
1553 | @item | |
1554 | In Java code, tags include all the constructs recognized in C++, plus | |
1555 | the @code{interface}, @code{extends} and @code{implements} constructs. | |
1556 | Tags for variables and functions in classes are named | |
1557 | @samp{@var{class}.@var{variable}} and @samp{@var{class}.@var{function}}. | |
1558 | ||
1559 | @item | |
1560 | In La@TeX{} text, the argument of any of the commands @code{\chapter}, | |
1561 | @code{\section}, @code{\subsection}, @code{\subsubsection}, | |
1562 | @code{\eqno}, @code{\label}, @code{\ref}, @code{\cite}, | |
1563 | @code{\bibitem}, @code{\part}, @code{\appendix}, @code{\entry}, | |
1564 | @code{\index}, @code{\def}, @code{\newcommand}, @code{\renewcommand}, | |
1565 | @code{\newenvironment} or @code{\renewenvironment} is a tag.@refill | |
1566 | ||
1567 | Other commands can make tags as well, if you specify them in the | |
1568 | environment variable @env{TEXTAGS} before invoking @code{etags}. The | |
1569 | value of this environment variable should be a colon-separated list of | |
1570 | command names. For example, | |
1571 | ||
1572 | @example | |
1573 | TEXTAGS="mycommand:myothercommand" | |
1574 | export TEXTAGS | |
1575 | @end example | |
1576 | ||
1577 | @noindent | |
1578 | specifies (using Bourne shell syntax) that the commands | |
1579 | @samp{\mycommand} and @samp{\myothercommand} also define tags. | |
1580 | ||
1581 | @item | |
1582 | In Lisp code, any function defined with @code{defun}, any variable | |
1583 | defined with @code{defvar} or @code{defconst}, and in general the first | |
1584 | argument of any expression that starts with @samp{(def} in column zero is | |
1585 | a tag. | |
1586 | ||
1587 | @item | |
1588 | In Scheme code, tags include anything defined with @code{def} or with a | |
1589 | construct whose name starts with @samp{def}. They also include variables | |
1590 | set with @code{set!} at top level in the file. | |
1591 | @end itemize | |
1592 | ||
1593 | Several other languages are also supported: | |
1594 | ||
1595 | @itemize @bullet | |
1596 | ||
1597 | @item | |
1598 | In Ada code, functions, procedures, packages, tasks and types are | |
1599 | tags. Use the @samp{--packages-only} option to create tags for | |
1600 | packages only. | |
1601 | ||
1602 | In Ada, the same name can be used for different kinds of entity | |
1603 | (e.g.@:, for a procedure and for a function). Also, for things like | |
1604 | packages, procedures and functions, there is the spec (i.e.@: the | |
1605 | interface) and the body (i.e.@: the implementation). To make it | |
1606 | easier to pick the definition you want, Ada tag name have suffixes | |
1607 | indicating the type of entity: | |
1608 | ||
1609 | @table @samp | |
1610 | @item /b | |
1611 | package body. | |
1612 | @item /f | |
1613 | function. | |
1614 | @item /k | |
1615 | task. | |
1616 | @item /p | |
1617 | procedure. | |
1618 | @item /s | |
1619 | package spec. | |
1620 | @item /t | |
1621 | type. | |
1622 | @end table | |
1623 | ||
1624 | Thus, @kbd{M-x find-tag @key{RET} bidule/b @key{RET}} will go | |
1625 | directly to the body of the package @code{bidule}, while @kbd{M-x | |
1626 | find-tag @key{RET} bidule @key{RET}} will just search for any tag | |
1627 | @code{bidule}. | |
1628 | ||
1629 | @item | |
1630 | In assembler code, labels appearing at the beginning of a line, | |
1631 | followed by a colon, are tags. | |
1632 | ||
1633 | @item | |
1634 | In Bison or Yacc input files, each rule defines as a tag the nonterminal | |
1635 | it constructs. The portions of the file that contain C code are parsed | |
1636 | as C code. | |
1637 | ||
1638 | @item | |
1639 | In Cobol code, tags are paragraph names; that is, any word starting in | |
1640 | column 8 and followed by a period. | |
1641 | ||
1642 | @item | |
1643 | In Erlang code, the tags are the functions, records and macros defined | |
1644 | in the file. | |
1645 | ||
1646 | @item | |
1647 | In Fortran code, functions, subroutines and block data are tags. | |
1648 | ||
1649 | @item | |
1650 | In HTML input files, the tags are the @code{title} and the @code{h1}, | |
1651 | @code{h2}, @code{h3} headers. Also, tags are @code{name=} in anchors | |
1652 | and all occurrences of @code{id=}. | |
1653 | ||
1654 | @item | |
1655 | In Lua input files, all functions are tags. | |
1656 | ||
1657 | @item | |
1658 | In makefiles, targets are tags; additionally, variables are tags | |
1659 | unless you specify @samp{--no-globals}. | |
1660 | ||
1661 | @item | |
1662 | In Objective C code, tags include Objective C definitions for classes, | |
1663 | class categories, methods and protocols. Tags for variables and | |
1664 | functions in classes are named @samp{@var{class}::@var{variable}} and | |
1665 | @samp{@var{class}::@var{function}}. | |
1666 | ||
1667 | @item | |
1668 | In Pascal code, the tags are the functions and procedures defined in | |
1669 | the file. | |
1670 | ||
1671 | @item | |
1672 | In Perl code, the tags are the packages, subroutines and variables | |
1673 | defined by the @code{package}, @code{sub}, @code{my} and @code{local} | |
1674 | keywords. Use @samp{--globals} if you want to tag global variables. | |
1675 | Tags for subroutines are named @samp{@var{package}::@var{sub}}. The | |
1676 | name for subroutines defined in the default package is | |
1677 | @samp{main::@var{sub}}. | |
1678 | ||
1679 | @item | |
1680 | In PHP code, tags are functions, classes and defines. Vars are tags | |
1681 | too, unless you use the @samp{--no-members} option. | |
1682 | ||
1683 | @item | |
1684 | In PostScript code, the tags are the functions. | |
1685 | ||
1686 | @item | |
1687 | In Prolog code, tags are predicates and rules at the beginning of | |
1688 | line. | |
1689 | ||
1690 | @item | |
1691 | In Python code, @code{def} or @code{class} at the beginning of a line | |
1692 | generate a tag. | |
1693 | @end itemize | |
1694 | ||
1695 | You can also generate tags based on regexp matching (@pxref{Etags | |
1696 | Regexps}) to handle other formats and languages. | |
1697 | ||
1698 | @node Create Tags Table | |
1699 | @subsection Creating Tags Tables | |
1700 | @cindex @code{etags} program | |
1701 | ||
1702 | The @code{etags} program is used to create a tags table file. It knows | |
1703 | the syntax of several languages, as described in | |
1704 | @iftex | |
1705 | the previous section. | |
1706 | @end iftex | |
1707 | @ifnottex | |
1708 | @ref{Tag Syntax}. | |
1709 | @end ifnottex | |
1710 | Here is how to run @code{etags}: | |
1711 | ||
1712 | @example | |
1713 | etags @var{inputfiles}@dots{} | |
1714 | @end example | |
1715 | ||
1716 | @noindent | |
1717 | The @code{etags} program reads the specified files, and writes a tags | |
0b7f2f3f FP |
1718 | table named @file{TAGS} in the current working directory. You can |
1719 | optionally specify a different file name for the tags table by using the | |
1720 | @samp{--output=@var{file}} option; specifying @file{-} as a file name | |
1721 | prints the tags table to standard output. | |
8cf51b2c GM |
1722 | |
1723 | If the specified files don't exist, @code{etags} looks for | |
1724 | compressed versions of them and uncompresses them to read them. Under | |
1725 | MS-DOS, @code{etags} also looks for file names like @file{mycode.cgz} | |
1726 | if it is given @samp{mycode.c} on the command line and @file{mycode.c} | |
1727 | does not exist. | |
1728 | ||
1729 | @code{etags} recognizes the language used in an input file based on | |
1730 | its file name and contents. You can specify the language with the | |
1731 | @samp{--language=@var{name}} option, described below. | |
1732 | ||
1733 | If the tags table data become outdated due to changes in the files | |
1734 | described in the table, the way to update the tags table is the same | |
1735 | way it was made in the first place. If the tags table fails to record | |
1736 | a tag, or records it for the wrong file, then Emacs cannot possibly | |
1737 | find its definition until you update the tags table. However, if the | |
1738 | position recorded in the tags table becomes a little bit wrong (due to | |
1739 | other editing), the worst consequence is a slight delay in finding the | |
1740 | tag. Even if the stored position is very far wrong, Emacs will still | |
1741 | find the tag, after searching most of the file for it. That delay is | |
1742 | hardly noticeable with today's computers. | |
1743 | ||
1744 | Thus, there is no need to update the tags table after each edit. | |
1745 | You should update a tags table when you define new tags that you want | |
1746 | to have listed, or when you move tag definitions from one file to | |
1747 | another, or when changes become substantial. | |
1748 | ||
1749 | One tags table can virtually include another. Specify the included | |
1750 | tags file name with the @samp{--include=@var{file}} option when | |
1751 | creating the file that is to include it. The latter file then acts as | |
1752 | if it covered all the source files specified in the included file, as | |
1753 | well as the files it directly contains. | |
1754 | ||
1755 | If you specify the source files with relative file names when you run | |
1756 | @code{etags}, the tags file will contain file names relative to the | |
1757 | directory where the tags file was initially written. This way, you can | |
1758 | move an entire directory tree containing both the tags file and the | |
1759 | source files, and the tags file will still refer correctly to the source | |
0b7f2f3f FP |
1760 | files. If the tags file is @file{-} or is in the @file{/dev} directory, |
1761 | however, the file names are | |
8cf51b2c GM |
1762 | made relative to the current working directory. This is useful, for |
1763 | example, when writing the tags to @file{/dev/stdout}. | |
1764 | ||
1765 | When using a relative file name, it should not be a symbolic link | |
1766 | pointing to a tags file in a different directory, because this would | |
1767 | generally render the file names invalid. | |
1768 | ||
1769 | If you specify absolute file names as arguments to @code{etags}, then | |
1770 | the tags file will contain absolute file names. This way, the tags file | |
1771 | will still refer to the same files even if you move it, as long as the | |
1772 | source files remain in the same place. Absolute file names start with | |
1773 | @samp{/}, or with @samp{@var{device}:/} on MS-DOS and MS-Windows. | |
1774 | ||
1775 | When you want to make a tags table from a great number of files, you | |
1776 | may have problems listing them on the command line, because some systems | |
1777 | have a limit on its length. The simplest way to circumvent this limit | |
1778 | is to tell @code{etags} to read the file names from its standard input, | |
1779 | by typing a dash in place of the file names, like this: | |
1780 | ||
1781 | @smallexample | |
1782 | find . -name "*.[chCH]" -print | etags - | |
1783 | @end smallexample | |
1784 | ||
1785 | Use the option @samp{--language=@var{name}} to specify the language | |
1786 | explicitly. You can intermix these options with file names; each one | |
1787 | applies to the file names that follow it. Specify | |
1788 | @samp{--language=auto} to tell @code{etags} to resume guessing the | |
1789 | language from the file names and file contents. Specify | |
1790 | @samp{--language=none} to turn off language-specific processing | |
1791 | entirely; then @code{etags} recognizes tags by regexp matching alone | |
1792 | (@pxref{Etags Regexps}). | |
1793 | ||
1794 | The option @samp{--parse-stdin=@var{file}} is mostly useful when | |
1795 | calling @code{etags} from programs. It can be used (only once) in | |
1796 | place of a file name on the command line. @code{Etags} will read from | |
1797 | standard input and mark the produced tags as belonging to the file | |
1798 | @var{file}. | |
1799 | ||
1800 | @samp{etags --help} outputs the list of the languages @code{etags} | |
1801 | knows, and the file name rules for guessing the language. It also prints | |
1802 | a list of all the available @code{etags} options, together with a short | |
1803 | explanation. If followed by one or more @samp{--language=@var{lang}} | |
1804 | options, it outputs detailed information about how tags are generated for | |
1805 | @var{lang}. | |
1806 | ||
1807 | @node Etags Regexps | |
1808 | @subsection Etags Regexps | |
1809 | ||
1810 | The @samp{--regex} option provides a general way of recognizing tags | |
1811 | based on regexp matching. You can freely intermix this option with | |
1812 | file names, and each one applies to the source files that follow it. | |
1813 | If you specify multiple @samp{--regex} options, all of them are used | |
1814 | in parallel. The syntax is: | |
1815 | ||
1816 | @smallexample | |
1817 | --regex=[@var{@{language@}}]/@var{tagregexp}/[@var{nameregexp}/]@var{modifiers} | |
1818 | @end smallexample | |
1819 | ||
1820 | The essential part of the option value is @var{tagregexp}, the | |
1821 | regexp for matching tags. It is always used anchored, that is, it | |
1822 | only matches at the beginning of a line. If you want to allow | |
1823 | indented tags, use a regexp that matches initial whitespace; start it | |
1824 | with @samp{[ \t]*}. | |
1825 | ||
1826 | In these regular expressions, @samp{\} quotes the next character, and | |
1827 | all the GCC character escape sequences are supported (@samp{\a} for | |
1828 | bell, @samp{\b} for back space, @samp{\d} for delete, @samp{\e} for | |
1829 | escape, @samp{\f} for formfeed, @samp{\n} for newline, @samp{\r} for | |
1830 | carriage return, @samp{\t} for tab, and @samp{\v} for vertical tab). | |
1831 | ||
1832 | Ideally, @var{tagregexp} should not match more characters than are | |
1833 | needed to recognize what you want to tag. If the syntax requires you | |
1834 | to write @var{tagregexp} so it matches more characters beyond the tag | |
1835 | itself, you should add a @var{nameregexp}, to pick out just the tag. | |
1836 | This will enable Emacs to find tags more accurately and to do | |
1837 | completion on tag names more reliably. You can find some examples | |
1838 | below. | |
1839 | ||
1840 | The @var{modifiers} are a sequence of zero or more characters that | |
1841 | modify the way @code{etags} does the matching. A regexp with no | |
1842 | modifiers is applied sequentially to each line of the input file, in a | |
1843 | case-sensitive way. The modifiers and their meanings are: | |
1844 | ||
1845 | @table @samp | |
1846 | @item i | |
1847 | Ignore case when matching this regexp. | |
1848 | @item m | |
1849 | Match this regular expression against the whole file, so that | |
1850 | multi-line matches are possible. | |
1851 | @item s | |
1852 | Match this regular expression against the whole file, and allow | |
1853 | @samp{.} in @var{tagregexp} to match newlines. | |
1854 | @end table | |
1855 | ||
1856 | The @samp{-R} option cancels all the regexps defined by preceding | |
1857 | @samp{--regex} options. It too applies to the file names following | |
1858 | it. Here's an example: | |
1859 | ||
1860 | @smallexample | |
1861 | etags --regex=/@var{reg1}/i voo.doo --regex=/@var{reg2}/m \ | |
1862 | bar.ber -R --lang=lisp los.er | |
1863 | @end smallexample | |
1864 | ||
1865 | @noindent | |
1866 | Here @code{etags} chooses the parsing language for @file{voo.doo} and | |
1867 | @file{bar.ber} according to their contents. @code{etags} also uses | |
1868 | @var{reg1} to recognize additional tags in @file{voo.doo}, and both | |
1869 | @var{reg1} and @var{reg2} to recognize additional tags in | |
1870 | @file{bar.ber}. @var{reg1} is checked against each line of | |
1871 | @file{voo.doo} and @file{bar.ber}, in a case-insensitive way, while | |
1872 | @var{reg2} is checked against the whole @file{bar.ber} file, | |
1873 | permitting multi-line matches, in a case-sensitive way. @code{etags} | |
1874 | uses only the Lisp tags rules, with no user-specified regexp matching, | |
1875 | to recognize tags in @file{los.er}. | |
1876 | ||
1877 | You can restrict a @samp{--regex} option to match only files of a | |
1878 | given language by using the optional prefix @var{@{language@}}. | |
1879 | (@samp{etags --help} prints the list of languages recognized by | |
1880 | @code{etags}.) This is particularly useful when storing many | |
1881 | predefined regular expressions for @code{etags} in a file. The | |
1882 | following example tags the @code{DEFVAR} macros in the Emacs source | |
1883 | files, for the C language only: | |
1884 | ||
1885 | @smallexample | |
1886 | --regex='@{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/' | |
1887 | @end smallexample | |
1888 | ||
1889 | @noindent | |
1890 | When you have complex regular expressions, you can store the list of | |
1891 | them in a file. The following option syntax instructs @code{etags} to | |
1892 | read two files of regular expressions. The regular expressions | |
1893 | contained in the second file are matched without regard to case. | |
1894 | ||
1895 | @smallexample | |
1896 | --regex=@@@var{case-sensitive-file} --ignore-case-regex=@@@var{ignore-case-file} | |
1897 | @end smallexample | |
1898 | ||
1899 | @noindent | |
1900 | A regex file for @code{etags} contains one regular expression per | |
1901 | line. Empty lines, and lines beginning with space or tab are ignored. | |
1902 | When the first character in a line is @samp{@@}, @code{etags} assumes | |
1903 | that the rest of the line is the name of another file of regular | |
1904 | expressions; thus, one such file can include another file. All the | |
1905 | other lines are taken to be regular expressions. If the first | |
1906 | non-whitespace text on the line is @samp{--}, that line is a comment. | |
1907 | ||
1908 | For example, we can create a file called @samp{emacs.tags} with the | |
1909 | following contents: | |
1910 | ||
1911 | @smallexample | |
1912 | -- This is for GNU Emacs C source files | |
1913 | @{c@}/[ \t]*DEFVAR_[A-Z_ \t(]+"\([^"]+\)"/\1/ | |
1914 | @end smallexample | |
1915 | ||
1916 | @noindent | |
1917 | and then use it like this: | |
1918 | ||
1919 | @smallexample | |
1920 | etags --regex=@@emacs.tags *.[ch] */*.[ch] | |
1921 | @end smallexample | |
1922 | ||
1923 | Here are some more examples. The regexps are quoted to protect them | |
1924 | from shell interpretation. | |
1925 | ||
1926 | @itemize @bullet | |
1927 | ||
1928 | @item | |
1929 | Tag Octave files: | |
1930 | ||
1931 | @smallexample | |
1932 | etags --language=none \ | |
1933 | --regex='/[ \t]*function.*=[ \t]*\([^ \t]*\)[ \t]*(/\1/' \ | |
1934 | --regex='/###key \(.*\)/\1/' \ | |
1935 | --regex='/[ \t]*global[ \t].*/' \ | |
1936 | *.m | |
1937 | @end smallexample | |
1938 | ||
1939 | @noindent | |
1940 | Note that tags are not generated for scripts, so that you have to add | |
1941 | a line by yourself of the form @samp{###key @var{scriptname}} if you | |
1942 | want to jump to it. | |
1943 | ||
1944 | @item | |
1945 | Tag Tcl files: | |
1946 | ||
1947 | @smallexample | |
1948 | etags --language=none --regex='/proc[ \t]+\([^ \t]+\)/\1/' *.tcl | |
1949 | @end smallexample | |
1950 | ||
1951 | @item | |
1952 | Tag VHDL files: | |
1953 | ||
1954 | @smallexample | |
1955 | etags --language=none \ | |
1956 | --regex='/[ \t]*\(ARCHITECTURE\|CONFIGURATION\) +[^ ]* +OF/' \ | |
1957 | --regex='/[ \t]*\(ATTRIBUTE\|ENTITY\|FUNCTION\|PACKAGE\ | |
1958 | \( BODY\)?\|PROCEDURE\|PROCESS\|TYPE\)[ \t]+\([^ \t(]+\)/\3/' | |
1959 | @end smallexample | |
1960 | @end itemize | |
1961 | ||
1962 | @node Select Tags Table | |
1963 | @subsection Selecting a Tags Table | |
1964 | ||
1965 | @vindex tags-file-name | |
1966 | @findex visit-tags-table | |
1967 | Emacs has at any time one @dfn{selected} tags table, and all the | |
1968 | commands for working with tags tables use the selected one. To select | |
1969 | a tags table, type @kbd{M-x visit-tags-table}, which reads the tags | |
1970 | table file name as an argument, with @file{TAGS} in the default | |
1971 | directory as the default. | |
1972 | ||
1973 | Emacs does not actually read in the tags table contents until you | |
1974 | try to use them; all @code{visit-tags-table} does is store the file | |
1975 | name in the variable @code{tags-file-name}, and setting the variable | |
1976 | yourself is just as good. The variable's initial value is @code{nil}; | |
1977 | that value tells all the commands for working with tags tables that | |
1978 | they must ask for a tags table file name to use. | |
1979 | ||
1980 | Using @code{visit-tags-table} when a tags table is already loaded | |
1981 | gives you a choice: you can add the new tags table to the current list | |
1982 | of tags tables, or start a new list. The tags commands use all the tags | |
1983 | tables in the current list. If you start a new list, the new tags table | |
1984 | is used @emph{instead} of others. If you add the new table to the | |
1985 | current list, it is used @emph{as well as} the others. | |
1986 | ||
1987 | @vindex tags-table-list | |
1988 | You can specify a precise list of tags tables by setting the variable | |
1989 | @code{tags-table-list} to a list of strings, like this: | |
1990 | ||
1991 | @c keep this on two lines for formatting in smallbook | |
1992 | @example | |
1993 | @group | |
1994 | (setq tags-table-list | |
1995 | '("~/emacs" "/usr/local/lib/emacs/src")) | |
1996 | @end group | |
1997 | @end example | |
1998 | ||
1999 | @noindent | |
2000 | This tells the tags commands to look at the @file{TAGS} files in your | |
2001 | @file{~/emacs} directory and in the @file{/usr/local/lib/emacs/src} | |
2002 | directory. The order depends on which file you are in and which tags | |
2003 | table mentions that file, as explained above. | |
2004 | ||
2005 | Do not set both @code{tags-file-name} and @code{tags-table-list}. | |
2006 | ||
2007 | @node Find Tag | |
2008 | @subsection Finding a Tag | |
2009 | ||
2010 | The most important thing that a tags table enables you to do is to find | |
2011 | the definition of a specific tag. | |
2012 | ||
2013 | @table @kbd | |
2014 | @item M-.@: @var{tag} @key{RET} | |
2015 | Find first definition of @var{tag} (@code{find-tag}). | |
2016 | @item C-u M-. | |
2017 | Find next alternate definition of last tag specified. | |
2018 | @item C-u - M-. | |
2019 | Go back to previous tag found. | |
2020 | @item C-M-. @var{pattern} @key{RET} | |
2021 | Find a tag whose name matches @var{pattern} (@code{find-tag-regexp}). | |
2022 | @item C-u C-M-. | |
2023 | Find the next tag whose name matches the last pattern used. | |
2024 | @item C-x 4 .@: @var{tag} @key{RET} | |
2025 | Find first definition of @var{tag}, but display it in another window | |
2026 | (@code{find-tag-other-window}). | |
2027 | @item C-x 5 .@: @var{tag} @key{RET} | |
2028 | Find first definition of @var{tag}, and create a new frame to select the | |
2029 | buffer (@code{find-tag-other-frame}). | |
2030 | @item M-* | |
2031 | Pop back to where you previously invoked @kbd{M-.} and friends. | |
2032 | @end table | |
2033 | ||
2034 | @kindex M-. | |
2035 | @findex find-tag | |
2036 | @kbd{M-.}@: (@code{find-tag}) is the command to find the definition of | |
2037 | a specified tag. It searches through the tags table for that tag, as a | |
2038 | string, and then uses the tags table info to determine the file that the | |
2039 | definition is in and the approximate character position in the file of | |
2040 | the definition. Then @code{find-tag} visits that file, moves point to | |
2041 | the approximate character position, and searches ever-increasing | |
2042 | distances away to find the tag definition. | |
2043 | ||
2044 | If an empty argument is given (just type @key{RET}), the balanced | |
2045 | expression in the buffer before or around point is used as the | |
2046 | @var{tag} argument. @xref{Expressions}. | |
2047 | ||
2048 | You don't need to give @kbd{M-.} the full name of the tag; a part | |
2049 | will do. This is because @kbd{M-.} finds tags in the table which | |
2050 | contain @var{tag} as a substring. However, it prefers an exact match | |
2051 | to a substring match. To find other tags that match the same | |
2052 | substring, give @code{find-tag} a numeric argument, as in @kbd{C-u | |
2053 | M-.}; this does not read a tag name, but continues searching the tags | |
2054 | table's text for another tag containing the same substring last used. | |
2055 | If you have a real @key{META} key, @kbd{M-0 M-.}@: is an easier | |
2056 | alternative to @kbd{C-u M-.}. | |
2057 | ||
2058 | @kindex C-x 4 . | |
2059 | @findex find-tag-other-window | |
2060 | @kindex C-x 5 . | |
2061 | @findex find-tag-other-frame | |
2062 | Like most commands that can switch buffers, @code{find-tag} has a | |
2063 | variant that displays the new buffer in another window, and one that | |
2064 | makes a new frame for it. The former is @w{@kbd{C-x 4 .}}, which invokes | |
2065 | the command @code{find-tag-other-window}. The latter is @w{@kbd{C-x 5 .}}, | |
2066 | which invokes @code{find-tag-other-frame}. | |
2067 | ||
2068 | To move back to places you've found tags recently, use @kbd{C-u - | |
2069 | M-.}; more generally, @kbd{M-.} with a negative numeric argument. This | |
2070 | command can take you to another buffer. @w{@kbd{C-x 4 .}} with a negative | |
2071 | argument finds the previous tag location in another window. | |
2072 | ||
2073 | @kindex M-* | |
2074 | @findex pop-tag-mark | |
2075 | @vindex find-tag-marker-ring-length | |
2076 | As well as going back to places you've found tags recently, you can go | |
2077 | back to places @emph{from where} you found them. Use @kbd{M-*}, which | |
2078 | invokes the command @code{pop-tag-mark}, for this. Typically you would | |
2079 | find and study the definition of something with @kbd{M-.} and then | |
2080 | return to where you were with @kbd{M-*}. | |
2081 | ||
2082 | Both @kbd{C-u - M-.} and @kbd{M-*} allow you to retrace your steps to | |
2083 | a depth determined by the variable @code{find-tag-marker-ring-length}. | |
2084 | ||
2085 | @findex find-tag-regexp | |
2086 | @kindex C-M-. | |
2087 | The command @kbd{C-M-.} (@code{find-tag-regexp}) visits the tags that | |
2088 | match a specified regular expression. It is just like @kbd{M-.} except | |
2089 | that it does regexp matching instead of substring matching. | |
2090 | ||
2091 | @node Tags Search | |
2092 | @subsection Searching and Replacing with Tags Tables | |
2093 | @cindex search and replace in multiple files | |
2094 | @cindex multiple-file search and replace | |
2095 | ||
2096 | The commands in this section visit and search all the files listed | |
2097 | in the selected tags table, one by one. For these commands, the tags | |
2098 | table serves only to specify a sequence of files to search. These | |
2099 | commands scan the list of tags tables starting with the first tags | |
2100 | table (if any) that describes the current file, proceed from there to | |
2101 | the end of the list, and then scan from the beginning of the list | |
2102 | until they have covered all the tables in the list. | |
2103 | ||
2104 | @table @kbd | |
2105 | @item M-x tags-search @key{RET} @var{regexp} @key{RET} | |
2106 | Search for @var{regexp} through the files in the selected tags | |
2107 | table. | |
2108 | @item M-x tags-query-replace @key{RET} @var{regexp} @key{RET} @var{replacement} @key{RET} | |
2109 | Perform a @code{query-replace-regexp} on each file in the selected tags table. | |
2110 | @item M-, | |
2111 | Restart one of the commands above, from the current location of point | |
2112 | (@code{tags-loop-continue}). | |
2113 | @end table | |
2114 | ||
2115 | @findex tags-search | |
2116 | @kbd{M-x tags-search} reads a regexp using the minibuffer, then | |
2117 | searches for matches in all the files in the selected tags table, one | |
2118 | file at a time. It displays the name of the file being searched so you | |
2119 | can follow its progress. As soon as it finds an occurrence, | |
2120 | @code{tags-search} returns. | |
2121 | ||
2122 | @kindex M-, | |
2123 | @findex tags-loop-continue | |
2124 | Having found one match, you probably want to find all the rest. To find | |
2125 | one more match, type @kbd{M-,} (@code{tags-loop-continue}) to resume the | |
2126 | @code{tags-search}. This searches the rest of the current buffer, followed | |
2127 | by the remaining files of the tags table.@refill | |
2128 | ||
2129 | @findex tags-query-replace | |
2130 | @kbd{M-x tags-query-replace} performs a single | |
2131 | @code{query-replace-regexp} through all the files in the tags table. It | |
2132 | reads a regexp to search for and a string to replace with, just like | |
2133 | ordinary @kbd{M-x query-replace-regexp}. It searches much like @kbd{M-x | |
2134 | tags-search}, but repeatedly, processing matches according to your | |
2135 | input. @xref{Replace}, for more information on query replace. | |
2136 | ||
2137 | @vindex tags-case-fold-search | |
2138 | @cindex case-sensitivity and tags search | |
2139 | You can control the case-sensitivity of tags search commands by | |
2140 | customizing the value of the variable @code{tags-case-fold-search}. The | |
2141 | default is to use the same setting as the value of | |
2142 | @code{case-fold-search} (@pxref{Search Case}). | |
2143 | ||
2144 | It is possible to get through all the files in the tags table with a | |
2145 | single invocation of @kbd{M-x tags-query-replace}. But often it is | |
2146 | useful to exit temporarily, which you can do with any input event that | |
ae068fdf RS |
2147 | has no special query replace meaning. You can resume the query |
2148 | replace subsequently by typing @kbd{M-,}; this command resumes the | |
2149 | last tags search or replace command that you did. For instance, to | |
2150 | skip the rest of the current file, you can type @kbd{M-> M-,}. | |
8cf51b2c GM |
2151 | |
2152 | The commands in this section carry out much broader searches than the | |
2153 | @code{find-tag} family. The @code{find-tag} commands search only for | |
2154 | definitions of tags that match your substring or regexp. The commands | |
2155 | @code{tags-search} and @code{tags-query-replace} find every occurrence | |
2156 | of the regexp, as ordinary search commands and replace commands do in | |
2157 | the current buffer. | |
2158 | ||
2159 | These commands create buffers only temporarily for the files that they | |
2160 | have to search (those which are not already visited in Emacs buffers). | |
2161 | Buffers in which no match is found are quickly killed; the others | |
2162 | continue to exist. | |
2163 | ||
2164 | It may have struck you that @code{tags-search} is a lot like | |
2165 | @code{grep}. You can also run @code{grep} itself as an inferior of | |
2166 | Emacs and have Emacs show you the matching lines one by one. | |
2167 | @xref{Grep Searching}. | |
2168 | ||
2169 | @node List Tags | |
2170 | @subsection Tags Table Inquiries | |
2171 | ||
2172 | @table @kbd | |
2173 | @item M-x list-tags @key{RET} @var{file} @key{RET} | |
2174 | Display a list of the tags defined in the program file @var{file}. | |
2175 | @item M-x tags-apropos @key{RET} @var{regexp} @key{RET} | |
2176 | Display a list of all tags matching @var{regexp}. | |
2177 | @end table | |
2178 | ||
2179 | @findex list-tags | |
2180 | @kbd{M-x list-tags} reads the name of one of the files described by | |
2181 | the selected tags table, and displays a list of all the tags defined in | |
2182 | that file. The ``file name'' argument is really just a string to | |
2183 | compare against the file names recorded in the tags table; it is read as | |
2184 | a string rather than as a file name. Therefore, completion and | |
2185 | defaulting are not available, and you must enter the file name the same | |
2186 | way it appears in the tags table. Do not include a directory as part of | |
2187 | the file name unless the file name recorded in the tags table includes a | |
2188 | directory. | |
2189 | ||
2190 | @findex tags-apropos | |
2191 | @vindex tags-apropos-verbose | |
2192 | @kbd{M-x tags-apropos} is like @code{apropos} for tags | |
2193 | (@pxref{Apropos}). It finds all the tags in the selected tags table | |
2194 | whose entries match @var{regexp}, and displays them. If the variable | |
2195 | @code{tags-apropos-verbose} is non-@code{nil}, it displays the names | |
2196 | of the tags files together with the tag names. | |
2197 | ||
2198 | @vindex tags-tag-face | |
2199 | @vindex tags-apropos-additional-actions | |
2200 | You can customize the appearance of the output by setting the | |
2201 | variable @code{tags-tag-face} to a face. You can display additional | |
2202 | output with @kbd{M-x tags-apropos} by customizing the variable | |
2203 | @code{tags-apropos-additional-actions}---see its documentation for | |
2204 | details. | |
2205 | ||
2206 | You can also use the collection of tag names to complete a symbol | |
2207 | name in the buffer. @xref{Symbol Completion}. | |
2208 | ||
2209 | @ifnottex | |
2210 | @include emerge-xtra.texi | |
2211 | @end ifnottex | |
2212 | ||
2213 | @ignore | |
2214 | arch-tag: b9d83dfb-82ea-4ff6-bab5-05a3617091fb | |
2215 | @end ignore |