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