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