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