Mercurial > emacs
annotate doc/emacs/files.texi @ 93759:4e76a03232e5
Merge from emacs--rel--22
Revision: emacs@sv.gnu.org/emacs--devo--0--patch-1107
author | Miles Bader <miles@gnu.org> |
---|---|
date | Sat, 05 Apr 2008 23:01:26 +0000 |
parents | 3e6309763b5d |
children | 8da676e385e1 |
rev | line source |
---|---|
84239 | 1 @c This is part of the Emacs manual. |
2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, | |
87903 | 3 @c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. |
84239 | 4 @c See file emacs.texi for copying conditions. |
5 @node Files, Buffers, Keyboard Macros, Top | |
6 @chapter File Handling | |
7 @cindex files | |
8 | |
9 The operating system stores data permanently in named @dfn{files}, so | |
10 most of the text you edit with Emacs comes from a file and is ultimately | |
11 stored in a file. | |
12 | |
13 To edit a file, you must tell Emacs to read the file and prepare a | |
14 buffer containing a copy of the file's text. This is called | |
15 @dfn{visiting} the file. Editing commands apply directly to text in the | |
16 buffer; that is, to the copy inside Emacs. Your changes appear in the | |
17 file itself only when you @dfn{save} the buffer back into the file. | |
18 | |
19 In addition to visiting and saving files, Emacs can delete, copy, | |
20 rename, and append to files, keep multiple versions of them, and operate | |
21 on file directories. | |
22 | |
23 @menu | |
24 * File Names:: How to type and edit file-name arguments. | |
25 * Visiting:: Visiting a file prepares Emacs to edit the file. | |
26 * Saving:: Saving makes your changes permanent. | |
27 * Reverting:: Reverting cancels all the changes not saved. | |
28 @ifnottex | |
29 * Autorevert:: Auto Reverting non-file buffers. | |
30 @end ifnottex | |
31 * Auto Save:: Auto Save periodically protects against loss of data. | |
32 * File Aliases:: Handling multiple names for one file. | |
33 * Version Control:: Version control systems (RCS, CVS and SCCS). | |
34 * Directories:: Creating, deleting, and listing file directories. | |
35 * Comparing Files:: Finding where two files differ. | |
36 * Diff Mode:: Mode for editing file differences. | |
37 * Misc File Ops:: Other things you can do on files. | |
38 * Compressed Files:: Accessing compressed files. | |
39 * File Archives:: Operating on tar, zip, jar etc. archive files. | |
40 * Remote Files:: Accessing files on other sites. | |
41 * Quoted File Names:: Quoting special characters in file names. | |
42 * File Name Cache:: Completion against a list of files you often use. | |
43 * File Conveniences:: Convenience Features for Finding Files. | |
44 * Filesets:: Handling sets of files. | |
45 @end menu | |
46 | |
47 @node File Names | |
48 @section File Names | |
49 @cindex file names | |
50 | |
51 Most Emacs commands that operate on a file require you to specify the | |
52 file name. (Saving and reverting are exceptions; the buffer knows which | |
53 file name to use for them.) You enter the file name using the | |
54 minibuffer (@pxref{Minibuffer}). @dfn{Completion} is available | |
55 (@pxref{Completion}) to make it easier to specify long file names. When | |
56 completing file names, Emacs ignores those whose file-name extensions | |
57 appear in the variable @code{completion-ignored-extensions}; see | |
58 @ref{Completion Options}. | |
59 | |
60 For most operations, there is a @dfn{default file name} which is used | |
61 if you type just @key{RET} to enter an empty argument. Normally the | |
62 default file name is the name of the file visited in the current buffer; | |
63 this makes it easy to operate on that file with any of the Emacs file | |
64 commands. | |
65 | |
66 @vindex default-directory | |
67 Each buffer has a default directory which is normally the same as the | |
68 directory of the file visited in that buffer. When you enter a file | |
69 name without a directory, the default directory is used. If you specify | |
70 a directory in a relative fashion, with a name that does not start with | |
71 a slash, it is interpreted with respect to the default directory. The | |
72 default directory is kept in the variable @code{default-directory}, | |
73 which has a separate value in every buffer. | |
74 | |
75 @findex cd | |
76 @findex pwd | |
77 The command @kbd{M-x pwd} displays the current buffer's default | |
78 directory, and the command @kbd{M-x cd} sets it (to a value read using | |
79 the minibuffer). A buffer's default directory changes only when the | |
80 @code{cd} command is used. A file-visiting buffer's default directory | |
81 is initialized to the directory of the file it visits. If you create | |
82 a buffer with @kbd{C-x b}, its default directory is copied from that | |
83 of the buffer that was current at the time. | |
84 | |
85 For example, if the default file name is @file{/u/rms/gnu/gnu.tasks} | |
86 then the default directory is normally @file{/u/rms/gnu/}. If you | |
87 type just @samp{foo}, which does not specify a directory, it is short | |
88 for @file{/u/rms/gnu/foo}. @samp{../.login} would stand for | |
89 @file{/u/rms/.login}. @samp{new/foo} would stand for the file name | |
90 @file{/u/rms/gnu/new/foo}. | |
91 | |
92 @vindex insert-default-directory | |
93 The default directory actually appears in the minibuffer when the | |
94 minibuffer becomes active to read a file name. This serves two | |
95 purposes: it @emph{shows} you what the default is, so that you can type | |
96 a relative file name and know with certainty what it will mean, and it | |
97 allows you to @emph{edit} the default to specify a different directory. | |
98 This insertion of the default directory is inhibited if the variable | |
99 @code{insert-default-directory} is set to @code{nil}. | |
100 | |
101 Note that it is legitimate to type an absolute file name after you | |
102 enter the minibuffer, ignoring the presence of the default directory | |
103 name as part of the text. The final minibuffer contents may look | |
104 invalid, but that is not so. For example, if the minibuffer starts out | |
105 with @samp{/usr/tmp/} and you add @samp{/x1/rms/foo}, you get | |
106 @samp{/usr/tmp//x1/rms/foo}; but Emacs ignores everything through the | |
107 first slash in the double slash; the result is @samp{/x1/rms/foo}. | |
108 @xref{Minibuffer File}. | |
109 | |
110 @cindex home directory shorthand | |
111 You can use @file{~/} in a file name to mean your home directory, | |
112 or @file{~@var{user-id}/} to mean the home directory of a user whose | |
113 login name is @code{user-id}@footnote{ | |
114 On MS-Windows and MS-DOS systems, where a user doesn't have a home | |
115 directory, Emacs replaces @file{~/} with the value of the | |
116 environment variable @code{HOME}; see @ref{General Variables}. On | |
117 these systems, the @file{~@var{user-id}/} construct is supported only | |
118 for the current user, i.e., only if @var{user-id} is the current | |
119 user's login name.}. | |
120 | |
121 @cindex environment variables in file names | |
122 @cindex expansion of environment variables | |
123 @cindex @code{$} in file names | |
124 @anchor{File Names with $}@samp{$} in a file name is used to | |
125 substitute an environment variable. The environment variable name | |
126 consists of all the alphanumeric characters after the @samp{$}; | |
127 alternatively, it can be enclosed in braces after the @samp{$}. For | |
128 example, if you have used the shell command @command{export | |
129 FOO=rms/hacks} to set up an environment variable named @env{FOO}, then | |
130 you can use @file{/u/$FOO/test.c} or @file{/u/$@{FOO@}/test.c} as an | |
131 abbreviation for @file{/u/rms/hacks/test.c}. If the environment | |
132 variable is not defined, no substitution occurs: @file{/u/$notdefined} | |
133 stands for itself (assuming the environment variable @env{notdefined} | |
134 is not defined). | |
135 | |
136 Note that shell commands to set environment variables affect Emacs | |
137 only when done before Emacs is started. | |
138 | |
139 To access a file with @samp{$} in its name, if the @samp{$} causes | |
140 expansion, type @samp{$$}. This pair is converted to a single | |
141 @samp{$} at the same time as variable substitution is performed for a | |
142 single @samp{$}. Alternatively, quote the whole file name with | |
143 @samp{/:} (@pxref{Quoted File Names}). File names which begin with a | |
144 literal @samp{~} should also be quoted with @samp{/:}. | |
145 | |
146 @findex substitute-in-file-name | |
147 The Lisp function that performs the @samp{$}-substitution is called | |
148 @code{substitute-in-file-name}. The substitution is performed only on | |
149 file names read as such using the minibuffer. | |
150 | |
151 You can include non-@acronym{ASCII} characters in file names if you set the | |
152 variable @code{file-name-coding-system} to a non-@code{nil} value. | |
153 @xref{File Name Coding}. | |
154 | |
155 @node Visiting | |
156 @section Visiting Files | |
157 @cindex visiting files | |
158 @cindex open file | |
159 | |
160 @table @kbd | |
161 @item C-x C-f | |
162 Visit a file (@code{find-file}). | |
163 @item C-x C-r | |
164 Visit a file for viewing, without allowing changes to it | |
165 (@code{find-file-read-only}). | |
166 @item C-x C-v | |
167 Visit a different file instead of the one visited last | |
168 (@code{find-alternate-file}). | |
169 @item C-x 4 f | |
170 Visit a file, in another window (@code{find-file-other-window}). Don't | |
171 alter what is displayed in the selected window. | |
172 @item C-x 5 f | |
173 Visit a file, in a new frame (@code{find-file-other-frame}). Don't | |
174 alter what is displayed in the selected frame. | |
175 @item M-x find-file-literally | |
176 Visit a file with no conversion of the contents. | |
177 @end table | |
178 | |
179 @cindex files, visiting and saving | |
180 @cindex saving files | |
181 @dfn{Visiting} a file means reading its contents into an Emacs | |
182 buffer so you can edit them. Emacs makes a new buffer for each file | |
183 that you visit. We often say that this buffer ``is visiting'' that | |
184 file, or that the buffer's ``visited file'' is that file. Emacs | |
185 constructs the buffer name from the file name by throwing away the | |
186 directory, keeping just the name proper. For example, a file named | |
187 @file{/usr/rms/emacs.tex} would get a buffer named @samp{emacs.tex}. | |
188 If there is already a buffer with that name, Emacs constructs a unique | |
189 name---the normal method is to append @samp{<2>}, @samp{<3>}, and so | |
190 on, but you can select other methods (@pxref{Uniquify}). | |
191 | |
192 Each window's mode line shows the name of the buffer that is being displayed | |
193 in that window, so you can always tell what buffer you are editing. | |
194 | |
195 The changes you make with editing commands are made in the Emacs | |
196 buffer. They do not take effect in the file that you visited, or any | |
197 permanent place, until you @dfn{save} the buffer. Saving the buffer | |
198 means that Emacs writes the current contents of the buffer into its | |
199 visited file. @xref{Saving}. | |
200 | |
201 @cindex modified (buffer) | |
202 If a buffer contains changes that have not been saved, we say the | |
203 buffer is @dfn{modified}. This is important because it implies that | |
204 some changes will be lost if the buffer is not saved. The mode line | |
205 displays two stars near the left margin to indicate that the buffer is | |
206 modified. | |
207 | |
208 @kindex C-x C-f | |
209 @findex find-file | |
210 To visit a file, use the command @kbd{C-x C-f} (@code{find-file}). Follow | |
211 the command with the name of the file you wish to visit, terminated by a | |
212 @key{RET}. | |
213 | |
214 The file name is read using the minibuffer (@pxref{Minibuffer}), with | |
215 defaulting and completion in the standard manner (@pxref{File Names}). | |
216 While in the minibuffer, you can abort @kbd{C-x C-f} by typing | |
217 @kbd{C-g}. File-name completion ignores certain file names; for more | |
218 about this, see @ref{Completion Options}. | |
219 | |
220 Your confirmation that @kbd{C-x C-f} has completed successfully is | |
221 the appearance of new text on the screen and a new buffer name in the | |
222 mode line. If the specified file does not exist and you could not | |
223 create it, or exists but you can't read it, then you get an error, | |
224 with an error message displayed in the echo area. | |
225 | |
226 If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make | |
227 another copy. It selects the existing buffer containing that file. | |
228 However, before doing so, it checks whether the file itself has changed | |
229 since you visited or saved it last. If the file has changed, Emacs offers | |
230 to reread it. | |
231 | |
232 @vindex large-file-warning-threshold | |
233 @cindex maximum buffer size exceeded, error message | |
234 If you try to visit a file larger than | |
235 @code{large-file-warning-threshold} (the default is 10000000, which is | |
236 about 10 megabytes), Emacs will ask you for confirmation first. You | |
237 can answer @kbd{y} to proceed with visiting the file. Note, however, | |
238 that Emacs cannot visit files that are larger than the maximum Emacs | |
239 buffer size, which is around 256 megabytes on 32-bit machines | |
240 (@pxref{Buffers}). If you try, Emacs will display an error message | |
241 saying that the maximum buffer size has been exceeded. | |
242 | |
243 @cindex file selection dialog | |
244 On graphical displays there are two additional methods for | |
245 visiting files. Firstly, when Emacs is built with a suitable GUI | |
246 toolkit, commands invoked with the mouse (by clicking on the menu bar | |
247 or tool bar) use the toolkit's standard File Selection dialog instead | |
248 of prompting for the file name in the minibuffer. On Unix and | |
249 GNU/Linux platforms, Emacs does that when built with GTK, LessTif, and | |
250 Motif toolkits; on MS-Windows and Mac, the GUI version does that by default. | |
251 For information on how to customize this, see @ref{Dialog Boxes}. | |
252 | |
253 Secondly, Emacs supports ``drag and drop''; dropping a file into an | |
254 ordinary Emacs window visits the file using that window. However, | |
255 dropping a file into a window displaying a Dired buffer moves or | |
256 copies the file into the displayed directory. For details, see | |
257 @ref{Drag and Drop}, and @ref{Misc Dired Features}. | |
258 | |
259 @cindex creating files | |
260 What if you want to create a new file? Just visit it. Emacs displays | |
261 @samp{(New file)} in the echo area, but in other respects behaves as if | |
262 you had visited an existing empty file. If you make any changes and | |
263 save them, the file is created. | |
264 | |
265 Emacs recognizes from the contents of a file which end-of-line | |
266 convention it uses to separate lines---newline (used on GNU/Linux and | |
267 on Unix), carriage-return linefeed (used on Microsoft systems), or | |
268 just carriage-return (used on the Macintosh)---and automatically | |
269 converts the contents to the normal Emacs convention, which is that | |
270 the newline character separates lines. This is a part of the general | |
271 feature of coding system conversion (@pxref{Coding Systems}), and | |
272 makes it possible to edit files imported from different operating | |
273 systems with equal convenience. If you change the text and save the | |
274 file, Emacs performs the inverse conversion, changing newlines back | |
275 into carriage-return linefeed or just carriage-return if appropriate. | |
276 | |
277 @vindex find-file-run-dired | |
278 If the file you specify is actually a directory, @kbd{C-x C-f} invokes | |
279 Dired, the Emacs directory browser, so that you can ``edit'' the contents | |
280 of the directory (@pxref{Dired}). Dired is a convenient way to view, delete, | |
281 or operate on the files in the directory. However, if the variable | |
282 @code{find-file-run-dired} is @code{nil}, then it is an error to try | |
283 to visit a directory. | |
284 | |
285 Files which are actually collections of other files, or @dfn{file | |
286 archives}, are visited in special modes which invoke a Dired-like | |
287 environment to allow operations on archive members. @xref{File | |
288 Archives}, for more about these features. | |
289 | |
290 @cindex wildcard characters in file names | |
291 @vindex find-file-wildcards | |
292 If the file name you specify contains shell-style wildcard | |
293 characters, Emacs visits all the files that match it. (On | |
294 case-insensitive filesystems, Emacs matches the wildcards disregarding | |
295 the letter case.) Wildcards include @samp{?}, @samp{*}, and | |
296 @samp{[@dots{}]} sequences. To enter the wild card @samp{?} in a file | |
297 name in the minibuffer, you need to type @kbd{C-q ?}. @xref{Quoted | |
298 File Names}, for information on how to visit a file whose name | |
299 actually contains wildcard characters. You can disable the wildcard | |
300 feature by customizing @code{find-file-wildcards}. | |
301 | |
302 If you visit a file that the operating system won't let you modify, | |
303 or that is marked read-only, Emacs makes the buffer read-only too, so | |
304 that you won't go ahead and make changes that you'll have trouble | |
305 saving afterward. You can make the buffer writable with @kbd{C-x C-q} | |
306 (@code{toggle-read-only}). @xref{Misc Buffer}. | |
307 | |
308 @kindex C-x C-r | |
309 @findex find-file-read-only | |
310 If you want to visit a file as read-only in order to protect | |
311 yourself from entering changes accidentally, visit it with the command | |
312 @kbd{C-x C-r} (@code{find-file-read-only}) instead of @kbd{C-x C-f}. | |
313 | |
314 @kindex C-x C-v | |
315 @findex find-alternate-file | |
316 If you visit a nonexistent file unintentionally (because you typed the | |
317 wrong file name), use the @kbd{C-x C-v} command | |
318 (@code{find-alternate-file}) to visit the file you really wanted. | |
319 @kbd{C-x C-v} is similar to @kbd{C-x C-f}, but it kills the current | |
320 buffer (after first offering to save it if it is modified). When | |
321 @kbd{C-x C-v} reads the file name to visit, it inserts the entire | |
322 default file name in the buffer, with point just after the directory | |
323 part; this is convenient if you made a slight error in typing the name. | |
324 | |
325 @kindex C-x 4 f | |
326 @findex find-file-other-window | |
327 @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f} | |
328 except that the buffer containing the specified file is selected in another | |
329 window. The window that was selected before @kbd{C-x 4 f} continues to | |
330 show the same buffer it was already showing. If this command is used when | |
331 only one window is being displayed, that window is split in two, with one | |
332 window showing the same buffer as before, and the other one showing the | |
333 newly requested file. @xref{Windows}. | |
334 | |
335 @kindex C-x 5 f | |
336 @findex find-file-other-frame | |
337 @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a | |
338 new frame, or makes visible any existing frame showing the file you | |
339 seek. This feature is available only when you are using a window | |
340 system. @xref{Frames}. | |
341 | |
342 @findex find-file-literally | |
343 If you wish to edit a file as a sequence of @acronym{ASCII} characters with no special | |
344 encoding or conversion, use the @kbd{M-x find-file-literally} command. | |
345 It visits a file, like @kbd{C-x C-f}, but does not do format conversion | |
346 (@pxref{Formatted Text}), character code conversion (@pxref{Coding | |
347 Systems}), or automatic uncompression (@pxref{Compressed Files}), and | |
348 does not add a final newline because of @code{require-final-newline}. | |
349 If you already have visited the same file in the usual (non-literal) | |
350 manner, this command asks you whether to visit it literally instead. | |
351 | |
352 @vindex find-file-hook | |
353 @vindex find-file-not-found-functions | |
354 Two special hook variables allow extensions to modify the operation of | |
355 visiting files. Visiting a file that does not exist runs the functions | |
356 in the list @code{find-file-not-found-functions}; this variable holds a list | |
357 of functions, and the functions are called one by one (with no | |
358 arguments) until one of them returns non-@code{nil}. This is not a | |
359 normal hook, and the name ends in @samp{-functions} rather than @samp{-hook} | |
360 to indicate that fact. | |
361 | |
362 Successful visiting of any file, whether existing or not, calls the | |
363 functions in the list @code{find-file-hook}, with no arguments. | |
364 This variable is a normal hook. In the case of a nonexistent file, the | |
365 @code{find-file-not-found-functions} are run first. @xref{Hooks}. | |
366 | |
367 There are several ways to specify automatically the major mode for | |
368 editing the file (@pxref{Choosing Modes}), and to specify local | |
369 variables defined for that file (@pxref{File Variables}). | |
370 | |
371 @node Saving | |
372 @section Saving Files | |
373 | |
374 @dfn{Saving} a buffer in Emacs means writing its contents back into the file | |
375 that was visited in the buffer. | |
376 | |
377 @menu | |
378 * Save Commands:: Commands for saving files. | |
379 * Backup:: How Emacs saves the old version of your file. | |
380 * Customize Save:: Customizing the saving of files. | |
381 * Interlocking:: How Emacs protects against simultaneous editing | |
382 of one file by two users. | |
383 * Shadowing: File Shadowing. Copying files to "shadows" automatically. | |
384 * Time Stamps:: Emacs can update time stamps on saved files. | |
385 @end menu | |
386 | |
387 @node Save Commands | |
388 @subsection Commands for Saving Files | |
389 | |
390 These are the commands that relate to saving and writing files. | |
391 | |
392 @table @kbd | |
393 @item C-x C-s | |
394 Save the current buffer in its visited file on disk (@code{save-buffer}). | |
395 @item C-x s | |
396 Save any or all buffers in their visited files (@code{save-some-buffers}). | |
397 @item M-~ | |
398 Forget that the current buffer has been changed (@code{not-modified}). | |
399 With prefix argument (@kbd{C-u}), mark the current buffer as changed. | |
400 @item C-x C-w | |
401 Save the current buffer with a specified file name (@code{write-file}). | |
402 @item M-x set-visited-file-name | |
403 Change the file name under which the current buffer will be saved. | |
404 @end table | |
405 | |
406 @kindex C-x C-s | |
407 @findex save-buffer | |
408 When you wish to save the file and make your changes permanent, type | |
409 @kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s} | |
410 displays a message like this: | |
411 | |
412 @example | |
413 Wrote /u/rms/gnu/gnu.tasks | |
414 @end example | |
415 | |
416 @noindent | |
417 If the selected buffer is not modified (no changes have been made in it | |
418 since the buffer was created or last saved), saving is not really done, | |
419 because it would have no effect. Instead, @kbd{C-x C-s} displays a message | |
420 like this in the echo area: | |
421 | |
422 @example | |
423 (No changes need to be saved) | |
424 @end example | |
425 | |
426 @kindex C-x s | |
427 @findex save-some-buffers | |
428 The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any | |
429 or all modified buffers. It asks you what to do with each buffer. The | |
430 possible responses are analogous to those of @code{query-replace}: | |
431 | |
432 @table @kbd | |
433 @item y | |
434 Save this buffer and ask about the rest of the buffers. | |
435 @item n | |
436 Don't save this buffer, but ask about the rest of the buffers. | |
437 @item ! | |
438 Save this buffer and all the rest with no more questions. | |
439 @c following generates acceptable underfull hbox | |
440 @item @key{RET} | |
441 Terminate @code{save-some-buffers} without any more saving. | |
442 @item . | |
443 Save this buffer, then exit @code{save-some-buffers} without even asking | |
444 about other buffers. | |
445 @item C-r | |
446 View the buffer that you are currently being asked about. When you exit | |
447 View mode, you get back to @code{save-some-buffers}, which asks the | |
448 question again. | |
449 @item d | |
450 Diff the buffer against its corresponding file, so you can see | |
451 what changes you would be saving. | |
452 @item C-h | |
453 Display a help message about these options. | |
454 @end table | |
455 | |
456 @kbd{C-x C-c}, the key sequence to exit Emacs, invokes | |
457 @code{save-some-buffers} and therefore asks the same questions. | |
458 | |
459 @kindex M-~ | |
460 @findex not-modified | |
461 If you have changed a buffer but you do not want to save the changes, | |
462 you should take some action to prevent it. Otherwise, each time you use | |
463 @kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer by | |
464 mistake. One thing you can do is type @kbd{M-~} (@code{not-modified}), | |
465 which clears out the indication that the buffer is modified. If you do | |
466 this, none of the save commands will believe that the buffer needs to be | |
467 saved. (@samp{~} is often used as a mathematical symbol for `not'; thus | |
468 @kbd{M-~} is `not', metafied.) You could also use | |
469 @code{set-visited-file-name} (see below) to mark the buffer as visiting | |
470 a different file name, one which is not in use for anything important. | |
471 Alternatively, you can cancel all the changes made since the file was | |
472 visited or saved, by reading the text from the file again. This is | |
473 called @dfn{reverting}. @xref{Reverting}. (You could also undo all the | |
474 changes by repeating the undo command @kbd{C-x u} until you have undone | |
475 all the changes; but reverting is easier.) You can also kill the buffer. | |
476 | |
477 @findex set-visited-file-name | |
478 @kbd{M-x set-visited-file-name} alters the name of the file that the | |
479 current buffer is visiting. It reads the new file name using the | |
480 minibuffer. Then it marks the buffer as visiting that file name, and | |
481 changes the buffer name correspondingly. @code{set-visited-file-name} | |
482 does not save the buffer in the newly visited file; it just alters the | |
483 records inside Emacs in case you do save later. It also marks the | |
484 buffer as ``modified'' so that @kbd{C-x C-s} in that buffer | |
485 @emph{will} save. | |
486 | |
487 @kindex C-x C-w | |
488 @findex write-file | |
489 If you wish to mark the buffer as visiting a different file and save it | |
490 right away, use @kbd{C-x C-w} (@code{write-file}). It is | |
491 equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s} | |
492 (except that @kbd{C-x C-w} asks for confirmation if the file exists). | |
493 @kbd{C-x C-s} used on a buffer that is not visiting a file has the | |
494 same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the | |
495 buffer as visiting that file, and saves it there. The default file name in | |
496 a buffer that is not visiting a file is made by combining the buffer name | |
497 with the buffer's default directory (@pxref{File Names}). | |
498 | |
499 If the new file name implies a major mode, then @kbd{C-x C-w} switches | |
500 to that major mode, in most cases. The command | |
501 @code{set-visited-file-name} also does this. @xref{Choosing Modes}. | |
502 | |
503 If Emacs is about to save a file and sees that the date of the latest | |
504 version on disk does not match what Emacs last read or wrote, Emacs | |
505 notifies you of this fact, because it probably indicates a problem caused | |
506 by simultaneous editing and requires your immediate attention. | |
507 @xref{Interlocking,, Simultaneous Editing}. | |
508 | |
509 @node Backup | |
510 @subsection Backup Files | |
511 @cindex backup file | |
512 @vindex make-backup-files | |
513 @vindex vc-make-backup-files | |
514 | |
515 On most operating systems, rewriting a file automatically destroys all | |
516 record of what the file used to contain. Thus, saving a file from Emacs | |
517 throws away the old contents of the file---or it would, except that | |
518 Emacs carefully copies the old contents to another file, called the | |
519 @dfn{backup} file, before actually saving. | |
520 | |
521 For most files, the variable @code{make-backup-files} determines | |
522 whether to make backup files. On most operating systems, its default | |
523 value is @code{t}, so that Emacs does write backup files. | |
524 | |
525 For files managed by a version control system (@pxref{Version | |
526 Control}), the variable @code{vc-make-backup-files} determines whether | |
527 to make backup files. By default it is @code{nil}, since backup files | |
528 are redundant when you store all the previous versions in a version | |
529 control system. | |
530 @iftex | |
531 @xref{General VC Options,,,emacs-xtra, Specialized Emacs Features}. | |
532 @end iftex | |
533 @ifnottex | |
534 @xref{General VC Options}. | |
535 @end ifnottex | |
536 | |
537 | |
538 At your option, Emacs can keep either a single backup for each file, | |
539 or make a series of numbered backup files for each file that you edit. | |
540 | |
541 @vindex backup-enable-predicate | |
542 @vindex temporary-file-directory | |
543 @vindex small-temporary-file-directory | |
544 The default value of the @code{backup-enable-predicate} variable | |
545 prevents backup files being written for files in the directories used | |
546 for temporary files, specified by @code{temporary-file-directory} or | |
547 @code{small-temporary-file-directory}. | |
548 | |
549 Emacs makes a backup for a file only the first time the file is saved | |
550 from one buffer. No matter how many times you save a file, its backup file | |
551 continues to contain the contents from before the file was visited. | |
552 Normally this means that the backup file contains the contents from before | |
553 the current editing session; however, if you kill the buffer and then visit | |
554 the file again, a new backup file will be made by the next save. | |
555 | |
556 You can also explicitly request making another backup file from a | |
557 buffer even though it has already been saved at least once. If you save | |
558 the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made | |
559 into a backup file if you save the buffer again. @kbd{C-u C-u C-x C-s} | |
560 saves the buffer, but first makes the previous file contents into a new | |
561 backup file. @kbd{C-u C-u C-u C-x C-s} does both things: it makes a | |
562 backup from the previous contents, and arranges to make another from the | |
563 newly saved contents if you save again. | |
564 | |
565 @menu | |
566 * One or Many: Numbered Backups. Whether to make one backup file or many. | |
567 * Names: Backup Names. How backup files are named. | |
568 * Deletion: Backup Deletion. Emacs deletes excess numbered backups. | |
569 * Copying: Backup Copying. Backups can be made by copying or renaming. | |
570 @end menu | |
571 | |
572 @node Numbered Backups | |
573 @subsubsection Numbered Backups | |
574 | |
575 @vindex version-control | |
576 The choice of single backup file or multiple numbered backup files | |
577 is controlled by the variable @code{version-control}. Its possible | |
578 values are: | |
579 | |
580 @table @code | |
581 @item t | |
582 Make numbered backups. | |
583 @item nil | |
584 Make numbered backups for files that have numbered backups already. | |
585 Otherwise, make single backups. | |
586 @item never | |
587 Never make numbered backups; always make single backups. | |
588 @end table | |
589 | |
590 @noindent | |
591 The usual way to set this variable is globally, through your | |
592 @file{.emacs} file or the customization buffer. However, you can set | |
593 @code{version-control} locally in an individual buffer to control the | |
594 making of backups for that buffer's file. For example, Rmail mode | |
595 locally sets @code{version-control} to @code{never} to make sure that | |
596 there is only one backup for an Rmail file. @xref{Locals}. | |
597 | |
598 @cindex @env{VERSION_CONTROL} environment variable | |
599 If you set the environment variable @env{VERSION_CONTROL}, to tell | |
600 various GNU utilities what to do with backup files, Emacs also obeys the | |
601 environment variable by setting the Lisp variable @code{version-control} | |
602 accordingly at startup. If the environment variable's value is @samp{t} | |
603 or @samp{numbered}, then @code{version-control} becomes @code{t}; if the | |
604 value is @samp{nil} or @samp{existing}, then @code{version-control} | |
605 becomes @code{nil}; if it is @samp{never} or @samp{simple}, then | |
606 @code{version-control} becomes @code{never}. | |
607 | |
608 @node Backup Names | |
609 @subsubsection Single or Numbered Backups | |
610 | |
611 When Emacs makes a single backup file, its name is normally | |
612 constructed by appending @samp{~} to the file name being edited; thus, | |
613 the backup file for @file{eval.c} would be @file{eval.c~}. | |
614 | |
615 @vindex make-backup-file-name-function | |
616 @vindex backup-directory-alist | |
617 You can change this behavior by defining the variable | |
618 @code{make-backup-file-name-function} to a suitable function. | |
619 Alternatively you can customize the variable | |
620 @code{backup-directory-alist} to specify that files matching certain | |
621 patterns should be backed up in specific directories. | |
622 | |
623 A typical use is to add an element @code{("." . @var{dir})} to make | |
624 all backups in the directory with absolute name @var{dir}; Emacs | |
625 modifies the backup file names to avoid clashes between files with the | |
626 same names originating in different directories. Alternatively, | |
627 adding, say, @code{("." . ".~")} would make backups in the invisible | |
628 subdirectory @file{.~} of the original file's directory. Emacs | |
629 creates the directory, if necessary, to make the backup. | |
630 | |
631 If access control stops Emacs from writing backup files under the usual | |
632 names, it writes the backup file as @file{%backup%~} in your home | |
633 directory. Only one such file can exist, so only the most recently | |
634 made such backup is available. | |
635 | |
636 If you choose to have a series of numbered backup files, backup file | |
637 names contain @samp{.~}, the number, and another @samp{~} after the | |
638 original file name. Thus, the backup files of @file{eval.c} would be | |
639 called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, all the way | |
640 through names like @file{eval.c.~259~} and beyond. The variable | |
641 @code{backup-directory-alist} applies to numbered backups just as | |
642 usual. | |
643 | |
644 @node Backup Deletion | |
645 @subsubsection Automatic Deletion of Backups | |
646 | |
647 To prevent excessive consumption of disk space, Emacs can delete numbered | |
648 backup versions automatically. Generally Emacs keeps the first few backups | |
649 and the latest few backups, deleting any in between. This happens every | |
650 time a new backup is made. | |
651 | |
652 @vindex kept-old-versions | |
653 @vindex kept-new-versions | |
654 The two variables @code{kept-old-versions} and | |
655 @code{kept-new-versions} control this deletion. Their values are, | |
656 respectively, the number of oldest (lowest-numbered) backups to keep | |
657 and the number of newest (highest-numbered) ones to keep, each time a | |
658 new backup is made. The backups in the middle (excluding those oldest | |
659 and newest) are the excess middle versions---those backups are | |
660 deleted. These variables' values are used when it is time to delete | |
661 excess versions, just after a new backup version is made; the newly | |
662 made backup is included in the count in @code{kept-new-versions}. By | |
663 default, both variables are 2. | |
664 | |
665 @vindex delete-old-versions | |
666 If @code{delete-old-versions} is @code{t}, Emacs deletes the excess | |
667 backup files silently. If it is @code{nil}, the default, Emacs asks | |
668 you whether it should delete the excess backup versions. If it has | |
669 any other value, then Emacs never automatically deletes backups. | |
670 | |
671 Dired's @kbd{.} (Period) command can also be used to delete old versions. | |
672 @xref{Dired Deletion}. | |
673 | |
674 @node Backup Copying | |
675 @subsubsection Copying vs.@: Renaming | |
676 | |
677 Backup files can be made by copying the old file or by renaming it. | |
678 This makes a difference when the old file has multiple names (hard | |
679 links). If the old file is renamed into the backup file, then the | |
680 alternate names become names for the backup file. If the old file is | |
681 copied instead, then the alternate names remain names for the file | |
682 that you are editing, and the contents accessed by those names will be | |
683 the new contents. | |
684 | |
685 The method of making a backup file may also affect the file's owner | |
686 and group. If copying is used, these do not change. If renaming is used, | |
687 you become the file's owner, and the file's group becomes the default | |
688 (different operating systems have different defaults for the group). | |
689 | |
690 Having the owner change is usually a good idea, because then the owner | |
691 always shows who last edited the file. Also, the owners of the backups | |
692 show who produced those versions. Occasionally there is a file whose | |
693 owner should not change; it is a good idea for such files to contain | |
694 local variable lists to set @code{backup-by-copying-when-mismatch} | |
695 locally (@pxref{File Variables}). | |
696 | |
697 @vindex backup-by-copying | |
698 @vindex backup-by-copying-when-linked | |
699 @vindex backup-by-copying-when-mismatch | |
700 @vindex backup-by-copying-when-privileged-mismatch | |
701 @cindex file ownership, and backup | |
702 @cindex backup, and user-id | |
703 The choice of renaming or copying is controlled by four variables. | |
704 Renaming is the default choice. If the variable | |
705 @code{backup-by-copying} is non-@code{nil}, copying is used. Otherwise, | |
706 if the variable @code{backup-by-copying-when-linked} is non-@code{nil}, | |
707 then copying is used for files that have multiple names, but renaming | |
708 may still be used when the file being edited has only one name. If the | |
709 variable @code{backup-by-copying-when-mismatch} is non-@code{nil}, then | |
710 copying is used if renaming would cause the file's owner or group to | |
711 change. @code{backup-by-copying-when-mismatch} is @code{t} by default | |
712 if you start Emacs as the superuser. The fourth variable, | |
713 @code{backup-by-copying-when-privileged-mismatch}, gives the highest | |
714 numeric user-id for which @code{backup-by-copying-when-mismatch} will be | |
715 forced on. This is useful when low-numbered user-ids are assigned to | |
716 special system users, such as @code{root}, @code{bin}, @code{daemon}, | |
717 etc., which must maintain ownership of files. | |
718 | |
719 When a file is managed with a version control system (@pxref{Version | |
720 Control}), Emacs does not normally make backups in the usual way for | |
721 that file. But check-in and check-out are similar in some ways to | |
722 making backups. One unfortunate similarity is that these operations | |
723 typically break hard links, disconnecting the file name you visited from | |
724 any alternate names for the same file. This has nothing to do with | |
725 Emacs---the version control system does it. | |
726 | |
727 @node Customize Save | |
728 @subsection Customizing Saving of Files | |
729 | |
730 @vindex require-final-newline | |
731 If the value of the variable @code{require-final-newline} is | |
732 @code{t}, saving or writing a file silently puts a newline at the end | |
733 if there isn't already one there. If the value is @code{visit}, Emacs | |
734 adds a newline at the end of any file that doesn't have one, just | |
735 after it visits the file. (This marks the buffer as modified, and you | |
736 can undo it.) If the value is @code{visit-save}, that means to add | |
737 newlines both on visiting and on saving. If the value is @code{nil}, | |
738 Emacs leaves the end of the file unchanged; if it's neither @code{nil} | |
739 nor @code{t}, Emacs asks you whether to add a newline. The default is | |
740 @code{nil}. | |
741 | |
742 @vindex mode-require-final-newline | |
743 Many major modes are designed for specific kinds of files that are | |
744 always supposed to end in newlines. These major modes set the | |
745 variable @code{require-final-newline} according to | |
746 @code{mode-require-final-newline}. By setting the latter variable, | |
747 you can control how these modes handle final newlines. | |
748 | |
749 @vindex write-region-inhibit-fsync | |
750 When Emacs saves a file, it invokes the @code{fsync} system call to | |
751 force the data immediately out to disk. This is important for safety | |
752 if the system crashes or in case of power outage. However, it can be | |
753 disruptive on laptops using power saving, because it requires the disk | |
754 to spin up each time you save a file. Setting | |
755 @code{write-region-inhibit-fsync} to a non-@code{nil} value disables | |
756 this synchronization. Be careful---this means increased risk of data | |
757 loss. | |
758 | |
759 @node Interlocking | |
760 @subsection Protection against Simultaneous Editing | |
761 | |
762 @cindex file dates | |
763 @cindex simultaneous editing | |
764 Simultaneous editing occurs when two users visit the same file, both | |
765 make changes, and then both save them. If nobody were informed that | |
766 this was happening, whichever user saved first would later find that his | |
767 changes were lost. | |
768 | |
769 On some systems, Emacs notices immediately when the second user starts | |
770 to change the file, and issues an immediate warning. On all systems, | |
771 Emacs checks when you save the file, and warns if you are about to | |
772 overwrite another user's changes. You can prevent loss of the other | |
773 user's work by taking the proper corrective action instead of saving the | |
774 file. | |
775 | |
776 @findex ask-user-about-lock | |
777 @cindex locking files | |
778 When you make the first modification in an Emacs buffer that is | |
779 visiting a file, Emacs records that the file is @dfn{locked} by you. | |
780 (It does this by creating a symbolic link in the same directory with a | |
781 different name.) Emacs removes the lock when you save the changes. The | |
782 idea is that the file is locked whenever an Emacs buffer visiting it has | |
783 unsaved changes. | |
784 | |
785 @cindex collision | |
786 If you begin to modify the buffer while the visited file is locked by | |
787 someone else, this constitutes a @dfn{collision}. When Emacs detects a | |
788 collision, it asks you what to do, by calling the Lisp function | |
789 @code{ask-user-about-lock}. You can redefine this function for the sake | |
790 of customization. The standard definition of this function asks you a | |
791 question and accepts three possible answers: | |
792 | |
793 @table @kbd | |
794 @item s | |
795 Steal the lock. Whoever was already changing the file loses the lock, | |
796 and you gain the lock. | |
797 @item p | |
798 Proceed. Go ahead and edit the file despite its being locked by someone else. | |
799 @item q | |
800 Quit. This causes an error (@code{file-locked}), and the buffer | |
801 contents remain unchanged---the modification you were trying to make | |
802 does not actually take place. | |
803 @end table | |
804 | |
805 Note that locking works on the basis of a file name; if a file has | |
806 multiple names, Emacs does not realize that the two names are the same file | |
807 and cannot prevent two users from editing it simultaneously under different | |
808 names. However, basing locking on names means that Emacs can interlock the | |
809 editing of new files that will not really exist until they are saved. | |
810 | |
811 Some systems are not configured to allow Emacs to make locks, and | |
812 there are cases where lock files cannot be written. In these cases, | |
813 Emacs cannot detect trouble in advance, but it still can detect the | |
814 collision when you try to save a file and overwrite someone else's | |
815 changes. | |
816 | |
817 If Emacs or the operating system crashes, this may leave behind lock | |
818 files which are stale, so you may occasionally get warnings about | |
819 spurious collisions. When you determine that the collision is spurious, | |
820 just use @kbd{p} to tell Emacs to go ahead anyway. | |
821 | |
822 Every time Emacs saves a buffer, it first checks the last-modification | |
823 date of the existing file on disk to verify that it has not changed since the | |
824 file was last visited or saved. If the date does not match, it implies | |
825 that changes were made in the file in some other way, and these changes are | |
826 about to be lost if Emacs actually does save. To prevent this, Emacs | |
827 displays a warning message and asks for confirmation before saving. | |
828 Occasionally you will know why the file was changed and know that it does | |
829 not matter; then you can answer @kbd{yes} and proceed. Otherwise, you should | |
830 cancel the save with @kbd{C-g} and investigate the situation. | |
831 | |
832 The first thing you should do when notified that simultaneous editing | |
833 has already taken place is to list the directory with @kbd{C-u C-x C-d} | |
834 (@pxref{Directories}). This shows the file's current author. You | |
835 should attempt to contact him to warn him not to continue editing. | |
836 Often the next step is to save the contents of your Emacs buffer under a | |
837 different name, and use @code{diff} to compare the two files.@refill | |
838 | |
839 @node File Shadowing | |
840 @subsection Shadowing Files | |
841 @cindex shadow files | |
842 @cindex file shadows | |
843 @findex shadow-initialize | |
844 | |
845 @table @kbd | |
846 @item M-x shadow-initialize | |
847 Set up file shadowing. | |
848 @item M-x shadow-define-literal-group | |
849 Declare a single file to be shared between sites. | |
850 @item M-x shadow-define-regexp-group | |
851 Make all files that match each of a group of files be shared between hosts. | |
852 @item M-x shadow-define-cluster @key{RET} @var{name} @key{RET} | |
853 Define a shadow file cluster @var{name}. | |
854 @item M-x shadow-copy-files | |
855 Copy all pending shadow files. | |
856 @item M-x shadow-cancel | |
857 Cancel the instruction to shadow some files. | |
858 @end table | |
859 | |
860 You can arrange to keep identical @dfn{shadow} copies of certain files | |
861 in more than one place---possibly on different machines. To do this, | |
862 first you must set up a @dfn{shadow file group}, which is a set of | |
863 identically-named files shared between a list of sites. The file | |
864 group is permanent and applies to further Emacs sessions as well as | |
865 the current one. Once the group is set up, every time you exit Emacs, | |
866 it will copy the file you edited to the other files in its group. You | |
867 can also do the copying without exiting Emacs, by typing @kbd{M-x | |
868 shadow-copy-files}. | |
869 | |
870 To set up a shadow file group, use @kbd{M-x | |
871 shadow-define-literal-group} or @kbd{M-x shadow-define-regexp-group}. | |
872 See their documentation strings for further information. | |
873 | |
874 Before copying a file to its shadows, Emacs asks for confirmation. | |
875 You can answer ``no'' to bypass copying of this file, this time. If | |
876 you want to cancel the shadowing permanently for a certain file, use | |
877 @kbd{M-x shadow-cancel} to eliminate or change the shadow file group. | |
878 | |
879 A @dfn{shadow cluster} is a group of hosts that share directories, so | |
880 that copying to or from one of them is sufficient to update the file | |
881 on all of them. Each shadow cluster has a name, and specifies the | |
882 network address of a primary host (the one we copy files to), and a | |
883 regular expression that matches the host names of all the other hosts | |
884 in the cluster. You can define a shadow cluster with @kbd{M-x | |
885 shadow-define-cluster}. | |
886 | |
887 @node Time Stamps | |
888 @subsection Updating Time Stamps Automatically | |
889 @cindex time stamps | |
890 @cindex modification dates | |
891 @cindex locale, date format | |
892 | |
893 You can arrange to put a time stamp in a file, so that it will be updated | |
894 automatically each time you edit and save the file. The time stamp | |
895 has to be in the first eight lines of the file, and you should | |
896 insert it like this: | |
897 | |
898 @example | |
899 Time-stamp: <> | |
900 @end example | |
901 | |
902 @noindent | |
903 or like this: | |
904 | |
905 @example | |
906 Time-stamp: " " | |
907 @end example | |
908 | |
909 @findex time-stamp | |
910 Then add the hook function @code{time-stamp} to the hook | |
911 @code{before-save-hook}; that hook function will automatically update | |
912 the time stamp, inserting the current date and time when you save the | |
913 file. You can also use the command @kbd{M-x time-stamp} to update the | |
914 time stamp manually. For other customizations, see the Custom group | |
915 @code{time-stamp}. Note that non-numeric fields in the time stamp are | |
916 formatted according to your locale setting (@pxref{Environment}). | |
917 | |
918 @node Reverting | |
919 @section Reverting a Buffer | |
920 @findex revert-buffer | |
921 @cindex drastic changes | |
922 @cindex reread a file | |
923 | |
924 If you have made extensive changes to a file and then change your mind | |
925 about them, you can get rid of them by reading in the previous version | |
926 of the file. To do this, use @kbd{M-x revert-buffer}, which operates on | |
927 the current buffer. Since reverting a buffer unintentionally could lose | |
928 a lot of work, you must confirm this command with @kbd{yes}. | |
929 | |
930 @code{revert-buffer} tries to position point in such a way that, if | |
931 the file was edited only slightly, you will be at approximately the | |
932 same piece of text after reverting as before. However, if you have made | |
933 drastic changes, point may wind up in a totally different piece of text. | |
934 | |
935 Reverting marks the buffer as ``not modified'' until another change is | |
936 made. | |
937 | |
938 Some kinds of buffers whose contents reflect data bases other than files, | |
939 such as Dired buffers, can also be reverted. For them, reverting means | |
940 recalculating their contents from the appropriate data base. Buffers | |
941 created explicitly with @kbd{C-x b} cannot be reverted; @code{revert-buffer} | |
942 reports an error when asked to do so. | |
943 | |
944 @vindex revert-without-query | |
945 When you edit a file that changes automatically and frequently---for | |
946 example, a log of output from a process that continues to run---it may be | |
947 useful for Emacs to revert the file without querying you, whenever you | |
948 visit the file again with @kbd{C-x C-f}. | |
949 | |
950 To request this behavior, set the variable @code{revert-without-query} | |
951 to a list of regular expressions. When a file name matches one of these | |
952 regular expressions, @code{find-file} and @code{revert-buffer} will | |
953 revert it automatically if it has changed---provided the buffer itself | |
954 is not modified. (If you have edited the text, it would be wrong to | |
955 discard your changes.) | |
956 | |
957 @cindex Global Auto-Revert mode | |
958 @cindex mode, Global Auto-Revert | |
959 @cindex Auto-Revert mode | |
960 @cindex mode, Auto-Revert | |
961 @findex global-auto-revert-mode | |
962 @findex auto-revert-mode | |
963 @findex auto-revert-tail-mode | |
964 | |
965 You may find it useful to have Emacs revert files automatically when | |
966 they change. Three minor modes are available to do this. | |
967 | |
968 @kbd{M-x global-auto-revert-mode} enables Global Auto-Revert mode, | |
969 which periodically checks all file buffers and reverts when the | |
970 corresponding file has changed. @kbd{M-x auto-revert-mode} enables a | |
971 local version, Auto-Revert mode, which applies only to the current | |
972 buffer. | |
973 | |
974 You can use Auto-Revert mode to ``tail'' a file such as a system | |
975 log, so that changes made to that file by other programs are | |
976 continuously displayed. To do this, just move the point to the end of | |
977 the buffer, and it will stay there as the file contents change. | |
978 However, if you are sure that the file will only change by growing at | |
979 the end, use Auto-Revert Tail mode instead | |
980 (@code{auto-revert-tail-mode}). It is more efficient for this. | |
981 | |
982 @vindex auto-revert-interval | |
983 The variable @code{auto-revert-interval} controls how often to check | |
984 for a changed file. Since checking a remote file is too slow, these | |
985 modes do not check or revert remote files. | |
986 | |
987 @xref{VC Mode Line}, for Auto Revert peculiarities in buffers that | |
988 visit files under version control. | |
989 | |
990 @ifnottex | |
991 @include arevert-xtra.texi | |
992 @end ifnottex | |
993 | |
994 @node Auto Save | |
995 @section Auto-Saving: Protection Against Disasters | |
996 @cindex Auto Save mode | |
997 @cindex mode, Auto Save | |
998 @cindex crashes | |
999 | |
87453 | 1000 Emacs saves all the visited files from time to time (based on |
1001 counting your keystrokes) without being asked, in separate files so as | |
1002 not to alter the files you actually use. This is called | |
1003 @dfn{auto-saving}. It prevents you from losing more than a limited | |
1004 amount of work if the system crashes. | |
84239 | 1005 |
1006 When Emacs determines that it is time for auto-saving, it considers | |
1007 each buffer, and each is auto-saved if auto-saving is enabled for it | |
1008 and it has been changed since the last time it was auto-saved. The | |
1009 message @samp{Auto-saving...} is displayed in the echo area during | |
1010 auto-saving, if any files are actually auto-saved. Errors occurring | |
1011 during auto-saving are caught so that they do not interfere with the | |
1012 execution of commands you have been typing. | |
1013 | |
1014 @menu | |
1015 * Files: Auto Save Files. The file where auto-saved changes are | |
1016 actually made until you save the file. | |
1017 * Control: Auto Save Control. Controlling when and how often to auto-save. | |
1018 * Recover:: Recovering text from auto-save files. | |
1019 @end menu | |
1020 | |
1021 @node Auto Save Files | |
1022 @subsection Auto-Save Files | |
1023 | |
1024 Auto-saving does not normally save in the files that you visited, because | |
1025 it can be very undesirable to save a program that is in an inconsistent | |
1026 state when you have made half of a planned change. Instead, auto-saving | |
1027 is done in a different file called the @dfn{auto-save file}, and the | |
1028 visited file is changed only when you request saving explicitly (such as | |
1029 with @kbd{C-x C-s}). | |
1030 | |
1031 Normally, the auto-save file name is made by appending @samp{#} to the | |
1032 front and rear of the visited file name. Thus, a buffer visiting file | |
1033 @file{foo.c} is auto-saved in a file @file{#foo.c#}. Most buffers that | |
1034 are not visiting files are auto-saved only if you request it explicitly; | |
1035 when they are auto-saved, the auto-save file name is made by appending | |
1036 @samp{#} to the front and rear of buffer name, then | |
1037 adding digits and letters at the end for uniqueness. For | |
1038 example, the @samp{*mail*} buffer in which you compose messages to be | |
1039 sent might be auto-saved in a file named @file{#*mail*#704juu}. Auto-save file | |
1040 names are made this way unless you reprogram parts of Emacs to do | |
1041 something different (the functions @code{make-auto-save-file-name} and | |
1042 @code{auto-save-file-name-p}). The file name to be used for auto-saving | |
1043 in a buffer is calculated when auto-saving is turned on in that buffer. | |
1044 | |
1045 @cindex auto-save for remote files | |
1046 @vindex auto-save-file-name-transforms | |
1047 The variable @code{auto-save-file-name-transforms} allows a degree | |
1048 of control over the auto-save file name. It lets you specify a series | |
1049 of regular expressions and replacements to transform the auto save | |
1050 file name. The default value puts the auto-save files for remote | |
1051 files (@pxref{Remote Files}) into the temporary file directory on the | |
1052 local machine. | |
1053 | |
1054 When you delete a substantial part of the text in a large buffer, auto | |
1055 save turns off temporarily in that buffer. This is because if you | |
1056 deleted the text unintentionally, you might find the auto-save file more | |
1057 useful if it contains the deleted text. To reenable auto-saving after | |
1058 this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x | |
1059 auto-save-mode}. | |
1060 | |
1061 @vindex auto-save-visited-file-name | |
1062 If you want auto-saving to be done in the visited file rather than | |
1063 in a separate auto-save file, set the variable | |
1064 @code{auto-save-visited-file-name} to a non-@code{nil} value. In this | |
1065 mode, there is no real difference between auto-saving and explicit | |
1066 saving. | |
1067 | |
1068 @vindex delete-auto-save-files | |
1069 A buffer's auto-save file is deleted when you save the buffer in its | |
1070 visited file. (You can inhibit this by setting the variable | |
1071 @code{delete-auto-save-files} to @code{nil}.) Changing the visited | |
1072 file name with @kbd{C-x C-w} or @code{set-visited-file-name} renames | |
1073 any auto-save file to go with the new visited name. | |
1074 | |
1075 @node Auto Save Control | |
1076 @subsection Controlling Auto-Saving | |
1077 | |
1078 @vindex auto-save-default | |
1079 @findex auto-save-mode | |
1080 Each time you visit a file, auto-saving is turned on for that file's | |
1081 buffer if the variable @code{auto-save-default} is non-@code{nil} (but not | |
1082 in batch mode; @pxref{Entering Emacs}). The default for this variable is | |
1083 @code{t}, so auto-saving is the usual practice for file-visiting buffers. | |
1084 Auto-saving can be turned on or off for any existing buffer with the | |
1085 command @kbd{M-x auto-save-mode}. Like other minor mode commands, @kbd{M-x | |
1086 auto-save-mode} turns auto-saving on with a positive argument, off with a | |
1087 zero or negative argument; with no argument, it toggles. | |
1088 | |
1089 @vindex auto-save-interval | |
1090 Emacs does auto-saving periodically based on counting how many characters | |
1091 you have typed since the last time auto-saving was done. The variable | |
1092 @code{auto-save-interval} specifies how many characters there are between | |
1093 auto-saves. By default, it is 300. Emacs doesn't accept values that are | |
1094 too small: if you customize @code{auto-save-interval} to a value less | |
1095 than 20, Emacs will behave as if the value is 20. | |
1096 | |
1097 @vindex auto-save-timeout | |
1098 Auto-saving also takes place when you stop typing for a while. The | |
1099 variable @code{auto-save-timeout} says how many seconds Emacs should | |
1100 wait before it does an auto save (and perhaps also a garbage | |
1101 collection). (The actual time period is longer if the current buffer is | |
1102 long; this is a heuristic which aims to keep out of your way when you | |
1103 are editing long buffers, in which auto-save takes an appreciable amount | |
1104 of time.) Auto-saving during idle periods accomplishes two things: | |
1105 first, it makes sure all your work is saved if you go away from the | |
1106 terminal for a while; second, it may avoid some auto-saving while you | |
1107 are actually typing. | |
1108 | |
1109 Emacs also does auto-saving whenever it gets a fatal error. This | |
1110 includes killing the Emacs job with a shell command such as @samp{kill | |
1111 %emacs}, or disconnecting a phone line or network connection. | |
1112 | |
1113 @findex do-auto-save | |
1114 You can request an auto-save explicitly with the command @kbd{M-x | |
1115 do-auto-save}. | |
1116 | |
1117 @node Recover | |
1118 @subsection Recovering Data from Auto-Saves | |
1119 | |
1120 @findex recover-file | |
1121 You can use the contents of an auto-save file to recover from a loss | |
1122 of data with the command @kbd{M-x recover-file @key{RET} @var{file} | |
1123 @key{RET}}. This visits @var{file} and then (after your confirmation) | |
1124 restores the contents from its auto-save file @file{#@var{file}#}. | |
1125 You can then save with @kbd{C-x C-s} to put the recovered text into | |
1126 @var{file} itself. For example, to recover file @file{foo.c} from its | |
1127 auto-save file @file{#foo.c#}, do:@refill | |
1128 | |
1129 @example | |
1130 M-x recover-file @key{RET} foo.c @key{RET} | |
1131 yes @key{RET} | |
1132 C-x C-s | |
1133 @end example | |
1134 | |
1135 Before asking for confirmation, @kbd{M-x recover-file} displays a | |
1136 directory listing describing the specified file and the auto-save file, | |
1137 so you can compare their sizes and dates. If the auto-save file | |
1138 is older, @kbd{M-x recover-file} does not offer to read it. | |
1139 | |
1140 @findex recover-session | |
1141 If Emacs or the computer crashes, you can recover all the files you | |
1142 were editing from their auto save files with the command @kbd{M-x | |
1143 recover-session}. This first shows you a list of recorded interrupted | |
1144 sessions. Move point to the one you choose, and type @kbd{C-c C-c}. | |
1145 | |
1146 Then @code{recover-session} asks about each of the files that were | |
1147 being edited during that session, asking whether to recover that file. | |
1148 If you answer @kbd{y}, it calls @code{recover-file}, which works in its | |
1149 normal fashion. It shows the dates of the original file and its | |
1150 auto-save file, and asks once again whether to recover that file. | |
1151 | |
1152 When @code{recover-session} is done, the files you've chosen to | |
1153 recover are present in Emacs buffers. You should then save them. Only | |
1154 this---saving them---updates the files themselves. | |
1155 | |
1156 @vindex auto-save-list-file-prefix | |
1157 Emacs records information about interrupted sessions for later | |
1158 recovery in files named | |
1159 @file{~/.emacs.d/auto-save-list/.saves-@var{pid}-@var{hostname}}. All | |
1160 of this name except the @file{@var{pid}-@var{hostname}} part comes | |
1161 from the value of @code{auto-save-list-file-prefix}. You can record | |
1162 sessions in a different place by customizing that variable. If you | |
1163 set @code{auto-save-list-file-prefix} to @code{nil} in your | |
1164 @file{.emacs} file, sessions are not recorded for recovery. | |
1165 | |
1166 @node File Aliases | |
1167 @section File Name Aliases | |
1168 @cindex symbolic links (visiting) | |
1169 @cindex hard links (visiting) | |
1170 | |
1171 Symbolic links and hard links both make it possible for several file | |
1172 names to refer to the same file. Hard links are alternate names that | |
1173 refer directly to the file; all the names are equally valid, and no one | |
1174 of them is preferred. By contrast, a symbolic link is a kind of defined | |
1175 alias: when @file{foo} is a symbolic link to @file{bar}, you can use | |
1176 either name to refer to the file, but @file{bar} is the real name, while | |
1177 @file{foo} is just an alias. More complex cases occur when symbolic | |
1178 links point to directories. | |
1179 | |
1180 @vindex find-file-existing-other-name | |
1181 @vindex find-file-suppress-same-file-warnings | |
1182 | |
1183 Normally, if you visit a file which Emacs is already visiting under | |
1184 a different name, Emacs displays a message in the echo area and uses | |
1185 the existing buffer visiting that file. This can happen on systems | |
1186 that support hard or symbolic links, or if you use a long file name on | |
1187 a system that truncates long file names, or on a case-insensitive file | |
1188 system. You can suppress the message by setting the variable | |
1189 @code{find-file-suppress-same-file-warnings} to a non-@code{nil} | |
1190 value. You can disable this feature entirely by setting the variable | |
1191 @code{find-file-existing-other-name} to @code{nil}: then if you visit | |
1192 the same file under two different names, you get a separate buffer for | |
1193 each file name. | |
1194 | |
1195 @vindex find-file-visit-truename | |
1196 @cindex truenames of files | |
1197 @cindex file truenames | |
1198 If the variable @code{find-file-visit-truename} is non-@code{nil}, | |
1199 then the file name recorded for a buffer is the file's @dfn{truename} | |
1200 (made by replacing all symbolic links with their target names), rather | |
1201 than the name you specify. Setting @code{find-file-visit-truename} also | |
1202 implies the effect of @code{find-file-existing-other-name}. | |
1203 | |
1204 @node Version Control | |
1205 @section Version Control | |
1206 @cindex version control | |
1207 | |
1208 @dfn{Version control systems} are packages that can record multiple | |
1209 versions of a source file, usually storing the unchanged parts of the | |
1210 file just once. Version control systems also record history information | |
1211 such as the creation time of each version, who created it, and a | |
1212 description of what was changed in that version. | |
1213 | |
1214 The Emacs version control interface is called VC. Its commands work | |
1215 with different version control systems---currently, it supports CVS, | |
1216 GNU Arch, RCS, Meta-CVS, Subversion, and SCCS. Of these, the GNU | |
85161
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1217 project distributes CVS, GNU Arch, and RCS. We also have free |
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1218 software to replace SCCS, known as CSSC; if you are using SCCS and |
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1219 don't want to make the incompatible change to RCS or CVS, you can |
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1220 switch to CSSC. |
84239 | 1221 |
1222 VC is enabled by default in Emacs. To disable it, set the | |
1223 customizable variable @code{vc-handled-backends} to @code{nil} | |
1224 @iftex | |
1225 (@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). | |
1226 @end iftex | |
1227 @ifnottex | |
1228 (@pxref{Customizing VC}). | |
1229 @end ifnottex | |
1230 | |
1231 | |
1232 @menu | |
1233 * Introduction to VC:: How version control works in general. | |
1234 * VC Mode Line:: How the mode line shows version control status. | |
1235 * Basic VC Editing:: How to edit a file under version control. | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1236 * Old Revisions:: Examining and comparing old versions. |
84239 | 1237 * Secondary VC Commands:: The commands used a little less frequently. |
1238 * Branches:: Multiple lines of development. | |
1239 @ifnottex | |
1240 * Remote Repositories:: Efficient access to remote CVS servers. | |
1241 * Snapshots:: Sets of file versions treated as a unit. | |
1242 * Miscellaneous VC:: Various other commands and features of VC. | |
1243 * Customizing VC:: Variables that change VC's behavior. | |
1244 @end ifnottex | |
1245 @end menu | |
1246 | |
1247 @node Introduction to VC | |
1248 @subsection Introduction to Version Control | |
1249 | |
1250 VC allows you to use a version control system from within Emacs, | |
85061
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1251 integrating the version control operations smoothly with editing. |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1252 Though VC cannot completely bridge the gaps between version-control |
85161
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1253 systems with widely differing capabilities, it does provide |
85061
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1254 a uniform interface to many version control operations. Regardless of |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1255 which version control system is in use, you will be able to do basic |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1256 operations in much the same way. |
84239 | 1257 |
1258 This section provides a general overview of version control, and | |
1259 describes the version control systems that VC supports. You can skip | |
1260 this section if you are already familiar with the version control system | |
1261 you want to use. | |
1262 | |
1263 @menu | |
85135
07ce6e2515dd
Fix sectrioning errors in files.texi.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85133
diff
changeset
|
1264 * Why Version Control?:: Understanding the problems it addresses |
07ce6e2515dd
Fix sectrioning errors in files.texi.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85133
diff
changeset
|
1265 * Version Control Systems:: Supported version control back-end systems. |
07ce6e2515dd
Fix sectrioning errors in files.texi.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85133
diff
changeset
|
1266 * VCS Concepts:: Words and concepts related to version control. |
07ce6e2515dd
Fix sectrioning errors in files.texi.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85133
diff
changeset
|
1267 * Types of Log File:: The VCS log in contrast to the ChangeLog. |
84239 | 1268 @end menu |
1269 | |
1270 @node Why Version Control? | |
1271 @subsubsection Understanding the problems it addresses | |
1272 | |
1273 Version control systems provide you with three important capabilities: | |
86364
7842eb213688
(Why Version Control): Fix typo.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
85473
diff
changeset
|
1274 @dfn{reversibility}, @dfn{concurrency}, and @dfn{history}. |
84239 | 1275 |
1276 The most basic capability you get from a version-control system is | |
1277 reversibility, the ability to back up to a saved, known-good state when | |
1278 you discover that some modification you did was a mistake or a bad idea. | |
1279 | |
1280 Version-control systems also support concurrency, the ability to | |
1281 have many people modifying the same collection of code or documents | |
1282 knowing that conflicting modifications can be detected and resolved. | |
1283 | |
1284 Version-control systems give you the capability to attach a history | |
1285 to your data, explanatory comments about the intention behind each | |
1286 change to it. Even for a programmer working solo change histories | |
1287 are an important aid to memory; for a multi-person project they | |
1288 become a vitally important form of communication among developers. | |
1289 | |
85135
07ce6e2515dd
Fix sectrioning errors in files.texi.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85133
diff
changeset
|
1290 @node Version Control Systems |
84239 | 1291 @subsubsection Supported Version Control Systems |
1292 | |
1293 @cindex back end (version control) | |
1294 VC currently works with six different version control systems or | |
85123
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1295 ``back ends'': SCCS, RCS, CVS, Meta-CVS, Subversion, GNU Arch, |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1296 git, and Mercurial. |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1297 @comment Omitting bzr because support is very scratchy and incomplete. |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1298 |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1299 @cindex SCCS |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1300 SCCS was the first version-control system ever built, and was long ago |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1301 superseded by later and more advanced ones; Emacs supports it only for |
86364
7842eb213688
(Why Version Control): Fix typo.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
85473
diff
changeset
|
1302 backward compatibility and historical reasons. VC compensates for |
85123
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1303 certain features missing in SCCS (snapshots, for example) by |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1304 implementing them itself, but some other VC features, such as multiple |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1305 branches, are not available with SCCS. Since SCCS is non-free you |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1306 should not use it; use its free replacement CSSC instead. But you |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1307 should use CSSC only if for some reason you cannot use a more |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1308 recent and better-designed version-control system. |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1309 |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1310 @cindex RCS |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1311 RCS is the free version control system around which VC was initially |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1312 built. Almost everything you can do with RCS can be done through VC. You |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1313 cannot use RCS over the network, though, and it only works at the level |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1314 of individual files, rather than projects. You should use it if you |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1315 want a simple, yet reliable tool for handling individual files. |
84239 | 1316 |
1317 @cindex CVS | |
85061
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1318 CVS is the free version control system that was until recently (as of |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1319 2007) used for the majority of free software projects, though it is now |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1320 being superseded by other systems. It allows concurrent |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1321 multi-user development either locally or over the network. Some of its |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1322 shortcomings, corrected by newer systems such as Subversion or GNU Arch, |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1323 are that it lacks atomic commits or support for renaming files. VC |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1324 supports all basic editing operations under CVS, but for some less |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1325 common tasks you still need to call CVS from the command line. Note |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1326 also that before using CVS you must set up a repository, which is a |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1327 subject too complex to treat here. |
84239 | 1328 |
85123
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1329 @cindex Meta-CVS |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1330 Meta-CVS uses CVS repositories, but has an enhanced client that |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1331 uses client-side information to solve various of the known problems |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1332 with CVS. It is not widely used, having been overtaken by Subversion. |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1333 The Emacs support for it is rudimentary, and may be removed in a |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1334 future version. |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1335 |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1336 @cindex SVN |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1337 @cindex Subversion |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1338 Subversion is a free version control system designed to be similar |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1339 to CVS but without CVS's problems, and is now (2007) rapidly |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1340 superseding CVS. Subversion supports atomic commits of filesets, and |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1341 versions directories, symbolic links, meta-data, renames, copies, and |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1342 deletes. It can be used via http or via its own protocol. |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1343 |
84239 | 1344 @cindex GNU Arch |
1345 @cindex Arch | |
1346 GNU Arch is a new version control system that is designed for | |
1347 distributed work. It differs in many ways from old well-known | |
1348 systems, such as CVS and RCS. It supports different transports for | |
1349 interoperating between users, offline operations, and it has good | |
85123
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1350 branching and merging features. It also supports atomic commits of |
85473
21825793865e
Disambiguate two slightly different uses of the term 'filesets'.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85236
diff
changeset
|
1351 filesets, and keeps a history of file renaming and moving. VC |
85123
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1352 does not support all operations provided by GNU Arch, so you must |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1353 sometimes invoke it from the command line, or use a specialized |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1354 module. |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1355 |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1356 @cindex git |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1357 git is a version-control system invented by Linus Torvalds to |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1358 support Linux kernel development. Like GNU Arch, it supports atomic |
85473
21825793865e
Disambiguate two slightly different uses of the term 'filesets'.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85236
diff
changeset
|
1359 commits of filesets, and keeps a history of file renaming and |
85123
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1360 moving. One significant feature of git is that it largely abolishes |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1361 the notion of a single centralized repository; instead, each working |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1362 copy of a git project is its own repository and coordination is done |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1363 through repository-sync operations. VC fully supports git, except |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1364 that it doesn't do news merges and repository sync operations must |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1365 be done from the command line. |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1366 |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1367 @cindex hg |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1368 @cindex Mercurial |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1369 Mercurial is a distributed version-control systems broadly |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1370 resembling GNU Arch and git, with atomic fileset commits and |
85135
07ce6e2515dd
Fix sectrioning errors in files.texi.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85133
diff
changeset
|
1371 rename/move histories. Like git it is fully decentralized. |
85123
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1372 VC fully supports Mercurial, except for repository sync operations |
4f909d0fbec8
Added descriptions of newer supported version control systems. Arranged all in
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85063
diff
changeset
|
1373 which still need to be done from the command line. |
84239 | 1374 |
85135
07ce6e2515dd
Fix sectrioning errors in files.texi.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85133
diff
changeset
|
1375 @node VCS Concepts |
84239 | 1376 @subsubsection Concepts of Version Control |
1377 | |
85061
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1378 @cindex repository |
84239 | 1379 @cindex registered file |
1380 When a file is under version control, we also say that it is | |
85061
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1381 @dfn{registered} in the version control system. The system has a |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1382 @dfn{repository} which stores both the file's present state plus its |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1383 change history---enough to reconstruct the current version or any |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1384 earlier version. The repository will also contain a @dfn{log entry} for |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1385 each change to the file, describing in words what was modified in that |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1386 revision. |
84239 | 1387 |
1388 @cindex work file | |
1389 @cindex checking out files | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1390 A file checked out of a version-control repository is sometimes |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1391 called the @dfn{work file}. You edit the work file and make changes |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1392 in it, as you would with an ordinary file. After you are done with a |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1393 set of changes, you @dfn{check in} or @dfn{commit} the file, which |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1394 records the changes in the repository, along with a log entry for |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1395 them. |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1396 |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1397 @cindex revision |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1398 @cindex revision ID |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1399 A copy of a file stored in a repository is called a @dfn{revision}. |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1400 The history of a file is a sequence of revisions. Each revisions is |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1401 named by a @dfn{revision ID}. In older VCSes (such as SCCS and RCS), |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1402 the simplest kind of revision ID consisted of a @dfn{dot-pair}; |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1403 integers (the @dfn{major} and @dfn{minor} revisions) separated by a |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1404 dot. Newer VCSes tend to use @dfn{monotonic} revision IDs that are |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1405 simple integers counting from 1. |
84239 | 1406 |
1407 To go beyond these basic concepts, you will need to understand three | |
1408 ways in which version-control systems can differ from each other. They | |
1409 can be locking or merging; they can be file-based or changeset-based; | |
1410 and they can be centralized or decentralized. VC handles all these | |
1411 choices, but they lead to differing behaviors which you will need | |
1412 to understand as you use it. | |
1413 | |
1414 @cindex locking versus merging | |
1415 A version control system typically has some mechanism to coordinate | |
1416 between users who want to change the same file. One method is | |
1417 @dfn{locking} (analogous to the locking that Emacs uses to detect | |
1418 simultaneous editing of a file, but distinct from it). In a locking | |
1419 system, such as SCCS, you must @dfn{lock} a file before you start to | |
1420 edit it. The other method is @dfn{merging}; the system tries to | |
1421 merge your changes with other people's changes when you check them in. | |
1422 | |
1423 With version control locking, work files are normally read-only so | |
1424 that you cannot change them. You ask the version control system to make | |
1425 a work file writable for you by locking it; only one user can do | |
1426 this at any given time. When you check in your changes, that unlocks | |
1427 the file, making the work file read-only again. This allows other users | |
1428 to lock the file to make further changes. | |
1429 | |
1430 By contrast, a merging system lets each user check out and modify a | |
85161
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1431 work file at any time. When you check in a file, the system will |
84239 | 1432 attempt to merge your changes with any others checked into the |
1433 repository since you checked out the file. | |
1434 | |
1435 Both locking and merging systems can have problems when multiple users | |
1436 try to modify the same file at the same time. Locking systems have | |
1437 @dfn{lock conflicts}; a user may try to check a file out and be unable | |
1438 to because it is locked. In merging systems, @dfn{merge conflicts} | |
1439 happen when you check in a change to a file that conflicts with a change | |
1440 checked in by someone else after your checkout. Both kinds of conflict | |
1441 have to be resolved by human judgment and communication. | |
1442 | |
86364
7842eb213688
(Why Version Control): Fix typo.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
85473
diff
changeset
|
1443 SCCS always uses locking. RCS is lock-based by default but can be |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1444 told to operate in a merging style. CVS and Subversion are |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1445 merge-based by default but can be told to operate in a locking mode. |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1446 Most later version-control systems, such as GNU Arch, git, and |
85161
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1447 Mercurial, have been based exclusively on merging rather than locking. |
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1448 This is because experience has shown that the merging-based approach |
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1449 is generally superior to the locking one, both in convenience to |
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1450 developers and in minimizing the number and severity of conflicts that |
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1451 actually occur. |
84239 | 1452 |
1453 While it is rather unlikely that anyone will ever again build a | |
1454 fundamentally locking-based rather than merging-based version-control | |
1455 system in the future, merging-based version-systems sometimes have locks | |
1456 retrofitted onto them for reasons having nothing to do with technology. | |
1457 @footnote{Usually the control-freak instincts of managers.} For this | |
1458 reason, and to support older systems still in use, VC mode supports | |
1459 both locking and merging version control and tries to hide the differences | |
1460 between them as much as possible. | |
1461 | |
1462 @cindex files versus changesets. | |
85135
07ce6e2515dd
Fix sectrioning errors in files.texi.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85133
diff
changeset
|
1463 On SCCS, RCS, CVS, and other early version-control systems, checkins |
84239 | 1464 and other operations are @dfn{file-based}; each file has its own |
85161
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1465 @dfn{master file} with its own comment and revision history separate |
84239 | 1466 from that of all other files in the system. Later systems, beginning |
86364
7842eb213688
(Why Version Control): Fix typo.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
85473
diff
changeset
|
1467 with Subversion, are @dfn{changeset-based}; a checkin under these |
85161
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1468 may include changes to several files and that change set is treated as |
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1469 a unit by the system. Any comment associated with the change belongs |
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1470 to no single file, but is attached to the changeset itself. |
84239 | 1471 |
1472 Changeset-based version control is in general both more flexible and | |
1473 more powerful than file-based version control; usually, when a change to | |
1474 multiple files has to be backed out, it's good to be able to easily | |
85061
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1475 identify and remove all of it. But it took some years for designers to |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1476 figure that out, and while file-based systems are passing out of use |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1477 there are lots of legacy repositories still to be dealt with at time of |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1478 writing in 2007. |
84239 | 1479 |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1480 In fact, older versions of VC mode supported only file-based systems, |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1481 leading to some unhappy results when it was used to drive |
85161
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1482 changeset-based ones---the Subversion support, for example, used to break |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1483 up changesets into multiple per-file commits. This has been fixed, but |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1484 it has left a legacy in VC-mode's terminology. The terms ``checkin'' |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1485 and ``checkout'' are associated with file-based and locking-based |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1486 systems and a bit archaic; nowadays those operations are usually called |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1487 ``commit'' and ``update''. |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1488 |
84239 | 1489 @cindex centralized vs. decentralized |
1490 Early version-control systems were designed around a @dfn{centralized} | |
1491 model in which each project has only one repository used by all | |
1492 developers. SCCS, RCS, CVS, and Subversion share this kind of model. | |
86364
7842eb213688
(Why Version Control): Fix typo.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
85473
diff
changeset
|
1493 It has two important problems. One is that a single repository is a |
85163
98d641abc94b
More minor changes suggested by Robert Chassell.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85161
diff
changeset
|
1494 single point of failure---if the repository server is down all work |
84239 | 1495 stops. The other is that you need to be connected live to the server to |
1496 do checkins and checkouts; if you're offline, you can't work. | |
1497 | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1498 Newer version-control systems like GNU Arch, git, Mercurial, and Bzr |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1499 are @dfn{decentralized}. A project may have several different |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1500 repositories, and these systems support a sort of super-merge between |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1501 repositories that tries to reconcile their change histories. At the |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1502 limit, each developer has his/her own repository, and repository |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1503 merges replace checkin/commit operations. |
84239 | 1504 |
1505 VC's job is to help you manage the traffic between your personal | |
1506 workfiles and a repository. Whether that repository is a single master | |
1507 or one of a network of peer repositories is not something VC has to care | |
1508 about. Thus, the difference between a centralized and a decentralized | |
1509 version-control system is invisible to VC mode. | |
1510 | |
1511 @iftex | |
1512 (@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}). | |
1513 @end iftex | |
1514 @ifnottex | |
1515 (@pxref{CVS Options}). | |
1516 @end ifnottex | |
1517 | |
1518 | |
1519 @node Types of Log File | |
1520 @subsubsection Types of Log File | |
1521 @cindex types of log file | |
1522 @cindex log File, types of | |
1523 @cindex version control log | |
1524 | |
1525 Projects that use a revision control system can have @emph{two} | |
85061
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1526 types of log for changes. One is the log maintained by the |
84239 | 1527 revision control system: each time you check in a change, you must |
1528 fill out a @dfn{log entry} for the change (@pxref{Log Buffer}). This | |
1529 kind of log is called the @dfn{version control log}, also the | |
1530 @dfn{revision control log}, @dfn{RCS log}, or @dfn{CVS log}. | |
1531 | |
1532 The other kind of log is the file @file{ChangeLog} (@pxref{Change | |
1533 Log}). It provides a chronological record of all changes to a large | |
1534 portion of a program---typically one directory and its subdirectories. | |
1535 A small program would use one @file{ChangeLog} file; a large program | |
1536 may well merit a @file{ChangeLog} file in each major directory. | |
1537 @xref{Change Log}. | |
1538 | |
85061
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1539 Actually, the fact that both kinds of log exist is partly a legacy from |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1540 file-based version control. Changelogs are a GNU convention, later |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1541 more widely adopted, that help developers to get a changeset-based |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1542 view of a project even when its version-control system has that |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1543 information split up in multiple file-based logs. |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1544 |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1545 Changeset-based version systems, on the other hand, often maintain |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1546 a changeset-based modification log for the entire system that makes |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1547 ChangeLogs mostly redundant. The only advantage ChangeLogs retain is that |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1548 it may be useful to be able to view the transaction history of a |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1549 single directory separately from those of other directories. |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1550 |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1551 A project maintained with version control can use just the |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1552 version-control log, or it can use both kinds of logs. It can |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1553 handle some files one way and some files the other way. Each project |
46ed9943a6fd
Update manual for 2007 conditions. None of these changes are
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
84239
diff
changeset
|
1554 has its policy, which you should follow. |
84239 | 1555 |
1556 When the policy is to use both, you typically want to write an entry | |
1557 for each change just once, then put it into both logs. You can write | |
1558 the entry in @file{ChangeLog}, then copy it to the log buffer when you | |
1559 check in the change. Or you can write the entry in the log buffer | |
1560 while checking in the change, and later use the @kbd{C-x v a} command | |
1561 to copy it to @file{ChangeLog} | |
1562 @iftex | |
1563 (@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}). | |
1564 @end iftex | |
1565 @ifnottex | |
1566 (@pxref{Change Logs and VC}). | |
1567 @end ifnottex | |
1568 | |
1569 @node VC Mode Line | |
1570 @subsection Version Control and the Mode Line | |
1571 | |
1572 When you visit a file that is under version control, Emacs indicates | |
1573 this on the mode line. For example, @samp{RCS-1.3} says that RCS is | |
1574 used for that file, and the current version is 1.3. | |
1575 | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1576 The character between the back-end name and the revision ID |
84239 | 1577 indicates the version control status of the file. @samp{-} means that |
1578 the work file is not locked (if locking is in use), or not modified (if | |
1579 locking is not in use). @samp{:} indicates that the file is locked, or | |
1580 that it is modified. If the file is locked by some other user (for | |
1581 instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}. | |
1582 | |
1583 @vindex auto-revert-check-vc-info | |
1584 When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is | |
1585 under version control, it updates the version control information in | |
1586 the mode line. However, Auto Revert mode may not properly update this | |
1587 information if the version control status changes without changes to | |
1588 the work file, from outside the current Emacs session. If you set | |
1589 @code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates | |
1590 the version control status information every | |
1591 @code{auto-revert-interval} seconds, even if the work file itself is | |
1592 unchanged. The resulting CPU usage depends on the version control | |
1593 system, but is usually not excessive. | |
1594 | |
1595 @node Basic VC Editing | |
1596 @subsection Basic Editing under Version Control | |
1597 | |
85135
07ce6e2515dd
Fix sectrioning errors in files.texi.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85133
diff
changeset
|
1598 @menu |
85236
7d608cb0bc46
Capitalize node names according to convention.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85176
diff
changeset
|
1599 * Selecting A Fileset:: Choosing a set of files to operate on |
7d608cb0bc46
Capitalize node names according to convention.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85176
diff
changeset
|
1600 * Doing The Right Thing:: Stepping forward in the development cycle |
7d608cb0bc46
Capitalize node names according to convention.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85176
diff
changeset
|
1601 * VC With A Locking VCS:: RCS in its default mode, SCCS, and optionally CVS. |
7d608cb0bc46
Capitalize node names according to convention.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85176
diff
changeset
|
1602 * VC With A Merging VCS:: Without locking: default mode for CVS. |
7d608cb0bc46
Capitalize node names according to convention.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85176
diff
changeset
|
1603 * Advanced C-x v v:: Advanced features available with a prefix argument. |
7d608cb0bc46
Capitalize node names according to convention.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85176
diff
changeset
|
1604 * Log Buffer:: Features available in log entry buffers. |
85135
07ce6e2515dd
Fix sectrioning errors in files.texi.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85133
diff
changeset
|
1605 @end menu |
07ce6e2515dd
Fix sectrioning errors in files.texi.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85133
diff
changeset
|
1606 |
85236
7d608cb0bc46
Capitalize node names according to convention.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85176
diff
changeset
|
1607 @node Selecting A Fileset |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1608 @subsubsection Choosing the scope of your command |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1609 |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1610 @cindex filesets |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1611 Most VC commands operate on @dfn{filesets}. A fileset is a |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1612 group of files that you have chosen to treat as a unit at the |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1613 time you perform the command. Filesets are the way that VC |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1614 mode bridges the gap between file-based and changeset-based |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1615 version-control systems. |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1616 |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1617 If you are visiting a version-controlled file in the current buffer, |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1618 the default fileset for any command is simply that one file. If you |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1619 are visiting a VC Dired buffer, and some files in it are marked, |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1620 your fileset is the marked files only. |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1621 |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1622 All files in a fileset must be under the same version-control system. |
85161
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1623 If they are not, VC mode will fail when you attempt to execute |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1624 a command on the fileset. |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1625 |
86366
9161e1d3983b
(Selecting a Fileset): Fix typo; small rewording.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
86364
diff
changeset
|
1626 VC filesets are, essentially, a way to pass multiple file |
85161
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1627 arguments as a group to underlying version-control commands. For |
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1628 example, on Subversion a checkin with more than one file in its |
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1629 fileset will become a joint commit, as though you had typed |
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1630 @command{svn commit} with those file arguments at the shell command |
96095558e97b
Minor fixes to version-control material suggseted by RMS and Robert
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85152
diff
changeset
|
1631 line in the directory of the selected buffer. |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1632 |
85164
497e90db3e18
*** empty log message ***
Juanma Barranquero <lekktu@gmail.com>
parents:
85163
diff
changeset
|
1633 If you are accustomed to earlier versions of VC, the change in behavior |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1634 you will notice is in VC-Dired mode. Other than @kbd{C-x v v}, most |
85163
98d641abc94b
More minor changes suggested by Robert Chassell.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85161
diff
changeset
|
1635 VC-mode commands once operated on only one file selected by the line |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1636 the cursor is on. The change in the behavior of @kbd{C-x v v} outside |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1637 VC-Dired mode is more subtle. Formerly it operated in parallel on all |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1638 marked files, but did not pass them to the version-control backends as |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1639 a group. Now it does, which enables VC to drive changeset-based |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1640 version-control systems. |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1641 |
85473
21825793865e
Disambiguate two slightly different uses of the term 'filesets'.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85236
diff
changeset
|
1642 Emacs uses the concept of named filesets elsewhere |
21825793865e
Disambiguate two slightly different uses of the term 'filesets'.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85236
diff
changeset
|
1643 (@pxref{Filesets}) to allow you to view and visit files in functional |
86366
9161e1d3983b
(Selecting a Fileset): Fix typo; small rewording.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
86364
diff
changeset
|
1644 groups. Unlike those, VC filesets are not named and don't persist |
85473
21825793865e
Disambiguate two slightly different uses of the term 'filesets'.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85236
diff
changeset
|
1645 across sessions. |
21825793865e
Disambiguate two slightly different uses of the term 'filesets'.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85236
diff
changeset
|
1646 |
85236
7d608cb0bc46
Capitalize node names according to convention.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85176
diff
changeset
|
1647 @node Doing The Right Thing |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1648 @subsubsection Performing the next operation in the development cycle |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1649 |
84239 | 1650 The principal VC command is an all-purpose command that performs |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1651 either locking or check-in on your current fileset, depending on |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1652 the situation. |
84239 | 1653 |
1654 @table @kbd | |
1655 @itemx C-x v v | |
1656 Perform the next logical version control operation on this file. | |
1657 @end table | |
1658 | |
1659 @findex vc-next-action | |
1660 @kindex C-x v v | |
1661 The precise action of this command depends on the state of the file, | |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1662 and whether the version control system uses locking or merging. SCCS and |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1663 RCS normally use locking; CVS and Subversion normally use |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1664 merging but can be configured to do locking. Later systems such as |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1665 GNU Arch and Mercurial always use merging. |
84239 | 1666 |
1667 @findex vc-toggle-read-only | |
1668 @kindex C-x C-q @r{(Version Control)} | |
1669 As a special convenience that is particularly useful for files with | |
1670 locking, you can let Emacs check a file in or out whenever you change | |
1671 its read-only flag. This means, for example, that you cannot | |
1672 accidentally edit a file without properly checking it out first. To | |
1673 achieve this, bind the key @kbd{C-x C-q} to @kbd{vc-toggle-read-only} | |
1674 in your @file{~/.emacs} file. (@xref{Init Rebinding}.) | |
1675 | |
85236
7d608cb0bc46
Capitalize node names according to convention.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85176
diff
changeset
|
1676 @node VC With A Locking VCS |
84239 | 1677 @subsubsection Basic Version Control with Locking |
1678 | |
1679 If locking is used for the file (as with SCCS, and RCS in its default | |
1680 mode), @kbd{C-x v v} can either lock a file or check it in: | |
1681 | |
1682 @itemize @bullet | |
1683 @item | |
1684 If the file is not locked, @kbd{C-x v v} locks it, and | |
1685 makes it writable so that you can change it. | |
1686 | |
1687 @item | |
1688 If the file is locked by you, and contains changes, @kbd{C-x v v} checks | |
1689 in the changes. In order to do this, it first reads the log entry | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1690 for the new revision. @xref{Log Buffer}. |
84239 | 1691 |
1692 @item | |
1693 If the file is locked by you, but you have not changed it since you | |
1694 locked it, @kbd{C-x v v} releases the lock and makes the file read-only | |
1695 again. | |
1696 | |
1697 @item | |
1698 If the file is locked by some other user, @kbd{C-x v v} asks you whether | |
1699 you want to ``steal the lock'' from that user. If you say yes, the file | |
1700 becomes locked by you, but a message is sent to the person who had | |
1701 formerly locked the file, to inform him of what has happened. | |
1702 @end itemize | |
1703 | |
1704 These rules also apply when you use CVS in locking mode, except | |
1705 that there is no such thing as stealing a lock. | |
1706 | |
85236
7d608cb0bc46
Capitalize node names according to convention.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85176
diff
changeset
|
1707 @node VC With A Merging VCS |
85135
07ce6e2515dd
Fix sectrioning errors in files.texi.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85133
diff
changeset
|
1708 @subsubsection Basic Version Control with Merging |
84239 | 1709 |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1710 When your version-control system is merging-based rather than |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1711 locking-based---the default for CVS and Subversion, and the way GNU |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1712 Arch and more modern systems always work---work files are always |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1713 writable; you do not need to do anything before you begin to edit a |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1714 file. The status indicator on the mode line is @samp{-} if the file |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1715 is unmodified; it flips to @samp{:} as soon as you save any changes in |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1716 the work file. |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1717 |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1718 Here is what @kbd{C-x v v} does when using a merging-based system |
85176
ecc5e7d7b8c6
More fixes from Robert J. Chassell.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85164
diff
changeset
|
1719 (such as CVS or Subversion in their default merging mode): |
84239 | 1720 |
1721 @itemize @bullet | |
1722 @item | |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1723 If some other user has checked in changes into the repository, Emacs |
84239 | 1724 asks you whether you want to merge those changes into your own work |
1725 file. You must do this before you can check in your own changes. (To | |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1726 pick up any recent changes from the repository @emph{without} trying |
84239 | 1727 to commit your own changes, type @kbd{C-x v m @key{RET}}.) |
1728 @xref{Merging}. | |
1729 | |
1730 @item | |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1731 If there are no new changes in the repository, but you have made |
84239 | 1732 modifications in your work file, @kbd{C-x v v} checks in your changes. |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1733 In order to do this, it first reads the log entry for the new revision. |
84239 | 1734 @xref{Log Buffer}. |
1735 | |
1736 @item | |
1737 If the file is not modified, the @kbd{C-x v v} does nothing. | |
1738 @end itemize | |
1739 | |
1740 These rules also apply when you use RCS in the mode that does not | |
1741 require locking, except that automatic merging of changes from the | |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1742 repository is not implemented. Unfortunately, this means that nothing |
84239 | 1743 informs you if another user has checked in changes in the same file |
1744 since you began editing it, and when this happens, his changes will be | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1745 effectively removed when you check in your revision (though they will |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1746 remain in the repository, so they will not be entirely lost). You must |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1747 therefore verify that the current revision is unchanged, before you |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1748 check in your changes. |
84239 | 1749 |
1750 In addition, locking is possible with RCS even in this mode, although | |
1751 it is not required; @kbd{C-x v v} with an unmodified file locks the | |
1752 file, just as it does with RCS in its normal (locking) mode. | |
1753 | |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1754 Later systems like CVS, Subversion and Arch will notice conflicting |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1755 changes in the repository automatically and notify you when they occur. |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1756 |
84239 | 1757 @node Advanced C-x v v |
1758 @subsubsection Advanced Control in @kbd{C-x v v} | |
1759 | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1760 @cindex revision ID to check in/out |
84239 | 1761 When you give a prefix argument to @code{vc-next-action} (@kbd{C-u |
1762 C-x v v}), it still performs the next logical version control | |
1763 operation, but accepts additional arguments to specify precisely how | |
1764 to do the operation. | |
1765 | |
1766 @itemize @bullet | |
1767 @item | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1768 If the file is modified (or locked), you can specify the revision ID |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1769 to use for the new version that you check in. This is one way |
84239 | 1770 to create a new branch (@pxref{Branches}). |
1771 | |
1772 @item | |
1773 If the file is not modified (and unlocked), you can specify the | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1774 revision to select; this lets you start working from an older |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1775 revision, or on another branch. If you do not enter any revision, |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1776 that takes you to the highest (``head'') revision on the current |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1777 branch; therefore @kbd{C-u C-x v v @key{RET}} is a convenient way to |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1778 get the latest version of a file from the repository. |
84239 | 1779 |
1780 @item | |
1781 @cindex specific version control system | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1782 Instead of the revision ID, you can also specify the name of a |
84239 | 1783 version control system. This is useful when one file is being managed |
1784 with two version control systems at the same time | |
1785 @iftex | |
1786 (@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs | |
1787 Features}). | |
1788 @end iftex | |
1789 @ifnottex | |
1790 (@pxref{Local Version Control}). | |
1791 @end ifnottex | |
1792 | |
1793 @end itemize | |
1794 | |
1795 @node Log Buffer | |
1796 @subsubsection Features of the Log Entry Buffer | |
1797 | |
1798 When you check in changes, @kbd{C-x v v} first reads a log entry. It | |
1799 pops up a buffer called @samp{*VC-Log*} for you to enter the log entry. | |
1800 | |
1801 Sometimes the @samp{*VC-Log*} buffer contains default text when you enter it, | |
1802 typically the last log message entered. If it does, mark and point | |
1803 are set around the entire contents of the buffer so that it is easy to | |
1804 kill the contents of the buffer with @kbd{C-w}. | |
1805 | |
1806 @findex log-edit-insert-changelog | |
86368
319d5c4e0f9c
(Log Buffer): Fix typos; small rewording.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
86366
diff
changeset
|
1807 If you work by first writing entries in the @file{ChangeLog} |
319d5c4e0f9c
(Log Buffer): Fix typos; small rewording.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
86366
diff
changeset
|
1808 (@pxref{Change Log}) and afterwards committing the change under revision |
84239 | 1809 control, you can generate the Log Edit text from the ChangeLog using |
1810 @kbd{C-c C-a} (@kbd{log-edit-insert-changelog}). This looks for | |
1811 entries for the file(s) concerned in the top entry in the ChangeLog | |
1812 and uses those paragraphs as the log text. This text is only inserted | |
1813 if the top entry was made under your user name on the current date. | |
1814 @iftex | |
1815 @xref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}, | |
1816 @end iftex | |
1817 @ifnottex | |
1818 @xref{Change Logs and VC}, | |
1819 @end ifnottex | |
1820 for the opposite way of working---generating ChangeLog entries from | |
1821 the revision control log. | |
1822 | |
1823 In the @samp{*VC-Log*} buffer, @kbd{C-c C-f} (@kbd{M-x | |
1824 log-edit-show-files}) shows the list of files to be committed in case | |
1825 you need to check that. (This can be a list of more than one file if | |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1826 you use VC Dired mode or PCL-CVS.) |
84239 | 1827 @iftex |
1828 @xref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}, | |
1829 @end iftex | |
1830 @ifnottex | |
1831 @xref{VC Dired Mode}, | |
1832 @end ifnottex | |
1833 and @ref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs | |
1834 Front-End to CVS}.) | |
1835 | |
1836 When you have finished editing the log message, type @kbd{C-c C-c} to | |
1837 exit the buffer and commit the change. | |
1838 | |
1839 To abort check-in, just @strong{don't} type @kbd{C-c C-c} in that | |
1840 buffer. You can switch buffers and do other editing. As long as you | |
1841 don't try to check in another file, the entry you were editing remains | |
1842 in the @samp{*VC-Log*} buffer, and you can go back to that buffer at any | |
1843 time to complete the check-in. | |
1844 | |
1845 If you change several source files for the same reason, it is often | |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1846 convenient to specify the same log entry for many of the files. (This |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1847 is the normal way to do things on a changeset-oriented system, where |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1848 comments are attached to changesets rather than the history of |
86368
319d5c4e0f9c
(Log Buffer): Fix typos; small rewording.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
86366
diff
changeset
|
1849 individual files.) The most convenient way to do this is to mark all the |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1850 files in VC-Dired mode and check in from there; the log buffer will |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1851 carry the fileset information with it and do a group commit when you |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1852 confirm it with @kbd{C-c C-c}. |
84239 | 1853 |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1854 However, you can also browse the history of previous log entries to |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1855 duplicate a checkin comment. This can be useful when you want several |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1856 files to have checkin comments that vary only slightly from each |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1857 other. The commands @kbd{M-n}, @kbd{M-p}, @kbd{M-s} and @kbd{M-r} for |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1858 doing this work just like the minibuffer history commands (except that |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1859 these versions are used outside the minibuffer). |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1860 |
84239 | 1861 @vindex vc-log-mode-hook |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
1862 Each time you check in a change, the log entry buffer is put into VC Log |
84239 | 1863 mode, which involves running two hooks: @code{text-mode-hook} and |
1864 @code{vc-log-mode-hook}. @xref{Hooks}. | |
1865 | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1866 @node Old Revisions |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1867 @subsection Examining And Comparing Old Revisions |
84239 | 1868 |
1869 One of the convenient features of version control is the ability | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1870 to examine any revision of a file, or compare two revisions. |
84239 | 1871 |
1872 @table @kbd | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1873 @item C-x v ~ @var{revision} @key{RET} |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1874 Examine revision @var{revision} of the visited file, in a buffer of its |
84239 | 1875 own. |
1876 | |
1877 @item C-x v = | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1878 Compare the buffer contents associated with the current |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1879 fileset with the working revision(s) from which you started editing. |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1880 |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1881 @item C-u C-x v = @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET} |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1882 Compare the specified two repository revisions of the current fileset. |
84239 | 1883 |
1884 @item C-x v g | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1885 Display the file with per-line revision information and using colors. |
84239 | 1886 @end table |
1887 | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1888 @findex vc-revision-other-window |
84239 | 1889 @kindex C-x v ~ |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1890 To examine an old revision in its entirety, visit the file and then type |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1891 @kbd{C-x v ~ @var{revision} @key{RET}} (@code{vc-revision-other-window}). |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1892 This puts the text of revision @var{revision} in a file named |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1893 @file{@var{filename}.~@var{revision}~}, and visits it in its own buffer |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1894 in a separate window. (In RCS, you can also select an old revision |
84239 | 1895 and create a branch from it. @xref{Branches}.) |
1896 | |
1897 @findex vc-diff | |
1898 @kindex C-x v = | |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1899 @kbd{C-x v =} compares the current buffer contents of each file in the |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1900 current fileset (saving them in the file if necessary) with the |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1901 repository revision from which you started editing each file (this is not |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1902 necessarily the latest revision of the file). The diff will be displayed |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1903 in a special buffer in another window. |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1904 |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1905 @findex vc-diff |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1906 @kindex C-u C-x v = |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1907 You can compare two repository revisions of the current fileset with |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1908 the command @kbd{C-u C-x v =} (@code{vc-diff}). @kbd{C-u C-x v =} reads |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1909 two revision ID or tags. The diff will be displayed in a special |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1910 buffer in another window. |
84239 | 1911 |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
1912 You can specify a checked-in revision by its ID; an empty input |
84239 | 1913 specifies the current contents of the work file (which may be different |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1914 from all the checked-in revisions). You can also specify a snapshot name |
84239 | 1915 @iftex |
1916 (@pxref{Snapshots,,,emacs-xtra, Specialized Emacs Features}) | |
1917 @end iftex | |
1918 @ifnottex | |
1919 (@pxref{Snapshots}) | |
1920 @end ifnottex | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1921 instead of one or both revision ID. |
84239 | 1922 |
85176
ecc5e7d7b8c6
More fixes from Robert J. Chassell.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85164
diff
changeset
|
1923 Note that if your version-control system is file-oriented (SCCS, |
ecc5e7d7b8c6
More fixes from Robert J. Chassell.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85164
diff
changeset
|
1924 RCS, CVS) rather than fileset-oriented (Subversion, GNU Arch, git, |
ecc5e7d7b8c6
More fixes from Robert J. Chassell.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85164
diff
changeset
|
1925 Mercurial) specifying a revision of a multiple-file fileset by |
ecc5e7d7b8c6
More fixes from Robert J. Chassell.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85164
diff
changeset
|
1926 revision ID (as opposed to a snapshot name or RSCCS/RCS tag) is |
ecc5e7d7b8c6
More fixes from Robert J. Chassell.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85164
diff
changeset
|
1927 unlikely to return diffs that are connected in any meaningful way. |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1928 |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1929 If you invoke @kbd{C-u C-x v =} or @kbd{C-u C-x v =} from a buffer |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1930 that is neither visiting a version-controlled file nor a VC Dired |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1931 buffer, these commands will generate a diff of all registered files in |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
1932 the current directory and its subdirectories. |
84239 | 1933 |
1934 @vindex vc-diff-switches | |
1935 @vindex vc-rcs-diff-switches | |
1936 @kbd{C-x v =} works by running a variant of the @code{diff} utility | |
1937 designed to work with the version control system in use. When you | |
1938 invoke @code{diff} this way, in addition to the options specified by | |
1939 @code{diff-switches} (@pxref{Comparing Files}), it receives those | |
1940 specified by @code{vc-diff-switches}, plus those specified for the | |
1941 specific back end by @code{vc-@var{backend}-diff-switches}. For | |
1942 instance, when the version control back end is RCS, @code{diff} uses | |
1943 the options in @code{vc-rcs-diff-switches}. The | |
1944 @samp{vc@dots{}diff-switches} variables are @code{nil} by default. | |
1945 | |
1946 The buffer produced by @kbd{C-x v =} supports the commands of | |
1947 Compilation mode (@pxref{Compilation Mode}), such as @kbd{C-x `} and | |
1948 @kbd{C-c C-c}, in both the ``old'' and ``new'' text, and they always | |
1949 find the corresponding locations in the current work file. (Older | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1950 revisions are not, in general, present as files on your disk.) |
84239 | 1951 |
1952 @findex vc-annotate | |
1953 @kindex C-x v g | |
1954 For some back ends, you can display the file @dfn{annotated} with | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
1955 per-line revision information and using colors to enhance the visual |
86368
319d5c4e0f9c
(Log Buffer): Fix typos; small rewording.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
86366
diff
changeset
|
1956 appearance, with the command @kbd{M-x vc-annotate}. This creates a new |
84239 | 1957 buffer (the ``annotate buffer'') displaying the file's text, with each |
1958 part colored to show how old it is. Text colored red is new, blue means | |
1959 old, and intermediate colors indicate intermediate ages. By default, | |
1960 the color is scaled over the full range of ages, such that the oldest | |
1961 changes are blue, and the newest changes are red. | |
1962 | |
86368
319d5c4e0f9c
(Log Buffer): Fix typos; small rewording.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
86366
diff
changeset
|
1963 When you give a prefix argument to this command, Emacs reads two |
319d5c4e0f9c
(Log Buffer): Fix typos; small rewording.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
86366
diff
changeset
|
1964 arguments using the minibuffer: the ID of which revision to display and |
84239 | 1965 annotate (instead of the current file contents), and the time span in |
1966 days the color range should cover. | |
1967 | |
1968 From the annotate buffer, these and other color scaling options are | |
1969 available from the @samp{VC-Annotate} menu. In this buffer, you can | |
1970 also use the following keys to browse the annotations of past revisions, | |
1971 view diffs, or view log entries: | |
1972 | |
1973 @table @kbd | |
1974 @item P | |
1975 Annotate the previous revision, that is to say, the revision before | |
1976 the one currently annotated. A numeric prefix argument is a repeat | |
1977 count, so @kbd{C-u 10 P} would take you back 10 revisions. | |
1978 | |
1979 @item N | |
1980 Annotate the next revision---the one after the revision currently | |
1981 annotated. A numeric prefix argument is a repeat count. | |
1982 | |
1983 @item J | |
1984 Annotate the revision indicated by the current line. | |
1985 | |
1986 @item A | |
1987 Annotate the revision before the one indicated by the current line. | |
1988 This is useful to see the state the file was in before the change on | |
1989 the current line was made. | |
1990 | |
1991 @item D | |
1992 Display the diff between the current line's revision and the previous | |
1993 revision. This is useful to see what the current line's revision | |
1994 actually changed in the file. | |
1995 | |
1996 @item L | |
1997 Show the log of the current line's revision. This is useful to see | |
1998 the author's description of the changes in the revision on the current | |
1999 line. | |
2000 | |
2001 @item W | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2002 Annotate the working revision--the one you are editing. If you used |
84239 | 2003 @kbd{P} and @kbd{N} to browse to other revisions, use this key to |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2004 return to your working revision. |
84239 | 2005 @end table |
2006 | |
2007 @node Secondary VC Commands | |
2008 @subsection The Secondary Commands of VC | |
2009 | |
86368
319d5c4e0f9c
(Log Buffer): Fix typos; small rewording.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
86366
diff
changeset
|
2010 This section explains the secondary commands of VC, those that you might |
84239 | 2011 use once a day. |
2012 | |
2013 @menu | |
2014 * Registering:: Putting a file under version control. | |
2015 * VC Status:: Viewing the VC status of files. | |
2016 * VC Undo:: Canceling changes before or after check-in. | |
2017 @ifnottex | |
2018 * VC Dired Mode:: Listing files managed by version control. | |
2019 * VC Dired Commands:: Commands to use in a VC Dired buffer. | |
2020 @end ifnottex | |
2021 @end menu | |
2022 | |
2023 @node Registering | |
2024 @subsubsection Registering a File for Version Control | |
2025 | |
2026 @kindex C-x v i | |
2027 @findex vc-register | |
2028 You can put any file under version control by simply visiting it, and | |
2029 then typing @w{@kbd{C-x v i}} (@code{vc-register}). | |
2030 | |
2031 @table @kbd | |
2032 @item C-x v i | |
2033 Register the visited file for version control. | |
2034 @end table | |
2035 | |
2036 To register the file, Emacs must choose which version control system | |
2037 to use for it. If the file's directory already contains files | |
2038 registered in a version control system, Emacs uses that system. If | |
2039 there is more than one system in use for a directory, Emacs uses the | |
2040 one that appears first in @code{vc-handled-backends} | |
2041 @iftex | |
2042 (@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). | |
2043 @end iftex | |
2044 @ifnottex | |
2045 (@pxref{Customizing VC}). | |
2046 @end ifnottex | |
2047 On the other hand, if there are no files already registered, Emacs uses | |
2048 the first system from @code{vc-handled-backends} that could register | |
2049 the file (for example, you cannot register a file under CVS if its | |
2050 directory is not already part of a CVS tree); with the default value | |
2051 of @code{vc-handled-backends}, this means that Emacs uses RCS in this | |
2052 situation. | |
2053 | |
2054 If locking is in use, @kbd{C-x v i} leaves the file unlocked and | |
2055 read-only. Type @kbd{C-x v v} if you wish to start editing it. After | |
2056 registering a file with CVS, you must subsequently commit the initial | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2057 revision by typing @kbd{C-x v v}. Until you do that, the revision ID |
84239 | 2058 appears as @samp{@@@@} in the mode line. |
2059 | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2060 @vindex vc-default-init-revision |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2061 @cindex initial revision ID to register |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2062 The default initial revision ID for a newly registered file |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2063 varies by what VCS you are using; normally it will be 1.1 on VCSes |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2064 that use dot-pair revision IDs and 1 on VCSes that use monotonic IDs. |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2065 You can specify a different default by setting the variable |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2066 @code{vc-default-init-revision}, or you can give @kbd{C-x v i} a |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2067 numeric argument; then it reads the initial revision ID for this |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2068 particular file using the minibuffer. |
84239 | 2069 |
2070 @vindex vc-initial-comment | |
2071 If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an | |
2072 initial comment to describe the purpose of this source file. Reading | |
2073 the initial comment works like reading a log entry (@pxref{Log Buffer}). | |
2074 | |
2075 @node VC Status | |
2076 @subsubsection VC Status Commands | |
2077 | |
2078 @table @kbd | |
2079 @item C-x v l | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2080 Display revision control state and change history. |
84239 | 2081 @end table |
2082 | |
2083 @kindex C-x v l | |
2084 @findex vc-print-log | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2085 To view the detailed revision control status and history of a file, |
84239 | 2086 type @kbd{C-x v l} (@code{vc-print-log}). It displays the history of |
2087 changes to the current file, including the text of the log entries. The | |
2088 output appears in a separate window. The point is centered at the | |
2089 revision of the file that is currently being visited. | |
2090 | |
2091 In the change log buffer, you can use the following keys to move | |
2092 between the logs of revisions and of files, to view past revisions, and | |
2093 to view diffs: | |
2094 | |
2095 @table @kbd | |
2096 @item p | |
2097 Move to the previous revision-item in the buffer. (Revision entries in the log | |
2098 buffer are usually in reverse-chronological order, so the previous | |
2099 revision-item usually corresponds to a newer revision.) A numeric | |
2100 prefix argument is a repeat count. | |
2101 | |
2102 @item n | |
2103 Move to the next revision-item (which most often corresponds to the | |
2104 previous revision of the file). A numeric prefix argument is a repeat | |
2105 count. | |
2106 | |
2107 @item P | |
2108 Move to the log of the previous file, when the logs of multiple files | |
2109 are in the log buffer | |
2110 @iftex | |
2111 (@pxref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}). | |
2112 @end iftex | |
2113 @ifnottex | |
2114 (@pxref{VC Dired Mode}). | |
2115 @end ifnottex | |
2116 Otherwise, just move to the beginning of the log. A numeric prefix | |
2117 argument is a repeat count, so @kbd{C-u 10 P} would move backward 10 | |
2118 files. | |
2119 | |
2120 @item N | |
2121 Move to the log of the next file, when the logs of multiple files are | |
2122 in the log buffer | |
2123 @iftex | |
2124 (@pxref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}). | |
2125 @end iftex | |
2126 @ifnottex | |
2127 (@pxref{VC Dired Mode}). | |
2128 @end ifnottex | |
2129 It also takes a numeric prefix argument as a repeat count. | |
2130 | |
2131 @item f | |
2132 Visit the revision indicated at the current line, like typing @kbd{C-x | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2133 v ~} and specifying this revision's ID (@pxref{Old Revisions}). |
84239 | 2134 |
2135 @item d | |
2136 Display the diff (@pxref{Comparing Files}) between the revision | |
2137 indicated at the current line and the next earlier revision. This is | |
2138 useful to see what actually changed when the revision indicated on the | |
2139 current line was committed. | |
2140 @end table | |
2141 | |
2142 @node VC Undo | |
2143 @subsubsection Undoing Version Control Actions | |
2144 | |
2145 @table @kbd | |
2146 @item C-x v u | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2147 Revert the buffer and the file to the working revision from which you started |
84239 | 2148 editing the file. |
2149 | |
2150 @item C-x v c | |
2151 Remove the last-entered change from the master for the visited file. | |
2152 This undoes your last check-in. | |
2153 @end table | |
2154 | |
2155 @kindex C-x v u | |
2156 @findex vc-revert-buffer | |
2157 If you want to discard your current set of changes and revert to the | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2158 working revision from which you started editing the file, use @kbd{C-x v u} |
84239 | 2159 (@code{vc-revert-buffer}). This leaves the file unlocked; if locking |
2160 is in use, you must first lock the file again before you change it | |
2161 again. @kbd{C-x v u} requires confirmation, unless it sees that you | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2162 haven't made any changes with respect to the master copy of the |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2163 working revision. |
84239 | 2164 |
2165 @kbd{C-x v u} is also the command to unlock a file if you lock it and | |
2166 then decide not to change it. | |
2167 | |
2168 @kindex C-x v c | |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
2169 @findex vc-rollback |
84239 | 2170 To cancel a change that you already checked in, use @kbd{C-x v c} |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
2171 (@code{vc-rollback}). This command discards all record of the most |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2172 recent checked-in revision, but only if your work file corresponds to |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2173 that revision---you cannot use @kbd{C-x v c} to cancel a revision that is |
85133
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
2174 not the latest on its branch. Note that many version-control systems do |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
2175 not support rollback at all; this command is something of a historical |
87df82f093bd
New VC command docs for the Emacs manual.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85123
diff
changeset
|
2176 relic. |
84239 | 2177 |
2178 @ifnottex | |
2179 @c vc1-xtra.texi needs extra level of lowering. | |
2180 @lowersections | |
2181 @include vc1-xtra.texi | |
2182 @raisesections | |
2183 @end ifnottex | |
2184 | |
2185 @node Branches | |
2186 @subsection Multiple Branches of a File | |
2187 @cindex branch (version control) | |
2188 @cindex trunk (version control) | |
2189 | |
2190 One use of version control is to maintain multiple ``current'' | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2191 revisions of a file. For example, you might have different revisions of a |
84239 | 2192 program in which you are gradually adding various unfinished new |
2193 features. Each such independent line of development is called a | |
2194 @dfn{branch}. VC allows you to create branches, switch between | |
2195 different branches, and merge changes from one branch to another. | |
2196 Please note, however, that branches are not supported for SCCS. | |
2197 | |
2198 A file's main line of development is usually called the @dfn{trunk}. | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2199 You can create multiple branches from the trunk. How the difference |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2200 between trunk and branch is made visible is dependent on whether the |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2201 VCS uses dot-pair or monotonic version IDs. |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2202 |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2203 In VCSes with dot-pair revision IDs, the revisions on the trunk are |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2204 normally IDed 1.1, 1.2, 1.3, etc. At any such revision, you can |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2205 start an independent branch. A branch starting at revision 1.2 would |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2206 have revision ID 1.2.1.1, and consecutive revisions on this branch |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2207 would have IDs 1.2.1.2, 1.2.1.3, 1.2.1.4, and so on. If there is |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2208 a second branch also starting at revision 1.2, it would consist of |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2209 revisions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc. |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2210 |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2211 In VCSes with monotonic revision IDs, trunk revisions are IDed as |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2212 1, 2, 3, etc. A branch from (say) revision 2 might start with 2.1 and |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2213 continue through 2.2, 2.3, etc. But naming conventions for branches |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2214 and subbranches vary widely on these systems, and some (like |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2215 Mercurial) never depart from the monotonic integer sequence at all. |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2216 Consult the documentation of the VCS you are using. |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2217 |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2218 @cindex head revision |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2219 If you omit the final component of a dot-pair revision ID, that is called a |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2220 @dfn{branch ID}. It refers to the highest existing revision on that |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2221 branch---the @dfn{head revision} of that branch. The branches in the |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2222 dot-pair example above have branch IDs 1.2.1 and 1.2.2. |
84239 | 2223 |
2224 @menu | |
2225 * Switching Branches:: How to get to another existing branch. | |
2226 * Creating Branches:: How to start a new branch. | |
2227 * Merging:: Transferring changes between branches. | |
2228 * Multi-User Branching:: Multiple users working at multiple branches | |
2229 in parallel. | |
2230 @end menu | |
2231 | |
2232 @node Switching Branches | |
2233 @subsubsection Switching between Branches | |
2234 | |
2235 To switch between branches, type @kbd{C-u C-x v v} and specify the | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2236 revision ID you want to select. On a locking-based system, this |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
2237 version is then visited @emph{unlocked} (write-protected), so you can |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
2238 examine it before locking it. Switching branches in this way is allowed |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
2239 only when the file is not locked. |
84239 | 2240 |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2241 On a VCS with dot-pair IDs, you can omit the minor part, thus giving |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2242 only the branch ID; this takes you to the head version on the |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2243 chosen branch. If you only type @key{RET}, Emacs goes to the highest |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2244 version on the trunk. |
84239 | 2245 |
2246 After you have switched to any branch (including the main branch), you | |
2247 stay on it for subsequent VC commands, until you explicitly select some | |
2248 other branch. | |
2249 | |
2250 @node Creating Branches | |
2251 @subsubsection Creating New Branches | |
2252 | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2253 To create a new branch from a head revision (one that is the latest in |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2254 the branch that contains it), first select that revision if necessary, |
84239 | 2255 lock it with @kbd{C-x v v}, and make whatever changes you want. Then, |
2256 when you check in the changes, use @kbd{C-u C-x v v}. This lets you | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2257 specify the revision ID for the new revision. You should specify a |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2258 suitable branch ID for a branch starting at the current revision. |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2259 For example, if the current revision is 2.5, the branch ID should be |
84239 | 2260 2.5.1, 2.5.2, and so on, depending on the number of existing branches at |
2261 that point. | |
2262 | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2263 To create a new branch at an older revision (one that is no longer the |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2264 head of a branch), first select that revision (@pxref{Switching |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
2265 Branches}). Your procedure will then differ depending on whether you |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
2266 are using a locking or merging-based VCS. |
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
2267 |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2268 On a locking VCS, you will need to lock the old revision branch with |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
2269 @kbd{C-x v v}. You'll be asked to confirm, when you lock the old |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2270 revision, that you really mean to create a new branch---if you say no, |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2271 you'll be offered a chance to lock the latest revision instead. On |
85063
4cdaedc4a269
More manual updates and additions bringing it current with modern
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85061
diff
changeset
|
2272 a merging-based VCS you will skip this step. |
84239 | 2273 |
2274 Then make your changes and type @kbd{C-x v v} again to check in a new | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2275 revision. This automatically creates a new branch starting from the |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2276 selected revision. You need not specially request a new branch, because |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2277 that's the only way to add a new revision at a point that is not the head |
84239 | 2278 of a branch. |
2279 | |
2280 After the branch is created, you ``stay'' on it. That means that | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2281 subsequent check-ins create new revisions on that branch. To leave the |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2282 branch, you must explicitly select a different revision with @kbd{C-u C-x |
84239 | 2283 v v}. To transfer changes from one branch to another, use the merge |
2284 command, described in the next section. | |
2285 | |
2286 @node Merging | |
2287 @subsubsection Merging Branches | |
2288 | |
2289 @cindex merging changes | |
2290 When you have finished the changes on a certain branch, you will | |
2291 often want to incorporate them into the file's main line of development | |
2292 (the trunk). This is not a trivial operation, because development might | |
2293 also have proceeded on the trunk, so that you must @dfn{merge} the | |
2294 changes into a file that has already been changed otherwise. VC allows | |
2295 you to do this (and other things) with the @code{vc-merge} command. | |
2296 | |
2297 @table @kbd | |
2298 @item C-x v m (vc-merge) | |
2299 Merge changes into the work file. | |
2300 @end table | |
2301 | |
2302 @kindex C-x v m | |
2303 @findex vc-merge | |
2304 @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it | |
2305 into the current version of the work file. It firsts asks you in the | |
2306 minibuffer where the changes should come from. If you just type | |
2307 @key{RET}, Emacs merges any changes that were made on the same branch | |
2308 since you checked the file out (we call this @dfn{merging the news}). | |
2309 This is the common way to pick up recent changes from the repository, | |
2310 regardless of whether you have already changed the file yourself. | |
2311 | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2312 You can also enter a branch ID or a pair of revision IDs in |
84239 | 2313 the minibuffer. Then @kbd{C-x v m} finds the changes from that |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2314 branch, or the differences between the two revisions you specified, and |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2315 merges them into the current revision of the current file. |
84239 | 2316 |
2317 As an example, suppose that you have finished a certain feature on | |
2318 branch 1.3.1. In the meantime, development on the trunk has proceeded | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2319 to revision 1.5. To merge the changes from the branch to the trunk, |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2320 first go to the head revision of the trunk, by typing @kbd{C-u C-x v v |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2321 @key{RET}}. Revision 1.5 is now current. If locking is used for the file, |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2322 type @kbd{C-x v v} to lock revision 1.5 so that you can change it. Next, |
84239 | 2323 type @kbd{C-x v m 1.3.1 @key{RET}}. This takes the entire set of changes on |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2324 branch 1.3.1 (relative to revision 1.3, where the branch started, up to |
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2325 the last revision on the branch) and merges it into the current revision |
84239 | 2326 of the work file. You can now check in the changed file, thus creating |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2327 revision 1.6 containing the changes from the branch. |
84239 | 2328 |
2329 It is possible to do further editing after merging the branch, before | |
2330 the next check-in. But it is usually wiser to check in the merged | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2331 revision, then lock it and make the further changes. This will keep |
84239 | 2332 a better record of the history of changes. |
2333 | |
2334 @cindex conflicts | |
2335 @cindex resolving conflicts | |
2336 When you merge changes into a file that has itself been modified, the | |
2337 changes might overlap. We call this situation a @dfn{conflict}, and | |
2338 reconciling the conflicting changes is called @dfn{resolving a | |
2339 conflict}. | |
2340 | |
2341 Whenever conflicts occur during merging, VC detects them, tells you | |
2342 about them in the echo area, and asks whether you want help in merging. | |
2343 If you say yes, it starts an Ediff session (@pxref{Top, | |
2344 Ediff, Ediff, ediff, The Ediff Manual}). | |
2345 | |
2346 If you say no, the conflicting changes are both inserted into the | |
2347 file, surrounded by @dfn{conflict markers}. The example below shows how | |
2348 a conflict region looks; the file is called @samp{name} and the current | |
85139
8ba0e30716a5
Terminology cleanup.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85135
diff
changeset
|
2349 master file revision with user B's changes in it is 1.11. |
84239 | 2350 |
2351 @c @w here is so CVS won't think this is a conflict. | |
2352 @smallexample | |
2353 @group | |
2354 @w{<}<<<<<< name | |
2355 @var{User A's version} | |
2356 ======= | |
2357 @var{User B's version} | |
2358 @w{>}>>>>>> 1.11 | |
2359 @end group | |
2360 @end smallexample | |
2361 | |
2362 @cindex vc-resolve-conflicts | |
2363 Then you can resolve the conflicts by editing the file manually. Or | |
2364 you can type @code{M-x vc-resolve-conflicts} after visiting the file. | |
2365 This starts an Ediff session, as described above. Don't forget to | |
2366 check in the merged version afterwards. | |
2367 | |
2368 @node Multi-User Branching | |
2369 @subsubsection Multi-User Branching | |
2370 | |
2371 It is often useful for multiple developers to work simultaneously on | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2372 different branches of a file. CVS and later systems allow this by |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2373 default; for RCS, it is possible if you create multiple source |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2374 directories. Each source directory should have a link named |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2375 @file{RCS} which points to a common directory of RCS master files. |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2376 Then each source directory can have its own choice of selected |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2377 revisions, but all share the same common RCS records. |
84239 | 2378 |
2379 This technique works reliably and automatically, provided that the | |
2380 source files contain RCS version headers | |
2381 @iftex | |
2382 (@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}). | |
2383 @end iftex | |
2384 @ifnottex | |
2385 (@pxref{Version Headers}). | |
2386 @end ifnottex | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2387 The headers enable Emacs to be sure, at all times, which revision |
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2388 ID is present in the work file. |
84239 | 2389 |
2390 If the files do not have version headers, you must instead tell Emacs | |
2391 explicitly in each session which branch you are working on. To do this, | |
2392 first find the file, then type @kbd{C-u C-x v v} and specify the correct | |
85152
a0d3d8180a58
Revise version-control portions of the manual to include
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85139
diff
changeset
|
2393 branch ID. This ensures that Emacs knows which branch it is using |
84239 | 2394 during this particular editing session. |
2395 | |
2396 @ifnottex | |
2397 @include vc2-xtra.texi | |
2398 @end ifnottex | |
2399 | |
2400 @node Directories | |
2401 @section File Directories | |
2402 | |
2403 @cindex file directory | |
2404 @cindex directory listing | |
2405 The file system groups files into @dfn{directories}. A @dfn{directory | |
2406 listing} is a list of all the files in a directory. Emacs provides | |
2407 commands to create and delete directories, and to make directory | |
2408 listings in brief format (file names only) and verbose format (sizes, | |
2409 dates, and authors included). Emacs also includes a directory browser | |
2410 feature called Dired; see @ref{Dired}. | |
2411 | |
2412 @table @kbd | |
2413 @item C-x C-d @var{dir-or-pattern} @key{RET} | |
2414 Display a brief directory listing (@code{list-directory}). | |
2415 @item C-u C-x C-d @var{dir-or-pattern} @key{RET} | |
2416 Display a verbose directory listing. | |
2417 @item M-x make-directory @key{RET} @var{dirname} @key{RET} | |
2418 Create a new directory named @var{dirname}. | |
2419 @item M-x delete-directory @key{RET} @var{dirname} @key{RET} | |
2420 Delete the directory named @var{dirname}. It must be empty, | |
2421 or you get an error. | |
2422 @end table | |
2423 | |
2424 @findex list-directory | |
2425 @kindex C-x C-d | |
2426 The command to display a directory listing is @kbd{C-x C-d} | |
2427 (@code{list-directory}). It reads using the minibuffer a file name | |
2428 which is either a directory to be listed or a wildcard-containing | |
2429 pattern for the files to be listed. For example, | |
2430 | |
2431 @example | |
2432 C-x C-d /u2/emacs/etc @key{RET} | |
2433 @end example | |
2434 | |
2435 @noindent | |
2436 lists all the files in directory @file{/u2/emacs/etc}. Here is an | |
2437 example of specifying a file name pattern: | |
2438 | |
2439 @example | |
2440 C-x C-d /u2/emacs/src/*.c @key{RET} | |
2441 @end example | |
2442 | |
2443 Normally, @kbd{C-x C-d} displays a brief directory listing containing | |
2444 just file names. A numeric argument (regardless of value) tells it to | |
2445 make a verbose listing including sizes, dates, and owners (like | |
2446 @samp{ls -l}). | |
2447 | |
2448 @vindex list-directory-brief-switches | |
2449 @vindex list-directory-verbose-switches | |
2450 The text of a directory listing is mostly obtained by running | |
2451 @code{ls} in an inferior process. Two Emacs variables control the | |
2452 switches passed to @code{ls}: @code{list-directory-brief-switches} is | |
2453 a string giving the switches to use in brief listings (@code{"-CF"} by | |
2454 default), and @code{list-directory-verbose-switches} is a string | |
2455 giving the switches to use in a verbose listing (@code{"-l"} by | |
2456 default). | |
2457 | |
2458 @vindex directory-free-space-program | |
2459 @vindex directory-free-space-args | |
2460 In verbose directory listings, Emacs adds information about the | |
2461 amount of free space on the disk that contains the directory. To do | |
2462 this, it runs the program specified by | |
2463 @code{directory-free-space-program} with arguments | |
2464 @code{directory-free-space-args}. | |
2465 | |
2466 @node Comparing Files | |
2467 @section Comparing Files | |
2468 @cindex comparing files | |
2469 | |
2470 @findex diff | |
2471 @vindex diff-switches | |
2472 The command @kbd{M-x diff} compares two files, displaying the | |
2473 differences in an Emacs buffer named @samp{*diff*}. It works by | |
2474 running the @code{diff} program, using options taken from the variable | |
2475 @code{diff-switches}. The value of @code{diff-switches} should be a | |
2476 string; the default is @code{"-c"} to specify a context diff. | |
2477 @xref{Top,, Diff, diff, Comparing and Merging Files}, for more | |
2478 information about @command{diff} output formats. | |
2479 | |
2480 @findex diff-backup | |
2481 The command @kbd{M-x diff-backup} compares a specified file with its most | |
2482 recent backup. If you specify the name of a backup file, | |
2483 @code{diff-backup} compares it with the source file that it is a backup | |
2484 of. | |
2485 | |
2486 @findex compare-windows | |
2487 The command @kbd{M-x compare-windows} compares the text in the | |
2488 current window with that in the next window. (For more information | |
2489 about windows in Emacs, @ref{Windows}.) Comparison starts at point in | |
2490 each window, after pushing each initial point value on the mark ring | |
2491 in its respective buffer. Then it moves point forward in each window, | |
2492 one character at a time, until it reaches characters that don't match. | |
2493 Then the command exits. | |
2494 | |
2495 If point in the two windows is followed by non-matching text when | |
2496 the command starts, @kbd{M-x compare-windows} tries heuristically to | |
2497 advance up to matching text in the two windows, and then exits. So if | |
2498 you use @kbd{M-x compare-windows} repeatedly, each time it either | |
2499 skips one matching range or finds the start of another. | |
2500 | |
2501 @vindex compare-ignore-case | |
2502 @vindex compare-ignore-whitespace | |
2503 With a numeric argument, @code{compare-windows} ignores changes in | |
2504 whitespace. If the variable @code{compare-ignore-case} is | |
2505 non-@code{nil}, the comparison ignores differences in case as well. | |
2506 If the variable @code{compare-ignore-whitespace} is non-@code{nil}, | |
2507 @code{compare-windows} normally ignores changes in whitespace, and a | |
2508 prefix argument turns that off. | |
2509 | |
2510 @cindex Smerge mode | |
2511 @findex smerge-mode | |
2512 @cindex failed merges | |
2513 @cindex merges, failed | |
2514 @cindex comparing 3 files (@code{diff3}) | |
2515 You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor | |
2516 mode for editing output from the @command{diff3} program. This is | |
2517 typically the result of a failed merge from a version control system | |
2518 ``update'' outside VC, due to conflicting changes to a file. Smerge | |
2519 mode provides commands to resolve conflicts by selecting specific | |
2520 changes. | |
2521 | |
2522 @iftex | |
2523 @xref{Emerge,,, emacs-xtra, Specialized Emacs Features}, | |
2524 @end iftex | |
2525 @ifnottex | |
2526 @xref{Emerge}, | |
2527 @end ifnottex | |
2528 for the Emerge facility, which provides a powerful interface for | |
2529 merging files. | |
2530 | |
2531 @node Diff Mode | |
2532 @section Diff Mode | |
2533 @cindex Diff mode | |
2534 @findex diff-mode | |
2535 @cindex patches, editing | |
2536 | |
2537 Diff mode is used for the output of @kbd{M-x diff}; it is also | |
2538 useful for editing patches and comparisons produced by the | |
2539 @command{diff} program. To select Diff mode manually, type @kbd{M-x | |
2540 diff-mode}. | |
2541 | |
2542 One general feature of Diff mode is that manual edits to the patch | |
2543 automatically correct line numbers, including those in the hunk | |
2544 header, so that you can actually apply the edited patch. Diff mode | |
2545 treats each hunk location as an ``error message,'' so that you can use | |
2546 commands such as @kbd{C-x '} to visit the corresponding source | |
2547 locations. It also provides the following commands to navigate, | |
2548 manipulate and apply parts of patches: | |
2549 | |
2550 @table @kbd | |
2551 @item M-n | |
2552 Move to the next hunk-start (@code{diff-hunk-next}). | |
2553 | |
2554 @item M-p | |
2555 Move to the previous hunk-start (@code{diff-hunk-prev}). | |
2556 | |
2557 @item M-@} | |
2558 Move to the next file-start, in a multi-file patch | |
2559 (@code{diff-file-next}). | |
2560 | |
2561 @item M-@{ | |
2562 Move to the previous file-start, in a multi-file patch | |
2563 (@code{diff-file-prev}). | |
2564 | |
2565 @item M-k | |
2566 Kill the hunk at point (@code{diff-hunk-kill}). | |
2567 | |
2568 @item M-K | |
2569 In a multi-file patch, kill the current file part. | |
2570 (@code{diff-file-kill}). | |
2571 | |
2572 @item C-c C-a | |
2573 Apply this hunk to its target file (@code{diff-apply-hunk}). With a | |
2574 prefix argument of @kbd{C-u}, revert this hunk. | |
2575 | |
2576 @item C-c C-c | |
2577 Go to the source corresponding to this hunk (@code{diff-goto-source}). | |
2578 | |
2579 @item C-c C-e | |
2580 Start an Ediff session with the patch (@code{diff-ediff-patch}). | |
2581 @xref{Top, Ediff, Ediff, ediff, The Ediff Manual}. | |
2582 | |
2583 @item C-c C-n | |
2584 Restrict the view to the current hunk (@code{diff-restrict-view}). | |
2585 @xref{Narrowing}. With a prefix argument of @kbd{C-u}, restrict the | |
2586 view to the current patch of a multiple file patch. To widen again, | |
2587 use @kbd{C-x n w}. | |
2588 | |
2589 @item C-c C-r | |
2590 Reverse the direction of comparison for the entire buffer | |
2591 (@code{diff-reverse-direction}). | |
2592 | |
2593 @item C-c C-s | |
2594 Split the hunk at point (@code{diff-split-hunk}). This is for | |
2595 manually editing patches, and only works with the unified diff format. | |
2596 | |
2597 @item C-c C-u | |
2598 Convert the entire buffer to unified format | |
2599 (@code{diff-context->unified}). With a prefix argument, convert | |
93352
3e6309763b5d
(Diff Mode, Misc File Ops): Describe Transient Mark mode as the
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
2600 unified format to context format. When the mark is active, convert |
3e6309763b5d
(Diff Mode, Misc File Ops): Describe Transient Mark mode as the
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
2601 only the text within the region. |
84239 | 2602 |
2603 @item C-c C-w | |
2604 Refine the current hunk so that it disregards changes in whitespace | |
2605 (@code{diff-refine-hunk}). | |
2606 @end table | |
2607 | |
2608 @kbd{C-x 4 a} in Diff mode operates on behalf of the target file, | |
2609 but gets the function name from the patch itself. @xref{Change Log}. | |
2610 This is useful for making log entries for functions that are deleted | |
2611 by the patch. | |
2612 | |
2613 @node Misc File Ops | |
2614 @section Miscellaneous File Operations | |
2615 | |
2616 Emacs has commands for performing many other operations on files. | |
2617 All operate on one file; they do not accept wildcard file names. | |
2618 | |
2619 @findex view-file | |
2620 @cindex viewing | |
2621 @cindex View mode | |
2622 @cindex mode, View | |
2623 @kbd{M-x view-file} allows you to scan or read a file by sequential | |
2624 screenfuls. It reads a file name argument using the minibuffer. After | |
2625 reading the file into an Emacs buffer, @code{view-file} displays the | |
2626 beginning. You can then type @key{SPC} to scroll forward one windowful, | |
2627 or @key{DEL} to scroll backward. Various other commands are provided | |
2628 for moving around in the file, but none for changing it; type @kbd{?} | |
2629 while viewing for a list of them. They are mostly the same as normal | |
2630 Emacs cursor motion commands. To exit from viewing, type @kbd{q}. | |
2631 The commands for viewing are defined by a special minor mode called View | |
2632 mode. | |
2633 | |
2634 A related command, @kbd{M-x view-buffer}, views a buffer already present | |
2635 in Emacs. @xref{Misc Buffer}. | |
2636 | |
2637 @kindex C-x i | |
2638 @findex insert-file | |
2639 @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the | |
2640 contents of the specified file into the current buffer at point, | |
93352
3e6309763b5d
(Diff Mode, Misc File Ops): Describe Transient Mark mode as the
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
2641 leaving point unchanged before the contents. The position after the |
3e6309763b5d
(Diff Mode, Misc File Ops): Describe Transient Mark mode as the
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
2642 inserted contents is added to the mark ring, without activating the |
3e6309763b5d
(Diff Mode, Misc File Ops): Describe Transient Mark mode as the
Chong Yidong <cyd@stupidchicken.com>
parents:
87903
diff
changeset
|
2643 mark (@pxref{Mark Ring}). |
84239 | 2644 |
2645 @findex insert-file-literally | |
2646 @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file}, | |
2647 except the file is inserted ``literally'': it is treated as a sequence | |
2648 of @acronym{ASCII} characters with no special encoding or conversion, | |
2649 similar to the @kbd{M-x find-file-literally} command | |
2650 (@pxref{Visiting}). | |
2651 | |
2652 @findex write-region | |
2653 @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it | |
2654 copies the contents of the region into the specified file. @kbd{M-x | |
2655 append-to-file} adds the text of the region to the end of the | |
2656 specified file. @xref{Accumulating Text}. The variable | |
2657 @code{write-region-inhibit-fsync} applies to these commands, as well | |
2658 as saving files; see @ref{Customize Save}. | |
2659 | |
2660 @findex delete-file | |
2661 @cindex deletion (of files) | |
2662 @kbd{M-x delete-file} deletes the specified file, like the @code{rm} | |
2663 command in the shell. If you are deleting many files in one directory, it | |
2664 may be more convenient to use Dired (@pxref{Dired}). | |
2665 | |
2666 @findex rename-file | |
2667 @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using | |
2668 the minibuffer, then renames file @var{old} as @var{new}. If the file name | |
2669 @var{new} already exists, you must confirm with @kbd{yes} or renaming is not | |
2670 done; this is because renaming causes the old meaning of the name @var{new} | |
2671 to be lost. If @var{old} and @var{new} are on different file systems, the | |
2672 file @var{old} is copied and deleted. | |
2673 | |
2674 If the argument @var{new} is just a directory name, the real new | |
2675 name is in that directory, with the same non-directory component as | |
2676 @var{old}. For example, @kbd{M-x rename-file RET ~/foo RET /tmp RET} | |
2677 renames @file{~/foo} to @file{/tmp/foo}. The same rule applies to all | |
2678 the remaining commands in this section. All of them ask for | |
2679 confirmation when the new file name already exists, too. | |
2680 | |
2681 @findex add-name-to-file | |
2682 @cindex hard links (creation) | |
2683 The similar command @kbd{M-x add-name-to-file} is used to add an | |
2684 additional name to an existing file without removing its old name. | |
2685 The new name is created as a ``hard link'' to the existing file. | |
2686 The new name must belong on the same file system that the file is on. | |
2687 On MS-Windows, this command works only if the file resides in an NTFS | |
2688 file system. On MS-DOS, it works by copying the file. | |
2689 | |
2690 @findex copy-file | |
2691 @cindex copying files | |
2692 @kbd{M-x copy-file} reads the file @var{old} and writes a new file | |
2693 named @var{new} with the same contents. | |
2694 | |
2695 @findex make-symbolic-link | |
2696 @cindex symbolic links (creation) | |
2697 @kbd{M-x make-symbolic-link} reads two file names @var{target} and | |
2698 @var{linkname}, then creates a symbolic link named @var{linkname}, | |
2699 which points at @var{target}. The effect is that future attempts to | |
2700 open file @var{linkname} will refer to whatever file is named | |
2701 @var{target} at the time the opening is done, or will get an error if | |
2702 the name @var{target} is nonexistent at that time. This command does | |
2703 not expand the argument @var{target}, so that it allows you to specify | |
2704 a relative name as the target of the link. | |
2705 | |
2706 Not all systems support symbolic links; on systems that don't | |
2707 support them, this command is not defined. | |
2708 | |
2709 @node Compressed Files | |
2710 @section Accessing Compressed Files | |
2711 @cindex compression | |
2712 @cindex uncompression | |
2713 @cindex Auto Compression mode | |
2714 @cindex mode, Auto Compression | |
2715 @pindex gzip | |
2716 | |
2717 Emacs automatically uncompresses compressed files when you visit | |
2718 them, and automatically recompresses them if you alter them and save | |
2719 them. Emacs recognizes compressed files by their file names. File | |
2720 names ending in @samp{.gz} indicate a file compressed with | |
2721 @code{gzip}. Other endings indicate other compression programs. | |
2722 | |
2723 Automatic uncompression and compression apply to all the operations in | |
2724 which Emacs uses the contents of a file. This includes visiting it, | |
2725 saving it, inserting its contents into a buffer, loading it, and byte | |
2726 compiling it. | |
2727 | |
2728 @findex auto-compression-mode | |
2729 @vindex auto-compression-mode | |
2730 To disable this feature, type the command @kbd{M-x | |
2731 auto-compression-mode}. You can disable it permanently by | |
2732 customizing the variable @code{auto-compression-mode}. | |
2733 | |
2734 @node File Archives | |
2735 @section File Archives | |
2736 @cindex mode, tar | |
2737 @cindex Tar mode | |
2738 @cindex file archives | |
2739 | |
2740 A file whose name ends in @samp{.tar} is normally an @dfn{archive} | |
2741 made by the @code{tar} program. Emacs views these files in a special | |
2742 mode called Tar mode which provides a Dired-like list of the contents | |
2743 (@pxref{Dired}). You can move around through the list just as you | |
2744 would in Dired, and visit the subfiles contained in the archive. | |
2745 However, not all Dired commands are available in Tar mode. | |
2746 | |
2747 If Auto Compression mode is enabled (@pxref{Compressed Files}), then | |
2748 Tar mode is used also for compressed archives---files with extensions | |
2749 @samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}. | |
2750 | |
2751 The keys @kbd{e}, @kbd{f} and @key{RET} all extract a component file | |
2752 into its own buffer. You can edit it there, and if you save the | |
2753 buffer, the edited version will replace the version in the Tar buffer. | |
2754 @kbd{v} extracts a file into a buffer in View mode. @kbd{o} extracts | |
2755 the file and displays it in another window, so you could edit the file | |
2756 and operate on the archive simultaneously. @kbd{d} marks a file for | |
2757 deletion when you later use @kbd{x}, and @kbd{u} unmarks a file, as in | |
2758 Dired. @kbd{C} copies a file from the archive to disk and @kbd{R} | |
2759 renames a file within the archive. @kbd{g} reverts the buffer from | |
2760 the archive on disk. | |
2761 | |
2762 The keys @kbd{M}, @kbd{G}, and @kbd{O} change the file's permission | |
2763 bits, group, and owner, respectively. | |
2764 | |
2765 If your display supports colors and the mouse, moving the mouse | |
2766 pointer across a file name highlights that file name, indicating that | |
2767 you can click on it. Clicking @kbd{Mouse-2} on the highlighted file | |
2768 name extracts the file into a buffer and displays that buffer. | |
2769 | |
2770 Saving the Tar buffer writes a new version of the archive to disk with | |
2771 the changes you made to the components. | |
2772 | |
2773 You don't need the @code{tar} program to use Tar mode---Emacs reads | |
2774 the archives directly. However, accessing compressed archives | |
2775 requires the appropriate uncompression program. | |
2776 | |
2777 @cindex Archive mode | |
2778 @cindex mode, archive | |
2779 @cindex @code{arc} | |
2780 @cindex @code{jar} | |
2781 @cindex @code{zip} | |
2782 @cindex @code{lzh} | |
2783 @cindex @code{zoo} | |
2784 @pindex arc | |
2785 @pindex jar | |
2786 @pindex zip | |
2787 @pindex lzh | |
2788 @pindex zoo | |
2789 @cindex Java class archives | |
2790 @cindex unzip archives | |
2791 A separate but similar Archive mode is used for archives produced by | |
2792 the programs @code{arc}, @code{jar}, @code{lzh}, @code{zip}, and | |
2793 @code{zoo}, which have extensions corresponding to the program names. | |
2794 Archive mode also works for those @code{exe} files that are | |
2795 self-extracting executables. | |
2796 | |
2797 The key bindings of Archive mode are similar to those in Tar mode, | |
2798 with the addition of the @kbd{m} key which marks a file for subsequent | |
2799 operations, and @kbd{M-@key{DEL}} which unmarks all the marked files. | |
2800 Also, the @kbd{a} key toggles the display of detailed file | |
2801 information, for those archive types where it won't fit in a single | |
2802 line. Operations such as renaming a subfile, or changing its mode or | |
2803 owner, are supported only for some of the archive formats. | |
2804 | |
2805 Unlike Tar mode, Archive mode runs the archiving program to unpack | |
2806 and repack archives. Details of the program names and their options | |
2807 can be set in the @samp{Archive} Customize group. However, you don't | |
2808 need these programs to look at the archive table of contents, only to | |
2809 extract or manipulate the subfiles in the archive. | |
2810 | |
2811 @node Remote Files | |
2812 @section Remote Files | |
2813 | |
2814 @cindex Tramp | |
2815 @cindex FTP | |
2816 @cindex remote file access | |
2817 You can refer to files on other machines using a special file name | |
2818 syntax: | |
2819 | |
2820 @example | |
2821 @group | |
2822 /@var{host}:@var{filename} | |
2823 /@var{user}@@@var{host}:@var{filename} | |
2824 /@var{user}@@@var{host}#@var{port}:@var{filename} | |
2825 /@var{method}:@var{user}@@@var{host}:@var{filename} | |
2826 /@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename} | |
2827 @end group | |
2828 @end example | |
2829 | |
2830 @noindent | |
2831 To carry out this request, Emacs uses either the FTP program or a | |
2832 remote-login program such as @command{ssh}, @command{rlogin}, or | |
2833 @command{telnet}. You can always specify in the file name which | |
2834 method to use---for example, | |
2835 @file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP, whereas | |
2836 @file{/ssh:@var{user}@@@var{host}:@var{filename}} uses @command{ssh}. | |
2837 When you don't specify a method in the file name, Emacs chooses | |
2838 the method as follows: | |
2839 | |
2840 @enumerate | |
2841 @item | |
2842 If the host name starts with @samp{ftp.} (with dot), then Emacs uses | |
2843 FTP. | |
2844 @item | |
2845 If the user name is @samp{ftp} or @samp{anonymous}, then Emacs uses | |
2846 FTP. | |
2847 @item | |
2848 Otherwise, Emacs uses @command{ssh}. | |
2849 @end enumerate | |
2850 | |
2851 @noindent | |
2852 Remote file access through FTP is handled by the Ange-FTP package, which | |
2853 is documented in the following. Remote file access through the other | |
2854 methods is handled by the Tramp package, which has its own manual. | |
2855 @xref{Top, The Tramp Manual,, tramp, The Tramp Manual}. | |
2856 | |
2857 When the Ange-FTP package is used, Emacs logs in through FTP using your | |
2858 user name or the name @var{user}. It may ask you for a password from | |
2859 time to time; this is used for logging in on @var{host}. The form using | |
2860 @var{port} allows you to access servers running on a non-default TCP | |
2861 port. | |
2862 | |
2863 @cindex backups for remote files | |
2864 @vindex ange-ftp-make-backup-files | |
2865 If you want to disable backups for remote files, set the variable | |
2866 @code{ange-ftp-make-backup-files} to @code{nil}. | |
2867 | |
2868 By default, the auto-save files (@pxref{Auto Save Files}) for remote | |
2869 files are made in the temporary file directory on the local machine. | |
2870 This is achieved using the variable @code{auto-save-file-name-transforms}. | |
2871 | |
2872 @cindex ange-ftp | |
2873 @vindex ange-ftp-default-user | |
2874 @cindex user name for remote file access | |
2875 Normally, if you do not specify a user name in a remote file name, | |
2876 that means to use your own user name. But if you set the variable | |
2877 @code{ange-ftp-default-user} to a string, that string is used instead. | |
2878 | |
2879 @cindex anonymous FTP | |
2880 @vindex ange-ftp-generate-anonymous-password | |
2881 To visit files accessible by anonymous FTP, you use special user | |
2882 names @samp{anonymous} or @samp{ftp}. Passwords for these user names | |
2883 are handled specially. The variable | |
2884 @code{ange-ftp-generate-anonymous-password} controls what happens: if | |
2885 the value of this variable is a string, then that string is used as | |
2886 the password; if non-@code{nil} (the default), then the value of | |
2887 @code{user-mail-address} is used; if @code{nil}, then Emacs prompts | |
2888 you for a password as usual. | |
2889 | |
2890 @cindex firewall, and accessing remote files | |
2891 @cindex gateway, and remote file access with @code{ange-ftp} | |
2892 @vindex ange-ftp-smart-gateway | |
2893 @vindex ange-ftp-gateway-host | |
2894 Sometimes you may be unable to access files on a remote machine | |
2895 because a @dfn{firewall} in between blocks the connection for security | |
2896 reasons. If you can log in on a @dfn{gateway} machine from which the | |
2897 target files @emph{are} accessible, and whose FTP server supports | |
2898 gatewaying features, you can still use remote file names; all you have | |
2899 to do is specify the name of the gateway machine by setting the | |
2900 variable @code{ange-ftp-gateway-host}, and set | |
2901 @code{ange-ftp-smart-gateway} to @code{t}. Otherwise you may be able | |
2902 to make remote file names work, but the procedure is complex. You can | |
2903 read the instructions by typing @kbd{M-x finder-commentary @key{RET} | |
2904 ange-ftp @key{RET}}. | |
2905 | |
2906 @vindex file-name-handler-alist | |
2907 @cindex disabling remote files | |
2908 You can entirely turn off the FTP file name feature by removing the | |
2909 entries @code{ange-ftp-completion-hook-function} and | |
2910 @code{ange-ftp-hook-function} from the variable | |
2911 @code{file-name-handler-alist}. You can turn off the feature in | |
2912 individual cases by quoting the file name with @samp{/:} (@pxref{Quoted | |
2913 File Names}). | |
2914 | |
2915 @node Quoted File Names | |
2916 @section Quoted File Names | |
2917 | |
2918 @cindex quoting file names | |
2919 @cindex file names, quote special characters | |
2920 You can @dfn{quote} an absolute file name to prevent special | |
2921 characters and syntax in it from having their special effects. | |
2922 The way to do this is to add @samp{/:} at the beginning. | |
2923 | |
2924 For example, you can quote a local file name which appears remote, to | |
2925 prevent it from being treated as a remote file name. Thus, if you have | |
2926 a directory named @file{/foo:} and a file named @file{bar} in it, you | |
2927 can refer to that file in Emacs as @samp{/:/foo:/bar}. | |
2928 | |
2929 @samp{/:} can also prevent @samp{~} from being treated as a special | |
2930 character for a user's home directory. For example, @file{/:/tmp/~hack} | |
2931 refers to a file whose name is @file{~hack} in directory @file{/tmp}. | |
2932 | |
2933 Quoting with @samp{/:} is also a way to enter in the minibuffer a | |
2934 file name that contains @samp{$}. In order for this to work, the | |
2935 @samp{/:} must be at the beginning of the minibuffer contents. (You | |
2936 can also double each @samp{$}; see @ref{File Names with $}.) | |
2937 | |
2938 You can also quote wildcard characters with @samp{/:}, for visiting. | |
2939 For example, @file{/:/tmp/foo*bar} visits the file | |
2940 @file{/tmp/foo*bar}. | |
2941 | |
2942 Another method of getting the same result is to enter | |
2943 @file{/tmp/foo[*]bar}, which is a wildcard specification that matches | |
2944 only @file{/tmp/foo*bar}. However, in many cases there is no need to | |
2945 quote the wildcard characters because even unquoted they give the | |
2946 right result. For example, if the only file name in @file{/tmp} that | |
2947 starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar}, | |
2948 then specifying @file{/tmp/foo*bar} will visit only | |
2949 @file{/tmp/foo*bar}. | |
2950 | |
2951 @node File Name Cache | |
2952 @section File Name Cache | |
2953 | |
2954 @cindex file name caching | |
2955 @cindex cache of file names | |
2956 @pindex find | |
2957 @kindex C-@key{TAB} | |
2958 @findex file-cache-minibuffer-complete | |
2959 You can use the @dfn{file name cache} to make it easy to locate a | |
2960 file by name, without having to remember exactly where it is located. | |
2961 When typing a file name in the minibuffer, @kbd{C-@key{tab}} | |
2962 (@code{file-cache-minibuffer-complete}) completes it using the file | |
2963 name cache. If you repeat @kbd{C-@key{tab}}, that cycles through the | |
2964 possible completions of what you had originally typed. (However, note | |
2965 that the @kbd{C-@key{tab}} character cannot be typed on most text-only | |
2966 terminals.) | |
2967 | |
2968 The file name cache does not fill up automatically. Instead, you | |
2969 load file names into the cache using these commands: | |
2970 | |
2971 @findex file-cache-add-directory | |
2972 @table @kbd | |
2973 @item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET} | |
2974 Add each file name in @var{directory} to the file name cache. | |
2975 @item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET} | |
2976 Add each file name in @var{directory} and all of its nested | |
2977 subdirectories to the file name cache. | |
2978 @item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET} | |
2979 Add each file name in @var{directory} and all of its nested | |
2980 subdirectories to the file name cache, using @command{locate} to find | |
2981 them all. | |
2982 @item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET} | |
2983 Add each file name in each directory listed in @var{variable} | |
2984 to the file name cache. @var{variable} should be a Lisp variable | |
2985 such as @code{load-path} or @code{exec-path}, whose value is a list | |
2986 of directory names. | |
2987 @item M-x file-cache-clear-cache @key{RET} | |
2988 Clear the cache; that is, remove all file names from it. | |
2989 @end table | |
2990 | |
2991 The file name cache is not persistent: it is kept and maintained | |
2992 only for the duration of the Emacs session. You can view the contents | |
2993 of the cache with the @code{file-cache-display} command. | |
2994 | |
2995 @node File Conveniences | |
2996 @section Convenience Features for Finding Files | |
2997 | |
2998 In this section, we introduce some convenient facilities for finding | |
2999 recently-opened files, reading file names from a buffer, and viewing | |
3000 image files. | |
3001 | |
3002 @findex recentf-mode | |
3003 @vindex recentf-mode | |
3004 @findex recentf-save-list | |
3005 @findex recentf-edit-list | |
3006 If you enable Recentf mode, with @kbd{M-x recentf-mode}, the | |
3007 @samp{File} menu includes a submenu containing a list of recently | |
3008 opened files. @kbd{M-x recentf-save-list} saves the current | |
3009 @code{recent-file-list} to a file, and @kbd{M-x recentf-edit-list} | |
3010 edits it. | |
3011 | |
3012 The @kbd{M-x ffap} command generalizes @code{find-file} with more | |
3013 powerful heuristic defaults (@pxref{FFAP}), often based on the text at | |
3014 point. Partial Completion mode offers other features extending | |
3015 @code{find-file}, which can be used with @code{ffap}. | |
3016 @xref{Completion Options}. | |
3017 | |
3018 @findex image-mode | |
3019 @findex image-toggle-display | |
3020 @cindex images, viewing | |
3021 Visiting image files automatically selects Image mode. This major | |
3022 mode allows you to toggle between displaying the file as an image in | |
3023 the Emacs buffer, and displaying its underlying text representation, | |
3024 using the command @kbd{C-c C-c} (@code{image-toggle-display}). This | |
3025 works only when Emacs can display the specific image type. If the | |
3026 displayed image is wider or taller than the frame, the usual point | |
3027 motion keys (@kbd{C-f}, @kbd{C-p}, and so forth) cause different parts | |
3028 of the image to be displayed. | |
3029 | |
3030 @findex thumbs-mode | |
3031 @findex mode, thumbs | |
3032 See also the Image-Dired package (@pxref{Image-Dired}) for viewing | |
3033 images as thumbnails. | |
3034 | |
3035 @node Filesets | |
3036 @section Filesets | |
3037 @cindex filesets | |
3038 | |
3039 @findex filesets-init | |
3040 If you regularly edit a certain group of files, you can define them | |
3041 as a @dfn{fileset}. This lets you perform certain operations, such as | |
3042 visiting, @code{query-replace}, and shell commands on all the files | |
3043 at once. To make use of filesets, you must first add the expression | |
3044 @code{(filesets-init)} to your @file{.emacs} file (@pxref{Init File}). | |
3045 This adds a @samp{Filesets} menu to the menu bar. | |
3046 | |
3047 @findex filesets-add-buffer | |
3048 @findex filesets-remove-buffer | |
3049 The simplest way to define a fileset is by adding files to it one | |
3050 at a time. To add a file to fileset @var{name}, visit the file and | |
3051 type @kbd{M-x filesets-add-buffer @kbd{RET} @var{name} @kbd{RET}}. If | |
3052 there is no fileset @var{name}, this creates a new one, which | |
3053 initially creates only the current file. The command @kbd{M-x | |
3054 filesets-remove-buffer} removes the current file from a fileset. | |
3055 | |
3056 You can also edit the list of filesets directly, with @kbd{M-x | |
3057 filesets-edit} (or by choosing @samp{Edit Filesets} from the | |
3058 @samp{Filesets} menu). The editing is performed in a Customize buffer | |
3059 (@pxref{Easy Customization}). Filesets need not be a simple list of | |
3060 files---you can also define filesets using regular expression matching | |
3061 file names. Some examples of these more complicated filesets are | |
3062 shown in the Customize buffer. Remember to select @samp{Save for | |
3063 future sessions} if you want to use the same filesets in future Emacs | |
3064 sessions. | |
3065 | |
3066 You can use the command @kbd{M-x filesets-open} to visit all the | |
3067 files in a fileset, and @kbd{M-x filesets-close} to close them. Use | |
3068 @kbd{M-x filesets-run-cmd} to run a shell command on all the files in | |
3069 a fileset. These commands are also available from the @samp{Filesets} | |
3070 menu, where each existing fileset is represented by a submenu. | |
3071 | |
85473
21825793865e
Disambiguate two slightly different uses of the term 'filesets'.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85236
diff
changeset
|
3072 Emacs uses the concept of a fileset elsewhere @pxref{Version |
21825793865e
Disambiguate two slightly different uses of the term 'filesets'.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85236
diff
changeset
|
3073 Control} to describe sets of files to be treated as a group for |
21825793865e
Disambiguate two slightly different uses of the term 'filesets'.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85236
diff
changeset
|
3074 purposes of version-control operations. Those filesets are |
21825793865e
Disambiguate two slightly different uses of the term 'filesets'.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85236
diff
changeset
|
3075 unnamed and do not persist across Emacs essions. |
21825793865e
Disambiguate two slightly different uses of the term 'filesets'.
Eric S. Raymond <esr@snark.thyrsus.com>
parents:
85236
diff
changeset
|
3076 |
84239 | 3077 @ignore |
3078 arch-tag: 768d32cb-e15a-4cc1-b7bf-62c00ee12250 | |
3079 @end ignore |