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