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