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