Commit | Line | Data |
---|---|---|
6bf7aab6 | 1 | @c This is part of the Emacs manual. |
ee417b73 | 2 | @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 1999, 2000, |
3f548a7c | 3 | @c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc. |
6bf7aab6 | 4 | @c See file emacs.texi for copying conditions. |
f05c7392 | 5 | @node Files, Buffers, Keyboard Macros, Top |
6bf7aab6 DL |
6 | @chapter File Handling |
7 | @cindex files | |
8 | ||
4f09cbeb | 9 | The operating system stores data permanently in named @dfn{files}, so |
6bf7aab6 DL |
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. | |
844040f3 EZ |
28 | @ifnottex |
29 | * Autorevert:: Auto Reverting non-file buffers. | |
30 | @end ifnottex | |
6bf7aab6 DL |
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. | |
5004f8d3 | 36 | * Diff Mode:: Mode for editing file differences. |
6bf7aab6 DL |
37 | * Misc File Ops:: Other things you can do on files. |
38 | * Compressed Files:: Accessing compressed files. | |
259a88ca | 39 | * File Archives:: Operating on tar, zip, jar etc. archive files. |
6bf7aab6 DL |
40 | * Remote Files:: Accessing files on other sites. |
41 | * Quoted File Names:: Quoting special characters in file names. | |
f02d86a3 | 42 | * File Name Cache:: Completion against a list of files you often use. |
9a98ef18 | 43 | * File Conveniences:: Convenience Features for Finding Files. |
9bc727cd | 44 | * Filesets:: Handling sets of files. |
6bf7aab6 DL |
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 | |
0cf729ce RS |
54 | minibuffer (@pxref{Minibuffer}). @dfn{Completion} is available |
55 | (@pxref{Completion}) to make it easier to specify long file names. When | |
36d6da4e | 56 | completing file names, Emacs ignores those whose file-name extensions |
0cf729ce | 57 | appear in the variable @code{completion-ignored-extensions}; see |
36d6da4e | 58 | @ref{Completion Options}. |
6bf7aab6 DL |
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 | |
4f09cbeb | 67 | Each buffer has a default directory which is normally the same as the |
6bf7aab6 DL |
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 | ||
6bf7aab6 DL |
75 | @findex cd |
76 | @findex pwd | |
1ba2ce68 | 77 | The command @kbd{M-x pwd} displays the current buffer's default |
6bf7aab6 DL |
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 | |
50a1bd4f RS |
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}. | |
6bf7aab6 DL |
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 | ||
50a1bd4f RS |
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 | |
d36cfc60 EZ |
113 | login name is @code{user-id}@footnote{ |
114 | On MS-Windows and MS-DOS systems, where a user doesn't have a home | |
bdfbd7e3 KB |
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 | |
d36cfc60 EZ |
118 | for the current user, i.e., only if @var{user-id} is the current |
119 | user's login name.}. | |
50a1bd4f | 120 | |
3d853351 EZ |
121 | @cindex environment variables in file names |
122 | @cindex expansion of environment variables | |
de508b5f | 123 | @cindex @code{$} in file names |
b3c8fa05 RS |
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 | |
60a96371 | 129 | FOO=rms/hacks} to set up an environment variable named @env{FOO}, then |
6bf7aab6 | 130 | you can use @file{/u/$FOO/test.c} or @file{/u/$@{FOO@}/test.c} as an |
b3c8fa05 RS |
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. | |
6bf7aab6 | 138 | |
b3c8fa05 RS |
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{/:}. | |
6bf7aab6 DL |
145 | |
146 | @findex substitute-in-file-name | |
50a1bd4f | 147 | The Lisp function that performs the @samp{$}-substitution is called |
6bf7aab6 DL |
148 | @code{substitute-in-file-name}. The substitution is performed only on |
149 | file names read as such using the minibuffer. | |
150 | ||
76dd3692 | 151 | You can include non-@acronym{ASCII} characters in file names if you set the |
6bf7aab6 | 152 | variable @code{file-name-coding-system} to a non-@code{nil} value. |
efa023dd | 153 | @xref{File Name Coding}. |
6bf7aab6 DL |
154 | |
155 | @node Visiting | |
156 | @section Visiting Files | |
157 | @cindex visiting files | |
1abebfbc | 158 | @cindex open file |
6bf7aab6 | 159 | |
6bf7aab6 DL |
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 | |
6bf7aab6 | 180 | @cindex saving files |
ec8ec9cd | 181 | @dfn{Visiting} a file means reading its contents into an Emacs |
0cf729ce RS |
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}). | |
6bf7aab6 DL |
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 | |
50a1bd4f | 197 | permanent place, until you @dfn{save} the buffer. Saving the buffer |
6bf7aab6 DL |
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}). | |
36d6da4e | 216 | While in the minibuffer, you can abort @kbd{C-x C-f} by typing |
bc5fba52 | 217 | @kbd{C-g}. File-name completion ignores certain file names; for more |
36d6da4e | 218 | about this, see @ref{Completion Options}. |
6bf7aab6 | 219 | |
50a1bd4f RS |
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. | |
6bf7aab6 DL |
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. | |
50a1bd4f RS |
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. | |
6bf7aab6 | 231 | |
3aff69e3 | 232 | @vindex large-file-warning-threshold |
9f2848e4 | 233 | @cindex maximum buffer size exceeded, error message |
3aff69e3 RS |
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 | |
50a1bd4f | 244 | On graphical displays there are two additional methods for |
3aff69e3 RS |
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 | |
638dab37 | 250 | Motif toolkits; on MS-Windows and Mac, the GUI version does that by default. |
a0554a40 | 251 | For information on how to customize this, see @ref{Dialog Boxes}. |
3aff69e3 | 252 | |
590e3b9e RS |
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}. | |
9f2848e4 | 258 | |
6bf7aab6 | 259 | @cindex creating files |
1ba2ce68 | 260 | What if you want to create a new file? Just visit it. Emacs displays |
d3ff0a57 | 261 | @samp{(New file)} in the echo area, but in other respects behaves as if |
6bf7aab6 DL |
262 | you had visited an existing empty file. If you make any changes and |
263 | save them, the file is created. | |
264 | ||
4cc27edb EZ |
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. | |
6bf7aab6 DL |
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 | |
4a10556b RS |
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. | |
6bf7aab6 | 284 | |
1b6f26fb EZ |
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 | ||
7ed32bd8 DL |
290 | @cindex wildcard characters in file names |
291 | @vindex find-file-wildcards | |
092b683a | 292 | If the file name you specify contains shell-style wildcard |
3161cd2c EZ |
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}. | |
6bf7aab6 DL |
301 | |
302 | If you visit a file that the operating system won't let you modify, | |
867357fb RS |
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} | |
576c4a0f | 306 | (@code{toggle-read-only}). @xref{Misc Buffer}. |
6bf7aab6 DL |
307 | |
308 | @kindex C-x C-r | |
309 | @findex find-file-read-only | |
867357fb RS |
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}. | |
6bf7aab6 DL |
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 | |
4f09cbeb EZ |
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. | |
6bf7aab6 | 324 | |
6bf7aab6 DL |
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 | |
76dd3692 | 343 | If you wish to edit a file as a sequence of @acronym{ASCII} characters with no special |
6bf7aab6 DL |
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 | |
4104194e GM |
347 | Systems}), or automatic uncompression (@pxref{Compressed Files}), and |
348 | does not add a final newline because of @code{require-final-newline}. | |
6bf7aab6 DL |
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 | ||
f2aa473a SM |
352 | @vindex find-file-hook |
353 | @vindex find-file-not-found-functions | |
6bf7aab6 DL |
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 | |
f2aa473a | 356 | in the list @code{find-file-not-found-functions}; this variable holds a list |
6bf7aab6 DL |
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 | |
f2aa473a | 359 | normal hook, and the name ends in @samp{-functions} rather than @samp{-hook} |
6bf7aab6 DL |
360 | to indicate that fact. |
361 | ||
0cf729ce | 362 | Successful visiting of any file, whether existing or not, calls the |
f2aa473a SM |
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}. | |
6bf7aab6 DL |
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 | ||
81a35977 RS |
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 | ||
eef3da72 | 387 | @node Save Commands |
81a35977 RS |
388 | @subsection Commands for Saving Files |
389 | ||
390 | These are the commands that relate to saving and writing files. | |
391 | ||
6bf7aab6 DL |
392 | @table @kbd |
393 | @item C-x C-s | |
0cf729ce | 394 | Save the current buffer in its visited file on disk (@code{save-buffer}). |
6bf7aab6 DL |
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}). | |
db8eeecd | 399 | With prefix argument (@kbd{C-u}), mark the current buffer as changed. |
6bf7aab6 | 400 | @item C-x C-w |
50a1bd4f | 401 | Save the current buffer with a specified file name (@code{write-file}). |
6bf7aab6 | 402 | @item M-x set-visited-file-name |
f65d66f8 | 403 | Change the file name under which the current buffer will be saved. |
6bf7aab6 DL |
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. | |
4a10556b RS |
449 | @item d |
450 | Diff the buffer against its corresponding file, so you can see | |
451 | what changes you would be saving. | |
6bf7aab6 DL |
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 | |
50a1bd4f | 473 | called @dfn{reverting}. @xref{Reverting}. (You could also undo all the |
6bf7aab6 | 474 | changes by repeating the undo command @kbd{C-x u} until you have undone |
50a1bd4f | 475 | all the changes; but reverting is easier.) You can also kill the buffer. |
6bf7aab6 DL |
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 | |
0cf729ce RS |
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. | |
6bf7aab6 DL |
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 | |
16f56815 RS |
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). | |
6bf7aab6 DL |
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 | |
0cf729ce | 497 | with the buffer's default directory (@pxref{File Names}). |
6bf7aab6 DL |
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 | ||
6bf7aab6 DL |
509 | @node Backup |
510 | @subsection Backup Files | |
511 | @cindex backup file | |
512 | @vindex make-backup-files | |
513 | @vindex vc-make-backup-files | |
6bf7aab6 DL |
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 | |
4f09cbeb | 527 | to make backup files. By default it is @code{nil}, since backup files |
6bf7aab6 | 528 | are redundant when you store all the previous versions in a version |
844040f3 EZ |
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 | ||
6bf7aab6 | 537 | |
50a1bd4f RS |
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 | ||
9a98ef18 DL |
541 | @vindex backup-enable-predicate |
542 | @vindex temporary-file-directory | |
543 | @vindex small-temporary-file-directory | |
6bf7aab6 | 544 | The default value of the @code{backup-enable-predicate} variable |
f02d86a3 RS |
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}. | |
6bf7aab6 | 548 | |
6bf7aab6 DL |
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 | |
0cf729ce RS |
562 | backup from the previous contents, and arranges to make another from the |
563 | newly saved contents if you save again. | |
6bf7aab6 DL |
564 | |
565 | @menu | |
1384a610 | 566 | * One or Many: Numbered Backups. Whether to make one backup file or many. |
50a1bd4f | 567 | * Names: Backup Names. How backup files are named. |
6bf7aab6 DL |
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 | ||
50a1bd4f RS |
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 | ||
6bf7aab6 DL |
608 | @node Backup Names |
609 | @subsubsection Single or Numbered Backups | |
610 | ||
50a1bd4f RS |
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~}. | |
6bf7aab6 | 614 | |
9a98ef18 DL |
615 | @vindex make-backup-file-name-function |
616 | @vindex backup-directory-alist | |
39cf6a8d | 617 | You can change this behavior by defining the variable |
9a98ef18 DL |
618 | @code{make-backup-file-name-function} to a suitable function. |
619 | Alternatively you can customize the variable | |
9daa0aa0 | 620 | @code{backup-directory-alist} to specify that files matching certain |
f02d86a3 RS |
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, | |
83217838 | 627 | adding, say, @code{("." . ".~")} would make backups in the invisible |
f02d86a3 RS |
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. | |
9a98ef18 | 635 | |
6bf7aab6 | 636 | If you choose to have a series of numbered backup files, backup file |
f02d86a3 RS |
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. | |
6bf7aab6 | 643 | |
6bf7aab6 DL |
644 | @node Backup Deletion |
645 | @subsubsection Automatic Deletion of Backups | |
646 | ||
6b4878ed | 647 | To prevent excessive consumption of disk space, Emacs can delete numbered |
6bf7aab6 DL |
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, | |
0cf729ce RS |
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. | |
6bf7aab6 DL |
664 | |
665 | @vindex delete-old-versions | |
3f9be7ce LT |
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. | |
6bf7aab6 DL |
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 | ||
0cf729ce RS |
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. | |
6bf7aab6 DL |
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 | |
3c8b8db0 EZ |
700 | @vindex backup-by-copying-when-privileged-mismatch |
701 | @cindex file ownership, and backup | |
f02d86a3 | 702 | @cindex backup, and user-id |
3c8b8db0 | 703 | The choice of renaming or copying is controlled by four variables. |
6bf7aab6 DL |
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 | |
3c8b8db0 EZ |
712 | if you start Emacs as the superuser. The fourth variable, |
713 | @code{backup-by-copying-when-privileged-mismatch}, gives the highest | |
f02d86a3 | 714 | numeric user-id for which @code{backup-by-copying-when-mismatch} will be |
4f09cbeb | 715 | forced on. This is useful when low-numbered user-ids are assigned to |
3c8b8db0 EZ |
716 | special system users, such as @code{root}, @code{bin}, @code{daemon}, |
717 | etc., which must maintain ownership of files. | |
6bf7aab6 DL |
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 | ||
81a35977 RS |
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 | ||
6bf7aab6 DL |
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 | |
0cf729ce RS |
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. | |
6bf7aab6 DL |
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 | |
066502ab | 818 | files which are stale, so you may occasionally get warnings about |
6bf7aab6 DL |
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 | |
1ba2ce68 | 827 | displays a warning message and asks for confirmation before saving. |
6bf7aab6 DL |
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 | ||
fa474484 DL |
839 | @node File Shadowing |
840 | @subsection Shadowing Files | |
841 | @cindex shadow files | |
842 | @cindex file shadows | |
50a1bd4f | 843 | @findex shadow-initialize |
fa474484 DL |
844 | |
845 | @table @kbd | |
846 | @item M-x shadow-initialize | |
847 | Set up file shadowing. | |
fa474484 DL |
848 | @item M-x shadow-define-literal-group |
849 | Declare a single file to be shared between sites. | |
f02d86a3 RS |
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}. | |
fa474484 DL |
854 | @item M-x shadow-copy-files |
855 | Copy all pending shadow files. | |
f02d86a3 RS |
856 | @item M-x shadow-cancel |
857 | Cancel the instruction to shadow some files. | |
fa474484 DL |
858 | @end table |
859 | ||
f02d86a3 RS |
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 | ||
d3ff0a57 RS |
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. | |
f02d86a3 RS |
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 | |
d0960fb3 | 883 | regular expression that matches the host names of all the other hosts |
f02d86a3 RS |
884 | in the cluster. You can define a shadow cluster with @kbd{M-x |
885 | shadow-define-cluster}. | |
fa474484 | 886 | |
9575b9ae DL |
887 | @node Time Stamps |
888 | @subsection Updating Time Stamps Automatically | |
9575b9ae DL |
889 | @cindex time stamps |
890 | @cindex modification dates | |
940f14b4 | 891 | @cindex locale, date format |
9575b9ae | 892 | |
4f09cbeb | 893 | You can arrange to put a time stamp in a file, so that it will be updated |
f02d86a3 RS |
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 | ||
9575b9ae DL |
898 | @example |
899 | Time-stamp: <> | |
900 | @end example | |
f02d86a3 | 901 | |
9575b9ae | 902 | @noindent |
f02d86a3 RS |
903 | or like this: |
904 | ||
9575b9ae | 905 | @example |
51c39777 | 906 | Time-stamp: " " |
9575b9ae | 907 | @end example |
9575b9ae | 908 | |
50a1bd4f | 909 | @findex time-stamp |
f02d86a3 | 910 | Then add the hook function @code{time-stamp} to the hook |
3f9be7ce | 911 | @code{before-save-hook}; that hook function will automatically update |
f02d86a3 RS |
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}). | |
9575b9ae | 917 | |
6bf7aab6 DL |
918 | @node Reverting |
919 | @section Reverting a Buffer | |
920 | @findex revert-buffer | |
921 | @cindex drastic changes | |
41d39958 | 922 | @cindex reread a file |
6bf7aab6 DL |
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 | ||
6deaa218 LT |
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. | |
6bf7aab6 DL |
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 | ||
9daa0aa0 DL |
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 | |
3aff69e3 RS |
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 | ||
50a1bd4f | 968 | @kbd{M-x global-auto-revert-mode} enables Global Auto-Revert mode, |
3aff69e3 | 969 | which periodically checks all file buffers and reverts when the |
50a1bd4f RS |
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 | |
efa023dd | 980 | (@code{auto-revert-tail-mode}). It is more efficient for this. |
3aff69e3 | 981 | |
9daa0aa0 | 982 | @vindex auto-revert-interval |
3aff69e3 RS |
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. | |
9daa0aa0 | 986 | |
50a1bd4f | 987 | @xref{VC Mode Line}, for Auto Revert peculiarities in buffers that |
ea98eb11 | 988 | visit files under version control. |
040d9a64 | 989 | |
844040f3 EZ |
990 | @ifnottex |
991 | @include arevert-xtra.texi | |
992 | @end ifnottex | |
993 | ||
6bf7aab6 DL |
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 | ||
a2586785 RS |
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. | |
6bf7aab6 | 1005 | |
50a1bd4f RS |
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. | |
6bf7aab6 DL |
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 | |
14661c9a RS |
1036 | @samp{#} to the front and rear of buffer name, then |
1037 | adding digits and letters at the end for uniqueness. For | |
6bf7aab6 | 1038 | example, the @samp{*mail*} buffer in which you compose messages to be |
3f9be7ce | 1039 | sent might be auto-saved in a file named @file{#*mail*#704juu}. Auto-save file |
6bf7aab6 DL |
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 | ||
5a2ce5f5 GM |
1045 | @cindex auto-save for remote files |
1046 | @vindex auto-save-file-name-transforms | |
b3c8fa05 RS |
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. | |
5a2ce5f5 | 1053 | |
6bf7aab6 DL |
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 | |
3f9be7ce | 1059 | auto-save-mode}. |
6bf7aab6 DL |
1060 | |
1061 | @vindex auto-save-visited-file-name | |
0cf729ce RS |
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. | |
6bf7aab6 DL |
1067 | |
1068 | @vindex delete-auto-save-files | |
1069 | A buffer's auto-save file is deleted when you save the buffer in its | |
50a1bd4f RS |
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. | |
6bf7aab6 DL |
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 | |
dce87f47 EZ |
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. | |
6bf7aab6 DL |
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 | |
df7593dd KB |
1157 | Emacs records information about interrupted sessions for later |
1158 | recovery in files named | |
d41d5dd4 | 1159 | @file{~/.emacs.d/auto-save-list/.saves-@var{pid}-@var{hostname}}. All |
df7593dd KB |
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. | |
6bf7aab6 DL |
1165 | |
1166 | @node File Aliases | |
1167 | @section File Name Aliases | |
f0725a6a RS |
1168 | @cindex symbolic links (visiting) |
1169 | @cindex hard links (visiting) | |
6bf7aab6 DL |
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 | ||
177c0ea7 | 1180 | @vindex find-file-existing-other-name |
124c3a1b | 1181 | @vindex find-file-suppress-same-file-warnings |
f70c5e45 | 1182 | |
f02d86a3 RS |
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 | |
f70c5e45 EZ |
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. | |
6bf7aab6 DL |
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 | |
177c0ea7 | 1211 | such as the creation time of each version, who created it, and a |
6bf7aab6 DL |
1212 | description of what was changed in that version. |
1213 | ||
7d5e745e | 1214 | The Emacs version control interface is called VC. Its commands work |
fa5b6026 AS |
1215 | with different version control systems---currently, it supports CVS, |
1216 | GNU Arch, RCS, Meta-CVS, Subversion, and SCCS. Of these, the GNU | |
1217 | project distributes CVS, GNU Arch, and RCS; we recommend that you use | |
1218 | either CVS or GNU Arch for your projects, and RCS for individual | |
1219 | files. We also have free software to replace SCCS, known as CSSC; if | |
1220 | you are using SCCS and don't want to make the incompatible change to | |
1221 | RCS or CVS, you can switch to CSSC. | |
6bf7aab6 | 1222 | |
bbf7e41b AS |
1223 | VC is enabled by default in Emacs. To disable it, set the |
1224 | customizable variable @code{vc-handled-backends} to @code{nil} | |
844040f3 | 1225 | @iftex |
45ca30f2 | 1226 | (@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). |
844040f3 EZ |
1227 | @end iftex |
1228 | @ifnottex | |
1229 | (@pxref{Customizing VC}). | |
1230 | @end ifnottex | |
1231 | ||
bbf7e41b | 1232 | |
6bf7aab6 DL |
1233 | @menu |
1234 | * Introduction to VC:: How version control works in general. | |
30068267 | 1235 | * VC Mode Line:: How the mode line shows version control status. |
6bf7aab6 DL |
1236 | * Basic VC Editing:: How to edit a file under version control. |
1237 | * Old Versions:: Examining and comparing old versions. | |
1238 | * Secondary VC Commands:: The commands used a little less frequently. | |
1239 | * Branches:: Multiple lines of development. | |
844040f3 EZ |
1240 | @ifnottex |
1241 | * Remote Repositories:: Efficient access to remote CVS servers. | |
1242 | * Snapshots:: Sets of file versions treated as a unit. | |
1243 | * Miscellaneous VC:: Various other commands and features of VC. | |
1244 | * Customizing VC:: Variables that change VC's behavior. | |
1245 | @end ifnottex | |
6bf7aab6 DL |
1246 | @end menu |
1247 | ||
1248 | @node Introduction to VC | |
1249 | @subsection Introduction to Version Control | |
1250 | ||
1251 | VC allows you to use a version control system from within Emacs, | |
1252 | integrating the version control operations smoothly with editing. VC | |
1253 | provides a uniform interface to version control, so that regardless of | |
1254 | which version control system is in use, you can use it the same way. | |
1255 | ||
1256 | This section provides a general overview of version control, and | |
1257 | describes the version control systems that VC supports. You can skip | |
1258 | this section if you are already familiar with the version control system | |
1259 | you want to use. | |
1260 | ||
1261 | @menu | |
1262 | * Version Systems:: Supported version control back-end systems. | |
1263 | * VC Concepts:: Words and concepts related to version control. | |
d4bb5888 | 1264 | * Types of Log File:: The per-file VC log in contrast to the ChangeLog. |
6bf7aab6 DL |
1265 | @end menu |
1266 | ||
1267 | @node Version Systems | |
1268 | @subsubsection Supported Version Control Systems | |
1269 | ||
6bf7aab6 | 1270 | @cindex back end (version control) |
fa5b6026 AS |
1271 | VC currently works with six different version control systems or |
1272 | ``back ends'': CVS, GNU Arch, RCS, Meta-CVS, Subversion, and SCCS. | |
6bf7aab6 DL |
1273 | |
1274 | @cindex CVS | |
fa5b6026 AS |
1275 | CVS is a free version control system that is used for the majority |
1276 | of free software projects today. It allows concurrent multi-user | |
1277 | development either locally or over the network. Some of its | |
1278 | shortcomings, corrected by newer systems such as GNU Arch, are that it | |
1279 | lacks atomic commits or support for renaming files. VC supports all | |
1280 | basic editing operations under CVS, but for some less common tasks you | |
1281 | still need to call CVS from the command line. Note also that before | |
1282 | using CVS you must set up a repository, which is a subject too complex | |
1283 | to treat here. | |
1284 | ||
1285 | @cindex GNU Arch | |
1286 | @cindex Arch | |
1287 | GNU Arch is a new version control system that is designed for | |
1288 | distributed work. It differs in many ways from old well-known | |
1289 | systems, such as CVS and RCS. It supports different transports for | |
1290 | interoperating between users, offline operations, and it has good | |
1291 | branching and merging features. It also supports atomic commits, and | |
1292 | history of file renaming and moving. VC does not support all | |
1293 | operations provided by GNU Arch, so you must sometimes invoke it from | |
1294 | the command line, or use a specialized module. | |
1295 | ||
1296 | @cindex RCS | |
1297 | RCS is the free version control system around which VC was initially | |
1298 | built. The VC commands are therefore conceptually closest to RCS. | |
1299 | Almost everything you can do with RCS can be done through VC. You | |
1300 | cannot use RCS over the network though, and it only works at the level | |
1301 | of individual files, rather than projects. You should use it if you | |
1302 | want a simple, yet reliable tool for handling individual files. | |
1303 | ||
1304 | @cindex SVN | |
1305 | @cindex Subversion | |
1306 | Subversion is a free version control system designed to be similar | |
1307 | to CVS but without CVS's problems. Subversion supports atomic commits, | |
1308 | and versions directories, symbolic links, meta-data, renames, copies, | |
1309 | and deletes. It can be used via http or via its own protocol. | |
1310 | ||
1311 | @cindex MCVS | |
1312 | @cindex Meta-CVS | |
3aff69e3 | 1313 | Meta-CVS is another attempt to solve problems arising in CVS. It |
fa5b6026 AS |
1314 | supports directory structure versioning, improved branching and |
1315 | merging, and use of symbolic links and meta-data in repositories. | |
6bf7aab6 DL |
1316 | |
1317 | @cindex SCCS | |
1318 | SCCS is a proprietary but widely used version control system. In | |
fa5b6026 AS |
1319 | terms of capabilities, it is the weakest of the six that VC supports. |
1320 | VC compensates for certain features missing in SCCS (snapshots, for | |
1321 | example) by implementing them itself, but some other VC features, such | |
50a1bd4f | 1322 | as multiple branches, are not available with SCCS. Since SCCS is |
4ed53daa | 1323 | non-free, not respecting its users freedom, you should not use it; |
50a1bd4f RS |
1324 | use its free replacement CSSC instead. But you should use CSSC only |
1325 | if for some reason you cannot use RCS, or one of the higher-level | |
1326 | systems such as CVS or GNU Arch. | |
6bf7aab6 | 1327 | |
a0554a40 | 1328 | In the following, we discuss mainly RCS, SCCS and CVS. Nearly |
be245005 | 1329 | everything said about CVS applies to GNU Arch, Subversion and Meta-CVS |
a0554a40 LT |
1330 | as well. |
1331 | ||
6bf7aab6 DL |
1332 | @node VC Concepts |
1333 | @subsubsection Concepts of Version Control | |
1334 | ||
1335 | @cindex master file | |
1336 | @cindex registered file | |
1337 | When a file is under version control, we also say that it is | |
1338 | @dfn{registered} in the version control system. Each registered file | |
1339 | has a corresponding @dfn{master file} which represents the file's | |
1340 | present state plus its change history---enough to reconstruct the | |
1341 | current version or any earlier version. Usually the master file also | |
1342 | records a @dfn{log entry} for each version, describing in words what was | |
1343 | changed in that version. | |
1344 | ||
1345 | @cindex work file | |
1346 | @cindex checking out files | |
1347 | The file that is maintained under version control is sometimes called | |
1348 | the @dfn{work file} corresponding to its master file. You edit the work | |
1349 | file and make changes in it, as you would with an ordinary file. (With | |
1350 | SCCS and RCS, you must @dfn{lock} the file before you start to edit it.) | |
1351 | After you are done with a set of changes, you @dfn{check the file in}, | |
1352 | which records the changes in the master file, along with a log entry for | |
1353 | them. | |
1354 | ||
1355 | With CVS, there are usually multiple work files corresponding to a | |
1356 | single master file---often each user has his own copy. It is also | |
1357 | possible to use RCS in this way, but this is not the usual way to use | |
1358 | RCS. | |
1359 | ||
1360 | @cindex locking and version control | |
1361 | A version control system typically has some mechanism to coordinate | |
1362 | between users who want to change the same file. One method is | |
1363 | @dfn{locking} (analogous to the locking that Emacs uses to detect | |
1364 | simultaneous editing of a file, but distinct from it). The other method | |
1365 | is to merge your changes with other people's changes when you check them | |
1366 | in. | |
1367 | ||
1368 | With version control locking, work files are normally read-only so | |
1369 | that you cannot change them. You ask the version control system to make | |
1370 | a work file writable for you by locking it; only one user can do | |
1371 | this at any given time. When you check in your changes, that unlocks | |
1372 | the file, making the work file read-only again. This allows other users | |
1373 | to lock the file to make further changes. SCCS always uses locking, and | |
1374 | RCS normally does. | |
1375 | ||
1376 | The other alternative for RCS is to let each user modify the work file | |
1377 | at any time. In this mode, locking is not required, but it is | |
1378 | permitted; check-in is still the way to record a new version. | |
1379 | ||
1380 | CVS normally allows each user to modify his own copy of the work file | |
1381 | at any time, but requires merging with changes from other users at | |
1382 | check-in time. However, CVS can also be set up to require locking. | |
844040f3 | 1383 | @iftex |
45ca30f2 | 1384 | (@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}). |
844040f3 EZ |
1385 | @end iftex |
1386 | @ifnottex | |
1387 | (@pxref{CVS Options}). | |
1388 | @end ifnottex | |
1389 | ||
6bf7aab6 | 1390 | |
d4bb5888 RC |
1391 | @node Types of Log File |
1392 | @subsubsection Types of Log File | |
30068267 | 1393 | @cindex types of log file |
177c0ea7 | 1394 | @cindex log File, types of |
30068267 | 1395 | @cindex version control log |
d4bb5888 | 1396 | |
bf96cde1 RS |
1397 | Projects that use a revision control system can have @emph{two} |
1398 | types of log for changes. One is the per-file log maintained by the | |
1399 | revision control system: each time you check in a change, you must | |
1400 | fill out a @dfn{log entry} for the change (@pxref{Log Buffer}). This | |
1401 | kind of log is called the @dfn{version control log}, also the | |
1402 | @dfn{revision control log}, @dfn{RCS log}, or @dfn{CVS log}. | |
1403 | ||
1404 | The other kind of log is the file @file{ChangeLog} (@pxref{Change | |
1405 | Log}). It provides a chronological record of all changes to a large | |
1406 | portion of a program---typically one directory and its subdirectories. | |
1407 | A small program would use one @file{ChangeLog} file; a large program | |
1408 | may well merit a @file{ChangeLog} file in each major directory. | |
1409 | @xref{Change Log}. | |
1410 | ||
1411 | A project maintained with version control can use just the per-file | |
1412 | log, or it can use both kinds of logs. It can handle some files one | |
1413 | way and some files the other way. Each project has its policy, which | |
1414 | you should follow. | |
1415 | ||
1416 | When the policy is to use both, you typically want to write an entry | |
1417 | for each change just once, then put it into both logs. You can write | |
30068267 RS |
1418 | the entry in @file{ChangeLog}, then copy it to the log buffer when you |
1419 | check in the change. Or you can write the entry in the log buffer | |
1420 | while checking in the change, and later use the @kbd{C-x v a} command | |
844040f3 EZ |
1421 | to copy it to @file{ChangeLog} |
1422 | @iftex | |
1423 | (@pxref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}). | |
1424 | @end iftex | |
1425 | @ifnottex | |
1426 | (@pxref{Change Logs and VC}). | |
1427 | @end ifnottex | |
1428 | ||
d4bb5888 | 1429 | |
6bf7aab6 DL |
1430 | @node VC Mode Line |
1431 | @subsection Version Control and the Mode Line | |
1432 | ||
1433 | When you visit a file that is under version control, Emacs indicates | |
1434 | this on the mode line. For example, @samp{RCS-1.3} says that RCS is | |
1435 | used for that file, and the current version is 1.3. | |
1436 | ||
1437 | The character between the back-end name and the version number | |
1438 | indicates the version control status of the file. @samp{-} means that | |
1439 | the work file is not locked (if locking is in use), or not modified (if | |
1440 | locking is not in use). @samp{:} indicates that the file is locked, or | |
1441 | that it is modified. If the file is locked by some other user (for | |
1442 | instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}. | |
1443 | ||
ea98eb11 LT |
1444 | @vindex auto-revert-check-vc-info |
1445 | When Auto Revert mode (@pxref{Reverting}) reverts a buffer that is | |
1446 | under version control, it updates the version control information in | |
1447 | the mode line. However, Auto Revert mode may not properly update this | |
1448 | information if the version control status changes without changes to | |
1449 | the work file, from outside the current Emacs session. If you set | |
1450 | @code{auto-revert-check-vc-info} to @code{t}, Auto Revert mode updates | |
1451 | the version control status information every | |
1452 | @code{auto-revert-interval} seconds, even if the work file itself is | |
1453 | unchanged. The resulting CPU usage depends on the version control | |
1454 | system, but is usually not excessive. | |
1455 | ||
6bf7aab6 DL |
1456 | @node Basic VC Editing |
1457 | @subsection Basic Editing under Version Control | |
1458 | ||
1459 | The principal VC command is an all-purpose command that performs | |
1460 | either locking or check-in, depending on the situation. | |
1461 | ||
1462 | @table @kbd | |
6bf7aab6 DL |
1463 | @itemx C-x v v |
1464 | Perform the next logical version control operation on this file. | |
1465 | @end table | |
1466 | ||
1467 | @findex vc-next-action | |
6bf7aab6 | 1468 | @kindex C-x v v |
6bf7aab6 DL |
1469 | The precise action of this command depends on the state of the file, |
1470 | and whether the version control system uses locking or not. SCCS and | |
1471 | RCS normally use locking; CVS normally does not use locking. | |
1472 | ||
576c4a0f AS |
1473 | @findex vc-toggle-read-only |
1474 | @kindex C-x C-q @r{(Version Control)} | |
1475 | As a special convenience that is particularly useful for files with | |
1476 | locking, you can let Emacs check a file in or out whenever you change | |
1477 | its read-only flag. This means, for example, that you cannot | |
1478 | accidentally edit a file without properly checking it out first. To | |
1479 | achieve this, bind the key @kbd{C-x C-q} to @kbd{vc-toggle-read-only} | |
1480 | in your @file{~/.emacs} file. (@xref{Init Rebinding}.) | |
1481 | ||
6bf7aab6 DL |
1482 | @menu |
1483 | * VC with Locking:: RCS in its default mode, SCCS, and optionally CVS. | |
1484 | * Without Locking:: Without locking: default mode for CVS. | |
576c4a0f | 1485 | * Advanced C-x v v:: Advanced features available with a prefix argument. |
6bf7aab6 DL |
1486 | * Log Buffer:: Features available in log entry buffers. |
1487 | @end menu | |
177c0ea7 JB |
1488 | |
1489 | @node VC with Locking | |
6bf7aab6 DL |
1490 | @subsubsection Basic Version Control with Locking |
1491 | ||
1492 | If locking is used for the file (as with SCCS, and RCS in its default | |
576c4a0f | 1493 | mode), @kbd{C-x v v} can either lock a file or check it in: |
6bf7aab6 DL |
1494 | |
1495 | @itemize @bullet | |
1496 | @item | |
576c4a0f | 1497 | If the file is not locked, @kbd{C-x v v} locks it, and |
6bf7aab6 DL |
1498 | makes it writable so that you can change it. |
1499 | ||
1500 | @item | |
576c4a0f | 1501 | If the file is locked by you, and contains changes, @kbd{C-x v v} checks |
6bf7aab6 DL |
1502 | in the changes. In order to do this, it first reads the log entry |
1503 | for the new version. @xref{Log Buffer}. | |
1504 | ||
1505 | @item | |
1506 | If the file is locked by you, but you have not changed it since you | |
576c4a0f | 1507 | locked it, @kbd{C-x v v} releases the lock and makes the file read-only |
6bf7aab6 DL |
1508 | again. |
1509 | ||
1510 | @item | |
576c4a0f | 1511 | If the file is locked by some other user, @kbd{C-x v v} asks you whether |
6bf7aab6 DL |
1512 | you want to ``steal the lock'' from that user. If you say yes, the file |
1513 | becomes locked by you, but a message is sent to the person who had | |
1514 | formerly locked the file, to inform him of what has happened. | |
1515 | @end itemize | |
1516 | ||
1517 | These rules also apply when you use CVS in locking mode, except | |
1518 | that there is no such thing as stealing a lock. | |
1519 | ||
1520 | @node Without Locking | |
1521 | @subsubsection Basic Version Control without Locking | |
1522 | ||
1523 | When there is no locking---the default for CVS---work files are always | |
1524 | writable; you do not need to do anything before you begin to edit a | |
1525 | file. The status indicator on the mode line is @samp{-} if the file is | |
1526 | unmodified; it flips to @samp{:} as soon as you save any changes in the | |
1527 | work file. | |
1528 | ||
576c4a0f | 1529 | Here is what @kbd{C-x v v} does when using CVS: |
6bf7aab6 DL |
1530 | |
1531 | @itemize @bullet | |
1532 | @item | |
7d5e745e RS |
1533 | If some other user has checked in changes into the master file, Emacs |
1534 | asks you whether you want to merge those changes into your own work | |
1535 | file. You must do this before you can check in your own changes. (To | |
1536 | pick up any recent changes from the master file @emph{without} trying | |
1537 | to commit your own changes, type @kbd{C-x v m @key{RET}}.) | |
ad63cf1d | 1538 | @xref{Merging}. |
6bf7aab6 DL |
1539 | |
1540 | @item | |
1541 | If there are no new changes in the master file, but you have made | |
576c4a0f | 1542 | modifications in your work file, @kbd{C-x v v} checks in your changes. |
6bf7aab6 DL |
1543 | In order to do this, it first reads the log entry for the new version. |
1544 | @xref{Log Buffer}. | |
1545 | ||
1546 | @item | |
576c4a0f | 1547 | If the file is not modified, the @kbd{C-x v v} does nothing. |
6bf7aab6 DL |
1548 | @end itemize |
1549 | ||
1550 | These rules also apply when you use RCS in the mode that does not | |
1551 | require locking, except that automatic merging of changes from the | |
1552 | master file is not implemented. Unfortunately, this means that nothing | |
1553 | informs you if another user has checked in changes in the same file | |
1554 | since you began editing it, and when this happens, his changes will be | |
1555 | effectively removed when you check in your version (though they will | |
1556 | remain in the master file, so they will not be entirely lost). You must | |
a0554a40 LT |
1557 | therefore verify that the current version is unchanged, before you |
1558 | check in your changes. We hope to eliminate this risk and provide | |
1559 | automatic merging with RCS in a future Emacs version. | |
6bf7aab6 DL |
1560 | |
1561 | In addition, locking is possible with RCS even in this mode, although | |
576c4a0f | 1562 | it is not required; @kbd{C-x v v} with an unmodified file locks the |
6bf7aab6 DL |
1563 | file, just as it does with RCS in its normal (locking) mode. |
1564 | ||
576c4a0f AS |
1565 | @node Advanced C-x v v |
1566 | @subsubsection Advanced Control in @kbd{C-x v v} | |
ad63cf1d | 1567 | |
37b844b9 | 1568 | @cindex version number to check in/out |
7d5e745e | 1569 | When you give a prefix argument to @code{vc-next-action} (@kbd{C-u |
576c4a0f | 1570 | C-x v v}), it still performs the next logical version control |
7d5e745e RS |
1571 | operation, but accepts additional arguments to specify precisely how |
1572 | to do the operation. | |
ad63cf1d AS |
1573 | |
1574 | @itemize @bullet | |
7d5e745e RS |
1575 | @item |
1576 | If the file is modified (or locked), you can specify the version | |
0cf729ce | 1577 | number to use for the new version that you check in. This is one way |
7d5e745e RS |
1578 | to create a new branch (@pxref{Branches}). |
1579 | ||
1580 | @item | |
1581 | If the file is not modified (and unlocked), you can specify the | |
1582 | version to select; this lets you start working from an older version, | |
1583 | or on another branch. If you do not enter any version, that takes you | |
1584 | to the highest version on the current branch; therefore @kbd{C-u C-x | |
576c4a0f | 1585 | v v @key{RET}} is a convenient way to get the latest version of a file from |
7d5e745e RS |
1586 | the repository. |
1587 | ||
1588 | @item | |
37b844b9 | 1589 | @cindex specific version control system |
7d5e745e RS |
1590 | Instead of the version number, you can also specify the name of a |
1591 | version control system. This is useful when one file is being managed | |
844040f3 EZ |
1592 | with two version control systems at the same time |
1593 | @iftex | |
1594 | (@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs | |
1595 | Features}). | |
1596 | @end iftex | |
1597 | @ifnottex | |
1598 | (@pxref{Local Version Control}). | |
1599 | @end ifnottex | |
1600 | ||
ad63cf1d AS |
1601 | @end itemize |
1602 | ||
6bf7aab6 DL |
1603 | @node Log Buffer |
1604 | @subsubsection Features of the Log Entry Buffer | |
1605 | ||
576c4a0f | 1606 | When you check in changes, @kbd{C-x v v} first reads a log entry. It |
6bf7aab6 | 1607 | pops up a buffer called @samp{*VC-Log*} for you to enter the log entry. |
e07ddddb | 1608 | |
50a1bd4f | 1609 | Sometimes the @samp{*VC-Log*} buffer contains default text when you enter it, |
e07ddddb NR |
1610 | typically the last log message entered. If it does, mark and point |
1611 | are set around the entire contents of the buffer so that it is easy to | |
1612 | kill the contents of the buffer with @kbd{C-w}. | |
1613 | ||
1614 | @findex log-edit-insert-changelog | |
50a1bd4f | 1615 | If you work by writing entries in the @file{ChangeLog} |
e07ddddb NR |
1616 | (@pxref{Change Log}) and then commit the change under revision |
1617 | control, you can generate the Log Edit text from the ChangeLog using | |
1618 | @kbd{C-c C-a} (@kbd{log-edit-insert-changelog}). This looks for | |
1619 | entries for the file(s) concerned in the top entry in the ChangeLog | |
1620 | and uses those paragraphs as the log text. This text is only inserted | |
1621 | if the top entry was made under your user name on the current date. | |
844040f3 | 1622 | @iftex |
45ca30f2 | 1623 | @xref{Change Logs and VC,,,emacs-xtra, Specialized Emacs Features}, |
844040f3 EZ |
1624 | @end iftex |
1625 | @ifnottex | |
1626 | @xref{Change Logs and VC}, | |
1627 | @end ifnottex | |
45ca30f2 KB |
1628 | for the opposite way of working---generating ChangeLog entries from |
1629 | the revision control log. | |
e07ddddb | 1630 | |
45ca30f2 KB |
1631 | In the @samp{*VC-Log*} buffer, @kbd{C-c C-f} (@kbd{M-x |
1632 | log-edit-show-files}) shows the list of files to be committed in case | |
1633 | you need to check that. (This can be a list of more than one file if | |
844040f3 EZ |
1634 | you use VC Dired mode or PCL-CVS. |
1635 | @iftex | |
1636 | @xref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}, | |
1637 | @end iftex | |
1638 | @ifnottex | |
1639 | @xref{VC Dired Mode}, | |
1640 | @end ifnottex | |
1641 | and @ref{Top, , About PCL-CVS, pcl-cvs, PCL-CVS --- The Emacs | |
1642 | Front-End to CVS}.) | |
e07ddddb | 1643 | |
50a1bd4f | 1644 | When you have finished editing the log message, type @kbd{C-c C-c} to |
e07ddddb | 1645 | exit the buffer and commit the change. |
6bf7aab6 DL |
1646 | |
1647 | To abort check-in, just @strong{don't} type @kbd{C-c C-c} in that | |
1648 | buffer. You can switch buffers and do other editing. As long as you | |
1649 | don't try to check in another file, the entry you were editing remains | |
1650 | in the @samp{*VC-Log*} buffer, and you can go back to that buffer at any | |
1651 | time to complete the check-in. | |
1652 | ||
1653 | If you change several source files for the same reason, it is often | |
1654 | convenient to specify the same log entry for many of the files. To do | |
1655 | this, use the history of previous log entries. The commands @kbd{M-n}, | |
1656 | @kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this work just like the | |
1657 | minibuffer history commands (except that these versions are used outside | |
1658 | the minibuffer). | |
1659 | ||
1660 | @vindex vc-log-mode-hook | |
1661 | Each time you check in a file, the log entry buffer is put into VC Log | |
1662 | mode, which involves running two hooks: @code{text-mode-hook} and | |
1663 | @code{vc-log-mode-hook}. @xref{Hooks}. | |
1664 | ||
1665 | @node Old Versions | |
1666 | @subsection Examining And Comparing Old Versions | |
1667 | ||
1668 | One of the convenient features of version control is the ability | |
1669 | to examine any version of a file, or compare two versions. | |
1670 | ||
1671 | @table @kbd | |
1672 | @item C-x v ~ @var{version} @key{RET} | |
1673 | Examine version @var{version} of the visited file, in a buffer of its | |
1674 | own. | |
1675 | ||
1676 | @item C-x v = | |
4ed53daa AS |
1677 | Compare the current buffer contents with the master version from which |
1678 | you started editing. | |
6bf7aab6 DL |
1679 | |
1680 | @item C-u C-x v = @var{file} @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET} | |
1681 | Compare the specified two versions of @var{file}. | |
1682 | ||
1683 | @item C-x v g | |
7bba6c37 | 1684 | Display the file with per-line version information and using colors. |
6bf7aab6 DL |
1685 | @end table |
1686 | ||
1687 | @findex vc-version-other-window | |
1688 | @kindex C-x v ~ | |
0cf729ce | 1689 | To examine an old version in its entirety, visit the file and then type |
6bf7aab6 DL |
1690 | @kbd{C-x v ~ @var{version} @key{RET}} (@code{vc-version-other-window}). |
1691 | This puts the text of version @var{version} in a file named | |
1692 | @file{@var{filename}.~@var{version}~}, and visits it in its own buffer | |
1693 | in a separate window. (In RCS, you can also select an old version | |
1694 | and create a branch from it. @xref{Branches}.) | |
1695 | ||
1696 | @findex vc-diff | |
1697 | @kindex C-x v = | |
ae529c64 | 1698 | It is usually more convenient to compare two versions of the file, |
6bf7aab6 DL |
1699 | with the command @kbd{C-x v =} (@code{vc-diff}). Plain @kbd{C-x v =} |
1700 | compares the current buffer contents (saving them in the file if | |
4ed53daa AS |
1701 | necessary) with the master version from which you started editing the |
1702 | file (this is not necessarily the latest version of the file). | |
1703 | @kbd{C-u C-x v =}, with a numeric argument, reads a file name and two | |
1704 | version numbers, then compares those versions of the specified file. | |
1705 | Both forms display the output in a special buffer in another window. | |
6bf7aab6 DL |
1706 | |
1707 | You can specify a checked-in version by its number; an empty input | |
1708 | specifies the current contents of the work file (which may be different | |
1709 | from all the checked-in versions). You can also specify a snapshot name | |
844040f3 EZ |
1710 | @iftex |
1711 | (@pxref{Snapshots,,,emacs-xtra, Specialized Emacs Features}) | |
1712 | @end iftex | |
1713 | @ifnottex | |
1714 | (@pxref{Snapshots}) | |
1715 | @end ifnottex | |
1716 | instead of one or both version numbers. | |
6bf7aab6 | 1717 | |
7d5e745e RS |
1718 | If you supply a directory name instead of the name of a registered |
1719 | file, this command compares the two specified versions of all registered | |
1720 | files in that directory and its subdirectories. | |
1721 | ||
ad63cf1d | 1722 | @vindex vc-diff-switches |
0cf729ce | 1723 | @vindex vc-rcs-diff-switches |
7d5e745e | 1724 | @kbd{C-x v =} works by running a variant of the @code{diff} utility |
0cf729ce RS |
1725 | designed to work with the version control system in use. When you |
1726 | invoke @code{diff} this way, in addition to the options specified by | |
36d36f35 | 1727 | @code{diff-switches} (@pxref{Comparing Files}), it receives those |
0cf729ce RS |
1728 | specified by @code{vc-diff-switches}, plus those specified for the |
1729 | specific back end by @code{vc-@var{backend}-diff-switches}. For | |
1730 | instance, when the version control back end is RCS, @code{diff} uses | |
1731 | the options in @code{vc-rcs-diff-switches}. The | |
1732 | @samp{vc@dots{}diff-switches} variables are @code{nil} by default. | |
7d5e745e | 1733 | |
97f5d067 AS |
1734 | The buffer produced by @kbd{C-x v =} supports the commands of |
1735 | Compilation mode (@pxref{Compilation Mode}), such as @kbd{C-x `} and | |
1736 | @kbd{C-c C-c}, in both the ``old'' and ``new'' text, and they always | |
1737 | find the corresponding locations in the current work file. (Older | |
1738 | versions are not, in general, present as files on your disk.) | |
6bf7aab6 DL |
1739 | |
1740 | @findex vc-annotate | |
1741 | @kindex C-x v g | |
4ed53daa | 1742 | For some back ends, you can display the file @dfn{annotated} with |
7bba6c37 | 1743 | per-line version information and using colors to enhance the visual |
1145ebb8 S |
1744 | appearance, with the command @kbd{M-x vc-annotate}. It creates a new |
1745 | buffer (the ``annotate buffer'') displaying the file's text, with each | |
1746 | part colored to show how old it is. Text colored red is new, blue means | |
1747 | old, and intermediate colors indicate intermediate ages. By default, | |
1748 | the color is scaled over the full range of ages, such that the oldest | |
1749 | changes are blue, and the newest changes are red. | |
67696322 RS |
1750 | |
1751 | When you give a prefix argument to this command, it uses the | |
1752 | minibuffer to read two arguments: which version number to display and | |
1145ebb8 S |
1753 | annotate (instead of the current file contents), and the time span in |
1754 | days the color range should cover. | |
1755 | ||
1756 | From the annotate buffer, these and other color scaling options are | |
1757 | available from the @samp{VC-Annotate} menu. In this buffer, you can | |
1758 | also use the following keys to browse the annotations of past revisions, | |
1759 | view diffs, or view log entries: | |
2a7790cf | 1760 | |
e8d8cb3e RS |
1761 | @table @kbd |
1762 | @item P | |
1763 | Annotate the previous revision, that is to say, the revision before | |
1764 | the one currently annotated. A numeric prefix argument is a repeat | |
1765 | count, so @kbd{C-u 10 P} would take you back 10 revisions. | |
1766 | ||
1767 | @item N | |
1768 | Annotate the next revision---the one after the revision currently | |
1769 | annotated. A numeric prefix argument is a repeat count. | |
1770 | ||
1771 | @item J | |
1772 | Annotate the revision indicated by the current line. | |
1773 | ||
1774 | @item A | |
1775 | Annotate the revision before the one indicated by the current line. | |
1776 | This is useful to see the state the file was in before the change on | |
1777 | the current line was made. | |
1778 | ||
1779 | @item D | |
1780 | Display the diff between the current line's revision and the previous | |
1781 | revision. This is useful to see what the current line's revision | |
1782 | actually changed in the file. | |
1783 | ||
1784 | @item L | |
1785 | Show the log of the current line's revision. This is useful to see | |
1786 | the author's description of the changes in the revision on the current | |
1787 | line. | |
1788 | ||
1789 | @item W | |
1790 | Annotate the workfile version--the one you are editing. If you used | |
1791 | @kbd{P} and @kbd{N} to browse to other revisions, use this key to | |
4ed53daa | 1792 | return to your current version. |
e8d8cb3e | 1793 | @end table |
2a7790cf | 1794 | |
6bf7aab6 DL |
1795 | @node Secondary VC Commands |
1796 | @subsection The Secondary Commands of VC | |
1797 | ||
1798 | This section explains the secondary commands of VC; those that you might | |
1799 | use once a day. | |
1800 | ||
1801 | @menu | |
1802 | * Registering:: Putting a file under version control. | |
1803 | * VC Status:: Viewing the VC status of files. | |
3f9be7ce | 1804 | * VC Undo:: Canceling changes before or after check-in. |
844040f3 EZ |
1805 | @ifnottex |
1806 | * VC Dired Mode:: Listing files managed by version control. | |
1807 | * VC Dired Commands:: Commands to use in a VC Dired buffer. | |
1808 | @end ifnottex | |
6bf7aab6 DL |
1809 | @end menu |
1810 | ||
1811 | @node Registering | |
1812 | @subsubsection Registering a File for Version Control | |
1813 | ||
1814 | @kindex C-x v i | |
1815 | @findex vc-register | |
1816 | You can put any file under version control by simply visiting it, and | |
1817 | then typing @w{@kbd{C-x v i}} (@code{vc-register}). | |
1818 | ||
1819 | @table @kbd | |
1820 | @item C-x v i | |
1821 | Register the visited file for version control. | |
1822 | @end table | |
1823 | ||
6bf7aab6 | 1824 | To register the file, Emacs must choose which version control system |
ad63cf1d AS |
1825 | to use for it. If the file's directory already contains files |
1826 | registered in a version control system, Emacs uses that system. If | |
45ca30f2 KB |
1827 | there is more than one system in use for a directory, Emacs uses the |
1828 | one that appears first in @code{vc-handled-backends} | |
844040f3 EZ |
1829 | @iftex |
1830 | (@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}). | |
1831 | @end iftex | |
1832 | @ifnottex | |
1833 | (@pxref{Customizing VC}). | |
1834 | @end ifnottex | |
1835 | On the other hand, if there are no files already registered, Emacs uses | |
45ca30f2 KB |
1836 | the first system from @code{vc-handled-backends} that could register |
1837 | the file (for example, you cannot register a file under CVS if its | |
1838 | directory is not already part of a CVS tree); with the default value | |
1839 | of @code{vc-handled-backends}, this means that Emacs uses RCS in this | |
1840 | situation. | |
6bf7aab6 DL |
1841 | |
1842 | If locking is in use, @kbd{C-x v i} leaves the file unlocked and | |
576c4a0f | 1843 | read-only. Type @kbd{C-x v v} if you wish to start editing it. After |
6bf7aab6 | 1844 | registering a file with CVS, you must subsequently commit the initial |
c5d36b03 RS |
1845 | version by typing @kbd{C-x v v}. Until you do that, the version |
1846 | appears as @samp{@@@@} in the mode line. | |
6bf7aab6 DL |
1847 | |
1848 | @vindex vc-default-init-version | |
37b844b9 | 1849 | @cindex initial version number to register |
6bf7aab6 DL |
1850 | The initial version number for a newly registered file is 1.1, by |
1851 | default. You can specify a different default by setting the variable | |
1852 | @code{vc-default-init-version}, or you can give @kbd{C-x v i} a numeric | |
1853 | argument; then it reads the initial version number for this particular | |
1854 | file using the minibuffer. | |
1855 | ||
1856 | @vindex vc-initial-comment | |
1857 | If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an | |
1858 | initial comment to describe the purpose of this source file. Reading | |
1859 | the initial comment works like reading a log entry (@pxref{Log Buffer}). | |
1860 | ||
1861 | @node VC Status | |
1862 | @subsubsection VC Status Commands | |
1863 | ||
1864 | @table @kbd | |
1865 | @item C-x v l | |
1866 | Display version control state and change history. | |
1867 | @end table | |
1868 | ||
1869 | @kindex C-x v l | |
1870 | @findex vc-print-log | |
1871 | To view the detailed version control status and history of a file, | |
1872 | type @kbd{C-x v l} (@code{vc-print-log}). It displays the history of | |
1873 | changes to the current file, including the text of the log entries. The | |
7436d3ff RS |
1874 | output appears in a separate window. The point is centered at the |
1875 | revision of the file that is currently being visited. | |
1876 | ||
50a1bd4f RS |
1877 | In the change log buffer, you can use the following keys to move |
1878 | between the logs of revisions and of files, to view past revisions, and | |
7436d3ff RS |
1879 | to view diffs: |
1880 | ||
1881 | @table @kbd | |
1882 | @item p | |
1883 | Move to the previous revision-item in the buffer. (Revision entries in the log | |
1884 | buffer are usually in reverse-chronological order, so the previous | |
1885 | revision-item usually corresponds to a newer revision.) A numeric | |
1886 | prefix argument is a repeat count. | |
1887 | ||
1888 | @item n | |
1889 | Move to the next revision-item (which most often corresponds to the | |
1890 | previous revision of the file). A numeric prefix argument is a repeat | |
1891 | count. | |
1892 | ||
7436d3ff RS |
1893 | @item P |
1894 | Move to the log of the previous file, when the logs of multiple files | |
844040f3 EZ |
1895 | are in the log buffer |
1896 | @iftex | |
1897 | (@pxref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}). | |
1898 | @end iftex | |
1899 | @ifnottex | |
1900 | (@pxref{VC Dired Mode}). | |
1901 | @end ifnottex | |
1902 | Otherwise, just move to the beginning of the log. A numeric prefix | |
1903 | argument is a repeat count, so @kbd{C-u 10 P} would move backward 10 | |
1904 | files. | |
7436d3ff RS |
1905 | |
1906 | @item N | |
1907 | Move to the log of the next file, when the logs of multiple files are | |
844040f3 EZ |
1908 | in the log buffer |
1909 | @iftex | |
1910 | (@pxref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}). | |
1911 | @end iftex | |
1912 | @ifnottex | |
1913 | (@pxref{VC Dired Mode}). | |
1914 | @end ifnottex | |
1915 | It also takes a numeric prefix argument as a repeat count. | |
11cfab98 JL |
1916 | |
1917 | @item f | |
1918 | Visit the revision indicated at the current line, like typing @kbd{C-x | |
1919 | v ~} and specifying this revision's number (@pxref{Old Versions}). | |
1920 | ||
1921 | @item d | |
1922 | Display the diff (@pxref{Comparing Files}) between the revision | |
1923 | indicated at the current line and the next earlier revision. This is | |
1924 | useful to see what actually changed when the revision indicated on the | |
1925 | current line was committed. | |
7436d3ff | 1926 | @end table |
6bf7aab6 DL |
1927 | |
1928 | @node VC Undo | |
1929 | @subsubsection Undoing Version Control Actions | |
1930 | ||
1931 | @table @kbd | |
1932 | @item C-x v u | |
4ed53daa AS |
1933 | Revert the buffer and the file to the version from which you started |
1934 | editing the file. | |
6bf7aab6 DL |
1935 | |
1936 | @item C-x v c | |
1937 | Remove the last-entered change from the master for the visited file. | |
1938 | This undoes your last check-in. | |
1939 | @end table | |
1940 | ||
1941 | @kindex C-x v u | |
1942 | @findex vc-revert-buffer | |
1943 | If you want to discard your current set of changes and revert to the | |
4ed53daa AS |
1944 | version from which you started editing the file, use @kbd{C-x v u} |
1945 | (@code{vc-revert-buffer}). This leaves the file unlocked; if locking | |
1946 | is in use, you must first lock the file again before you change it | |
1947 | again. @kbd{C-x v u} requires confirmation, unless it sees that you | |
1948 | haven't made any changes with respect to the master version. | |
6bf7aab6 DL |
1949 | |
1950 | @kbd{C-x v u} is also the command to unlock a file if you lock it and | |
1951 | then decide not to change it. | |
1952 | ||
1953 | @kindex C-x v c | |
1954 | @findex vc-cancel-version | |
1955 | To cancel a change that you already checked in, use @kbd{C-x v c} | |
1956 | (@code{vc-cancel-version}). This command discards all record of the | |
4ed53daa AS |
1957 | most recent checked-in version, but only if your work file corresponds |
1958 | to that version---you cannot use @kbd{C-x v c} to cancel a version | |
1959 | that is not the latest on its branch. @kbd{C-x v c} also offers to | |
1960 | revert your work file and buffer to the previous version (the one that | |
1961 | precedes the version that is deleted). | |
6bf7aab6 DL |
1962 | |
1963 | If you answer @kbd{no}, VC keeps your changes in the buffer, and locks | |
1964 | the file. The no-revert option is useful when you have checked in a | |
1965 | change and then discover a trivial error in it; you can cancel the | |
1966 | erroneous check-in, fix the error, and check the file in again. | |
1967 | ||
1968 | When @kbd{C-x v c} does not revert the buffer, it unexpands all | |
844040f3 EZ |
1969 | version control headers in the buffer instead |
1970 | @iftex | |
1971 | (@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}). | |
1972 | @end iftex | |
1973 | @ifnottex | |
1974 | (@pxref{Version Headers}). | |
1975 | @end ifnottex | |
1976 | This is because the buffer no longer corresponds to any existing | |
1977 | version. If you check it in again, the check-in process will expand | |
1978 | the headers properly for the new version number. | |
6bf7aab6 DL |
1979 | |
1980 | However, it is impossible to unexpand the RCS @samp{@w{$}Log$} header | |
1981 | automatically. If you use that header feature, you have to unexpand it | |
1982 | by hand---by deleting the entry for the version that you just canceled. | |
1983 | ||
1984 | Be careful when invoking @kbd{C-x v c}, as it is easy to lose a lot of | |
1985 | work with it. To help you be careful, this command always requires | |
1986 | confirmation with @kbd{yes}. Note also that this command is disabled | |
1987 | under CVS, because canceling versions is very dangerous and discouraged | |
1988 | with CVS. | |
1989 | ||
844040f3 EZ |
1990 | @ifnottex |
1991 | @c vc1-xtra.texi needs extra level of lowering. | |
1992 | @lowersections | |
1993 | @include vc1-xtra.texi | |
1994 | @raisesections | |
1995 | @end ifnottex | |
1996 | ||
6bf7aab6 DL |
1997 | @node Branches |
1998 | @subsection Multiple Branches of a File | |
1999 | @cindex branch (version control) | |
2000 | @cindex trunk (version control) | |
2001 | ||
2002 | One use of version control is to maintain multiple ``current'' | |
2003 | versions of a file. For example, you might have different versions of a | |
2004 | program in which you are gradually adding various unfinished new | |
2005 | features. Each such independent line of development is called a | |
2006 | @dfn{branch}. VC allows you to create branches, switch between | |
2007 | different branches, and merge changes from one branch to another. | |
a0554a40 | 2008 | Please note, however, that branches are not supported for SCCS. |
6bf7aab6 DL |
2009 | |
2010 | A file's main line of development is usually called the @dfn{trunk}. | |
2011 | The versions on the trunk are normally numbered 1.1, 1.2, 1.3, etc. At | |
2012 | any such version, you can start an independent branch. A branch | |
2013 | starting at version 1.2 would have version number 1.2.1.1, and consecutive | |
2014 | versions on this branch would have numbers 1.2.1.2, 1.2.1.3, 1.2.1.4, | |
2015 | and so on. If there is a second branch also starting at version 1.2, it | |
2016 | would consist of versions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc. | |
2017 | ||
2018 | @cindex head version | |
2019 | If you omit the final component of a version number, that is called a | |
2020 | @dfn{branch number}. It refers to the highest existing version on that | |
2021 | branch---the @dfn{head version} of that branch. The branches in the | |
2022 | example above have branch numbers 1.2.1 and 1.2.2. | |
2023 | ||
2024 | @menu | |
2025 | * Switching Branches:: How to get to another existing branch. | |
2026 | * Creating Branches:: How to start a new branch. | |
2027 | * Merging:: Transferring changes between branches. | |
177c0ea7 | 2028 | * Multi-User Branching:: Multiple users working at multiple branches |
6bf7aab6 DL |
2029 | in parallel. |
2030 | @end menu | |
2031 | ||
2032 | @node Switching Branches | |
2033 | @subsubsection Switching between Branches | |
2034 | ||
576c4a0f | 2035 | To switch between branches, type @kbd{C-u C-x v v} and specify the |
6bf7aab6 DL |
2036 | version number you want to select. This version is then visited |
2037 | @emph{unlocked} (write-protected), so you can examine it before locking | |
2038 | it. Switching branches in this way is allowed only when the file is not | |
2039 | locked. | |
2040 | ||
2041 | You can omit the minor version number, thus giving only the branch | |
2042 | number; this takes you to the head version on the chosen branch. If you | |
7d5e745e | 2043 | only type @key{RET}, Emacs goes to the highest version on the trunk. |
6bf7aab6 DL |
2044 | |
2045 | After you have switched to any branch (including the main branch), you | |
2046 | stay on it for subsequent VC commands, until you explicitly select some | |
2047 | other branch. | |
2048 | ||
2049 | @node Creating Branches | |
2050 | @subsubsection Creating New Branches | |
2051 | ||
2052 | To create a new branch from a head version (one that is the latest in | |
2053 | the branch that contains it), first select that version if necessary, | |
576c4a0f AS |
2054 | lock it with @kbd{C-x v v}, and make whatever changes you want. Then, |
2055 | when you check in the changes, use @kbd{C-u C-x v v}. This lets you | |
6bf7aab6 DL |
2056 | specify the version number for the new version. You should specify a |
2057 | suitable branch number for a branch starting at the current version. | |
2058 | For example, if the current version is 2.5, the branch number should be | |
2059 | 2.5.1, 2.5.2, and so on, depending on the number of existing branches at | |
2060 | that point. | |
2061 | ||
2062 | To create a new branch at an older version (one that is no longer the | |
2063 | head of a branch), first select that version (@pxref{Switching | |
576c4a0f | 2064 | Branches}), then lock it with @kbd{C-x v v}. You'll be asked to |
6bf7aab6 DL |
2065 | confirm, when you lock the old version, that you really mean to create a |
2066 | new branch---if you say no, you'll be offered a chance to lock the | |
2067 | latest version instead. | |
2068 | ||
576c4a0f | 2069 | Then make your changes and type @kbd{C-x v v} again to check in a new |
6bf7aab6 DL |
2070 | version. This automatically creates a new branch starting from the |
2071 | selected version. You need not specially request a new branch, because | |
2072 | that's the only way to add a new version at a point that is not the head | |
2073 | of a branch. | |
2074 | ||
2075 | After the branch is created, you ``stay'' on it. That means that | |
2076 | subsequent check-ins create new versions on that branch. To leave the | |
2077 | branch, you must explicitly select a different version with @kbd{C-u C-x | |
576c4a0f | 2078 | v v}. To transfer changes from one branch to another, use the merge |
6bf7aab6 DL |
2079 | command, described in the next section. |
2080 | ||
2081 | @node Merging | |
2082 | @subsubsection Merging Branches | |
2083 | ||
2084 | @cindex merging changes | |
2085 | When you have finished the changes on a certain branch, you will | |
2086 | often want to incorporate them into the file's main line of development | |
2087 | (the trunk). This is not a trivial operation, because development might | |
2088 | also have proceeded on the trunk, so that you must @dfn{merge} the | |
2089 | changes into a file that has already been changed otherwise. VC allows | |
2090 | you to do this (and other things) with the @code{vc-merge} command. | |
2091 | ||
2092 | @table @kbd | |
2093 | @item C-x v m (vc-merge) | |
2094 | Merge changes into the work file. | |
2095 | @end table | |
2096 | ||
2097 | @kindex C-x v m | |
2098 | @findex vc-merge | |
2099 | @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it | |
ad63cf1d AS |
2100 | into the current version of the work file. It firsts asks you in the |
2101 | minibuffer where the changes should come from. If you just type | |
7d5e745e | 2102 | @key{RET}, Emacs merges any changes that were made on the same branch |
ad63cf1d AS |
2103 | since you checked the file out (we call this @dfn{merging the news}). |
2104 | This is the common way to pick up recent changes from the repository, | |
2105 | regardless of whether you have already changed the file yourself. | |
2106 | ||
2107 | You can also enter a branch number or a pair of version numbers in | |
0cf729ce RS |
2108 | the minibuffer. Then @kbd{C-x v m} finds the changes from that |
2109 | branch, or the differences between the two versions you specified, and | |
2110 | merges them into the current version of the current file. | |
6bf7aab6 DL |
2111 | |
2112 | As an example, suppose that you have finished a certain feature on | |
2113 | branch 1.3.1. In the meantime, development on the trunk has proceeded | |
2114 | to version 1.5. To merge the changes from the branch to the trunk, | |
576c4a0f | 2115 | first go to the head version of the trunk, by typing @kbd{C-u C-x v v |
7d5e745e | 2116 | @key{RET}}. Version 1.5 is now current. If locking is used for the file, |
576c4a0f | 2117 | type @kbd{C-x v v} to lock version 1.5 so that you can change it. Next, |
7d5e745e | 2118 | type @kbd{C-x v m 1.3.1 @key{RET}}. This takes the entire set of changes on |
6bf7aab6 DL |
2119 | branch 1.3.1 (relative to version 1.3, where the branch started, up to |
2120 | the last version on the branch) and merges it into the current version | |
2121 | of the work file. You can now check in the changed file, thus creating | |
2122 | version 1.6 containing the changes from the branch. | |
2123 | ||
2124 | It is possible to do further editing after merging the branch, before | |
2125 | the next check-in. But it is usually wiser to check in the merged | |
2126 | version, then lock it and make the further changes. This will keep | |
2127 | a better record of the history of changes. | |
2128 | ||
2129 | @cindex conflicts | |
2130 | @cindex resolving conflicts | |
2131 | When you merge changes into a file that has itself been modified, the | |
2132 | changes might overlap. We call this situation a @dfn{conflict}, and | |
2133 | reconciling the conflicting changes is called @dfn{resolving a | |
2134 | conflict}. | |
2135 | ||
2136 | Whenever conflicts occur during merging, VC detects them, tells you | |
2137 | about them in the echo area, and asks whether you want help in merging. | |
2138 | If you say yes, it starts an Ediff session (@pxref{Top, | |
2139 | Ediff, Ediff, ediff, The Ediff Manual}). | |
2140 | ||
2141 | If you say no, the conflicting changes are both inserted into the | |
2142 | file, surrounded by @dfn{conflict markers}. The example below shows how | |
2143 | a conflict region looks; the file is called @samp{name} and the current | |
2144 | master file version with user B's changes in it is 1.11. | |
2145 | ||
2146 | @c @w here is so CVS won't think this is a conflict. | |
2147 | @smallexample | |
2148 | @group | |
2149 | @w{<}<<<<<< name | |
2150 | @var{User A's version} | |
2151 | ======= | |
2152 | @var{User B's version} | |
2153 | @w{>}>>>>>> 1.11 | |
2154 | @end group | |
2155 | @end smallexample | |
2156 | ||
2157 | @cindex vc-resolve-conflicts | |
2158 | Then you can resolve the conflicts by editing the file manually. Or | |
2159 | you can type @code{M-x vc-resolve-conflicts} after visiting the file. | |
0cf729ce RS |
2160 | This starts an Ediff session, as described above. Don't forget to |
2161 | check in the merged version afterwards. | |
6bf7aab6 DL |
2162 | |
2163 | @node Multi-User Branching | |
2164 | @subsubsection Multi-User Branching | |
2165 | ||
2166 | It is often useful for multiple developers to work simultaneously on | |
2167 | different branches of a file. CVS allows this by default; for RCS, it | |
2168 | is possible if you create multiple source directories. Each source | |
2169 | directory should have a link named @file{RCS} which points to a common | |
2170 | directory of RCS master files. Then each source directory can have its | |
2171 | own choice of selected versions, but all share the same common RCS | |
2172 | records. | |
2173 | ||
2174 | This technique works reliably and automatically, provided that the | |
844040f3 EZ |
2175 | source files contain RCS version headers |
2176 | @iftex | |
2177 | (@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}). | |
2178 | @end iftex | |
2179 | @ifnottex | |
2180 | (@pxref{Version Headers}). | |
2181 | @end ifnottex | |
2182 | The headers enable Emacs to be sure, at all times, which version | |
2183 | number is present in the work file. | |
6bf7aab6 DL |
2184 | |
2185 | If the files do not have version headers, you must instead tell Emacs | |
2186 | explicitly in each session which branch you are working on. To do this, | |
576c4a0f | 2187 | first find the file, then type @kbd{C-u C-x v v} and specify the correct |
6bf7aab6 DL |
2188 | branch number. This ensures that Emacs knows which branch it is using |
2189 | during this particular editing session. | |
2190 | ||
844040f3 EZ |
2191 | @ifnottex |
2192 | @include vc2-xtra.texi | |
2193 | @end ifnottex | |
2194 | ||
6bf7aab6 DL |
2195 | @node Directories |
2196 | @section File Directories | |
2197 | ||
2198 | @cindex file directory | |
2199 | @cindex directory listing | |
2200 | The file system groups files into @dfn{directories}. A @dfn{directory | |
2201 | listing} is a list of all the files in a directory. Emacs provides | |
2202 | commands to create and delete directories, and to make directory | |
2203 | listings in brief format (file names only) and verbose format (sizes, | |
50a1bd4f RS |
2204 | dates, and authors included). Emacs also includes a directory browser |
2205 | feature called Dired; see @ref{Dired}. | |
6bf7aab6 DL |
2206 | |
2207 | @table @kbd | |
2208 | @item C-x C-d @var{dir-or-pattern} @key{RET} | |
2209 | Display a brief directory listing (@code{list-directory}). | |
2210 | @item C-u C-x C-d @var{dir-or-pattern} @key{RET} | |
2211 | Display a verbose directory listing. | |
2212 | @item M-x make-directory @key{RET} @var{dirname} @key{RET} | |
2213 | Create a new directory named @var{dirname}. | |
2214 | @item M-x delete-directory @key{RET} @var{dirname} @key{RET} | |
2215 | Delete the directory named @var{dirname}. It must be empty, | |
2216 | or you get an error. | |
2217 | @end table | |
2218 | ||
2219 | @findex list-directory | |
2220 | @kindex C-x C-d | |
2221 | The command to display a directory listing is @kbd{C-x C-d} | |
2222 | (@code{list-directory}). It reads using the minibuffer a file name | |
2223 | which is either a directory to be listed or a wildcard-containing | |
2224 | pattern for the files to be listed. For example, | |
2225 | ||
2226 | @example | |
2227 | C-x C-d /u2/emacs/etc @key{RET} | |
2228 | @end example | |
2229 | ||
2230 | @noindent | |
2231 | lists all the files in directory @file{/u2/emacs/etc}. Here is an | |
2232 | example of specifying a file name pattern: | |
2233 | ||
2234 | @example | |
2235 | C-x C-d /u2/emacs/src/*.c @key{RET} | |
2236 | @end example | |
2237 | ||
1ba2ce68 | 2238 | Normally, @kbd{C-x C-d} displays a brief directory listing containing |
6bf7aab6 | 2239 | just file names. A numeric argument (regardless of value) tells it to |
d3ff0a57 | 2240 | make a verbose listing including sizes, dates, and owners (like |
6bf7aab6 DL |
2241 | @samp{ls -l}). |
2242 | ||
2243 | @vindex list-directory-brief-switches | |
2244 | @vindex list-directory-verbose-switches | |
b3c8fa05 RS |
2245 | The text of a directory listing is mostly obtained by running |
2246 | @code{ls} in an inferior process. Two Emacs variables control the | |
2247 | switches passed to @code{ls}: @code{list-directory-brief-switches} is | |
2248 | a string giving the switches to use in brief listings (@code{"-CF"} by | |
2249 | default), and @code{list-directory-verbose-switches} is a string | |
2250 | giving the switches to use in a verbose listing (@code{"-l"} by | |
2251 | default). | |
2252 | ||
2253 | @vindex directory-free-space-program | |
2254 | @vindex directory-free-space-args | |
50a1bd4f RS |
2255 | In verbose directory listings, Emacs adds information about the |
2256 | amount of free space on the disk that contains the directory. To do | |
2257 | this, it runs the program specified by | |
2258 | @code{directory-free-space-program} with arguments | |
b3c8fa05 | 2259 | @code{directory-free-space-args}. |
6bf7aab6 DL |
2260 | |
2261 | @node Comparing Files | |
2262 | @section Comparing Files | |
2263 | @cindex comparing files | |
2264 | ||
2265 | @findex diff | |
2266 | @vindex diff-switches | |
2267 | The command @kbd{M-x diff} compares two files, displaying the | |
0cf729ce RS |
2268 | differences in an Emacs buffer named @samp{*diff*}. It works by |
2269 | running the @code{diff} program, using options taken from the variable | |
2270 | @code{diff-switches}. The value of @code{diff-switches} should be a | |
2271 | string; the default is @code{"-c"} to specify a context diff. | |
5004f8d3 RS |
2272 | @xref{Top,, Diff, diff, Comparing and Merging Files}, for more |
2273 | information about @command{diff} output formats. | |
6bf7aab6 | 2274 | |
6bf7aab6 DL |
2275 | @findex diff-backup |
2276 | The command @kbd{M-x diff-backup} compares a specified file with its most | |
2277 | recent backup. If you specify the name of a backup file, | |
2278 | @code{diff-backup} compares it with the source file that it is a backup | |
2279 | of. | |
2280 | ||
2281 | @findex compare-windows | |
ce08e7d4 RS |
2282 | The command @kbd{M-x compare-windows} compares the text in the |
2283 | current window with that in the next window. (For more information | |
2284 | about windows in Emacs, @ref{Windows}.) Comparison starts at point in | |
2285 | each window, after pushing each initial point value on the mark ring | |
2286 | in its respective buffer. Then it moves point forward in each window, | |
2287 | one character at a time, until it reaches characters that don't match. | |
2288 | Then the command exits. | |
2289 | ||
2290 | If point in the two windows is followed by non-matching text when | |
50a1bd4f RS |
2291 | the command starts, @kbd{M-x compare-windows} tries heuristically to |
2292 | advance up to matching text in the two windows, and then exits. So if | |
2293 | you use @kbd{M-x compare-windows} repeatedly, each time it either | |
2294 | skips one matching range or finds the start of another. | |
6bf7aab6 DL |
2295 | |
2296 | @vindex compare-ignore-case | |
3aff69e3 | 2297 | @vindex compare-ignore-whitespace |
6bf7aab6 DL |
2298 | With a numeric argument, @code{compare-windows} ignores changes in |
2299 | whitespace. If the variable @code{compare-ignore-case} is | |
3aff69e3 | 2300 | non-@code{nil}, the comparison ignores differences in case as well. |
a0554a40 | 2301 | If the variable @code{compare-ignore-whitespace} is non-@code{nil}, |
3aff69e3 RS |
2302 | @code{compare-windows} normally ignores changes in whitespace, and a |
2303 | prefix argument turns that off. | |
6bf7aab6 | 2304 | |
fa474484 DL |
2305 | @cindex Smerge mode |
2306 | @findex smerge-mode | |
2307 | @cindex failed merges | |
2308 | @cindex merges, failed | |
089d639f | 2309 | @cindex comparing 3 files (@code{diff3}) |
f02d86a3 RS |
2310 | You can use @kbd{M-x smerge-mode} to turn on Smerge mode, a minor |
2311 | mode for editing output from the @command{diff3} program. This is | |
2312 | typically the result of a failed merge from a version control system | |
2313 | ``update'' outside VC, due to conflicting changes to a file. Smerge | |
2314 | mode provides commands to resolve conflicts by selecting specific | |
2315 | changes. | |
2316 | ||
844040f3 | 2317 | @iftex |
9dc999d3 | 2318 | @xref{Emerge,,, emacs-xtra, Specialized Emacs Features}, |
844040f3 EZ |
2319 | @end iftex |
2320 | @ifnottex | |
2321 | @xref{Emerge}, | |
2322 | @end ifnottex | |
2323 | for the Emerge facility, which provides a powerful interface for | |
2324 | merging files. | |
6bf7aab6 | 2325 | |
5004f8d3 RS |
2326 | @node Diff Mode |
2327 | @section Diff Mode | |
2328 | @cindex Diff mode | |
2329 | @findex diff-mode | |
2330 | @cindex patches, editing | |
2331 | ||
6ce1d379 RS |
2332 | Diff mode is used for the output of @kbd{M-x diff}; it is also |
2333 | useful for editing patches and comparisons produced by the | |
2334 | @command{diff} program. To select Diff mode manually, type @kbd{M-x | |
2335 | diff-mode}. | |
5004f8d3 RS |
2336 | |
2337 | One general feature of Diff mode is that manual edits to the patch | |
2338 | automatically correct line numbers, including those in the hunk | |
2339 | header, so that you can actually apply the edited patch. Diff mode | |
5a7f4c1b | 2340 | treats each hunk location as an ``error message,'' so that you can use |
59767336 RS |
2341 | commands such as @kbd{C-x '} to visit the corresponding source |
2342 | locations. It also provides the following commands to navigate, | |
2343 | manipulate and apply parts of patches: | |
5004f8d3 RS |
2344 | |
2345 | @table @kbd | |
2346 | @item M-n | |
2347 | Move to the next hunk-start (@code{diff-hunk-next}). | |
2348 | ||
2349 | @item M-p | |
2350 | Move to the previous hunk-start (@code{diff-hunk-prev}). | |
2351 | ||
2352 | @item M-@} | |
2353 | Move to the next file-start, in a multi-file patch | |
2354 | (@code{diff-file-next}). | |
2355 | ||
2356 | @item M-@{ | |
2357 | Move to the previous file-start, in a multi-file patch | |
2358 | (@code{diff-file-prev}). | |
2359 | ||
2360 | @item M-k | |
2361 | Kill the hunk at point (@code{diff-hunk-kill}). | |
2362 | ||
2363 | @item M-K | |
2364 | In a multi-file patch, kill the current file part. | |
2365 | (@code{diff-file-kill}). | |
2366 | ||
2367 | @item C-c C-a | |
2368 | Apply this hunk to its target file (@code{diff-apply-hunk}). With a | |
2369 | prefix argument of @kbd{C-u}, revert this hunk. | |
2370 | ||
2371 | @item C-c C-c | |
2372 | Go to the source corresponding to this hunk (@code{diff-goto-source}). | |
2373 | ||
2374 | @item C-c C-e | |
2375 | Start an Ediff session with the patch (@code{diff-ediff-patch}). | |
2376 | @xref{Top, Ediff, Ediff, ediff, The Ediff Manual}. | |
2377 | ||
2378 | @item C-c C-n | |
2379 | Restrict the view to the current hunk (@code{diff-restrict-view}). | |
2380 | @xref{Narrowing}. With a prefix argument of @kbd{C-u}, restrict the | |
2381 | view to the current patch of a multiple file patch. To widen again, | |
2382 | use @kbd{C-x n w}. | |
2383 | ||
2384 | @item C-c C-r | |
2385 | Reverse the direction of comparison for the entire buffer | |
2386 | (@code{diff-reverse-direction}). | |
2387 | ||
2388 | @item C-c C-s | |
2389 | Split the hunk at point (@code{diff-split-hunk}). This is for | |
2390 | manually editing patches, and only works with the unified diff format. | |
2391 | ||
2392 | @item C-c C-u | |
2393 | Convert the entire buffer to unified format | |
2394 | (@code{diff-context->unified}). With a prefix argument, convert | |
2395 | unified format to context format. In Transient Mark mode, when the | |
2396 | mark is active, this command operates only on the region. | |
2397 | ||
2398 | @item C-c C-w | |
2399 | Refine the current hunk so that it disregards changes in whitespace | |
2400 | (@code{diff-refine-hunk}). | |
2401 | @end table | |
2402 | ||
2403 | @kbd{C-x 4 a} in Diff mode operates on behalf of the target file, | |
2404 | but gets the function name from the patch itself. @xref{Change Log}. | |
2405 | This is useful for making log entries for functions that are deleted | |
2406 | by the patch. | |
2407 | ||
6bf7aab6 DL |
2408 | @node Misc File Ops |
2409 | @section Miscellaneous File Operations | |
2410 | ||
2411 | Emacs has commands for performing many other operations on files. | |
2412 | All operate on one file; they do not accept wildcard file names. | |
2413 | ||
2414 | @findex view-file | |
2415 | @cindex viewing | |
2416 | @cindex View mode | |
2417 | @cindex mode, View | |
2418 | @kbd{M-x view-file} allows you to scan or read a file by sequential | |
2419 | screenfuls. It reads a file name argument using the minibuffer. After | |
2420 | reading the file into an Emacs buffer, @code{view-file} displays the | |
2421 | beginning. You can then type @key{SPC} to scroll forward one windowful, | |
2422 | or @key{DEL} to scroll backward. Various other commands are provided | |
2423 | for moving around in the file, but none for changing it; type @kbd{?} | |
2424 | while viewing for a list of them. They are mostly the same as normal | |
2425 | Emacs cursor motion commands. To exit from viewing, type @kbd{q}. | |
2e3c33de | 2426 | The commands for viewing are defined by a special minor mode called View |
6bf7aab6 DL |
2427 | mode. |
2428 | ||
2429 | A related command, @kbd{M-x view-buffer}, views a buffer already present | |
2430 | in Emacs. @xref{Misc Buffer}. | |
2431 | ||
0cf729ce | 2432 | @kindex C-x i |
6bf7aab6 | 2433 | @findex insert-file |
0cf729ce RS |
2434 | @kbd{M-x insert-file} (also @kbd{C-x i}) inserts a copy of the |
2435 | contents of the specified file into the current buffer at point, | |
2436 | leaving point unchanged before the contents and the mark after them. | |
6bf7aab6 | 2437 | |
8adbd6c2 | 2438 | @findex insert-file-literally |
dcf3396e CY |
2439 | @kbd{M-x insert-file-literally} is like @kbd{M-x insert-file}, |
2440 | except the file is inserted ``literally'': it is treated as a sequence | |
2441 | of @acronym{ASCII} characters with no special encoding or conversion, | |
2442 | similar to the @kbd{M-x find-file-literally} command | |
2443 | (@pxref{Visiting}). | |
8adbd6c2 | 2444 | |
6bf7aab6 DL |
2445 | @findex write-region |
2446 | @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it | |
2447 | copies the contents of the region into the specified file. @kbd{M-x | |
81a35977 RS |
2448 | append-to-file} adds the text of the region to the end of the |
2449 | specified file. @xref{Accumulating Text}. The variable | |
2450 | @code{write-region-inhibit-fsync} applies to these commands, as well | |
2451 | as saving files; see @ref{Customize Save}. | |
6bf7aab6 DL |
2452 | |
2453 | @findex delete-file | |
2454 | @cindex deletion (of files) | |
2455 | @kbd{M-x delete-file} deletes the specified file, like the @code{rm} | |
2456 | command in the shell. If you are deleting many files in one directory, it | |
2457 | may be more convenient to use Dired (@pxref{Dired}). | |
2458 | ||
2459 | @findex rename-file | |
2460 | @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using | |
0cf729ce | 2461 | the minibuffer, then renames file @var{old} as @var{new}. If the file name |
6bf7aab6 DL |
2462 | @var{new} already exists, you must confirm with @kbd{yes} or renaming is not |
2463 | done; this is because renaming causes the old meaning of the name @var{new} | |
2464 | to be lost. If @var{old} and @var{new} are on different file systems, the | |
2465 | file @var{old} is copied and deleted. | |
2466 | ||
3aff69e3 RS |
2467 | If the argument @var{new} is just a directory name, the real new |
2468 | name is in that directory, with the same non-directory component as | |
2469 | @var{old}. For example, @kbd{M-x rename-file RET ~/foo RET /tmp RET} | |
2470 | renames @file{~/foo} to @file{/tmp/foo}. The same rule applies to all | |
2471 | the remaining commands in this section. All of them ask for | |
2472 | confirmation when the new file name already exists, too. | |
2473 | ||
6bf7aab6 | 2474 | @findex add-name-to-file |
0cf729ce | 2475 | @cindex hard links (creation) |
6bf7aab6 DL |
2476 | The similar command @kbd{M-x add-name-to-file} is used to add an |
2477 | additional name to an existing file without removing its old name. | |
0cf729ce | 2478 | The new name is created as a ``hard link'' to the existing file. |
6bf7aab6 | 2479 | The new name must belong on the same file system that the file is on. |
3aff69e3 | 2480 | On MS-Windows, this command works only if the file resides in an NTFS |
40c56a36 | 2481 | file system. On MS-DOS, it works by copying the file. |
6bf7aab6 DL |
2482 | |
2483 | @findex copy-file | |
2484 | @cindex copying files | |
3aff69e3 RS |
2485 | @kbd{M-x copy-file} reads the file @var{old} and writes a new file |
2486 | named @var{new} with the same contents. | |
6bf7aab6 DL |
2487 | |
2488 | @findex make-symbolic-link | |
f0725a6a | 2489 | @cindex symbolic links (creation) |
6bf7aab6 | 2490 | @kbd{M-x make-symbolic-link} reads two file names @var{target} and |
3aff69e3 RS |
2491 | @var{linkname}, then creates a symbolic link named @var{linkname}, |
2492 | which points at @var{target}. The effect is that future attempts to | |
2493 | open file @var{linkname} will refer to whatever file is named | |
2494 | @var{target} at the time the opening is done, or will get an error if | |
2495 | the name @var{target} is nonexistent at that time. This command does | |
2496 | not expand the argument @var{target}, so that it allows you to specify | |
2497 | a relative name as the target of the link. | |
2498 | ||
2499 | Not all systems support symbolic links; on systems that don't | |
2500 | support them, this command is not defined. | |
6bf7aab6 DL |
2501 | |
2502 | @node Compressed Files | |
2503 | @section Accessing Compressed Files | |
2504 | @cindex compression | |
2505 | @cindex uncompression | |
2506 | @cindex Auto Compression mode | |
2507 | @cindex mode, Auto Compression | |
2508 | @pindex gzip | |
2509 | ||
2bdeaecc | 2510 | Emacs automatically uncompresses compressed files when you visit |
158a07a8 | 2511 | them, and automatically recompresses them if you alter them and save |
2bdeaecc RS |
2512 | them. Emacs recognizes compressed files by their file names. File |
2513 | names ending in @samp{.gz} indicate a file compressed with | |
6bf7aab6 DL |
2514 | @code{gzip}. Other endings indicate other compression programs. |
2515 | ||
2516 | Automatic uncompression and compression apply to all the operations in | |
2517 | which Emacs uses the contents of a file. This includes visiting it, | |
2518 | saving it, inserting its contents into a buffer, loading it, and byte | |
2519 | compiling it. | |
2520 | ||
2bdeaecc RS |
2521 | @findex auto-compression-mode |
2522 | @vindex auto-compression-mode | |
2523 | To disable this feature, type the command @kbd{M-x | |
31909de7 | 2524 | auto-compression-mode}. You can disable it permanently by |
2bdeaecc RS |
2525 | customizing the variable @code{auto-compression-mode}. |
2526 | ||
259a88ca DL |
2527 | @node File Archives |
2528 | @section File Archives | |
2529 | @cindex mode, tar | |
2530 | @cindex Tar mode | |
089d639f | 2531 | @cindex file archives |
259a88ca | 2532 | |
f02d86a3 RS |
2533 | A file whose name ends in @samp{.tar} is normally an @dfn{archive} |
2534 | made by the @code{tar} program. Emacs views these files in a special | |
2535 | mode called Tar mode which provides a Dired-like list of the contents | |
2536 | (@pxref{Dired}). You can move around through the list just as you | |
2537 | would in Dired, and visit the subfiles contained in the archive. | |
2538 | However, not all Dired commands are available in Tar mode. | |
2539 | ||
50a1bd4f | 2540 | If Auto Compression mode is enabled (@pxref{Compressed Files}), then |
f02d86a3 RS |
2541 | Tar mode is used also for compressed archives---files with extensions |
2542 | @samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}. | |
259a88ca | 2543 | |
7d5e745e | 2544 | The keys @kbd{e}, @kbd{f} and @key{RET} all extract a component file |
50a1bd4f RS |
2545 | into its own buffer. You can edit it there, and if you save the |
2546 | buffer, the edited version will replace the version in the Tar buffer. | |
2547 | @kbd{v} extracts a file into a buffer in View mode. @kbd{o} extracts | |
2548 | the file and displays it in another window, so you could edit the file | |
2549 | and operate on the archive simultaneously. @kbd{d} marks a file for | |
366f22ff EZ |
2550 | deletion when you later use @kbd{x}, and @kbd{u} unmarks a file, as in |
2551 | Dired. @kbd{C} copies a file from the archive to disk and @kbd{R} | |
50a1bd4f RS |
2552 | renames a file within the archive. @kbd{g} reverts the buffer from |
2553 | the archive on disk. | |
366f22ff EZ |
2554 | |
2555 | The keys @kbd{M}, @kbd{G}, and @kbd{O} change the file's permission | |
2556 | bits, group, and owner, respectively. | |
2557 | ||
2558 | If your display supports colors and the mouse, moving the mouse | |
2559 | pointer across a file name highlights that file name, indicating that | |
2560 | you can click on it. Clicking @kbd{Mouse-2} on the highlighted file | |
2561 | name extracts the file into a buffer and displays that buffer. | |
2562 | ||
2563 | Saving the Tar buffer writes a new version of the archive to disk with | |
259a88ca DL |
2564 | the changes you made to the components. |
2565 | ||
f02d86a3 RS |
2566 | You don't need the @code{tar} program to use Tar mode---Emacs reads |
2567 | the archives directly. However, accessing compressed archives | |
2568 | requires the appropriate uncompression program. | |
fa474484 | 2569 | |
366f22ff EZ |
2570 | @cindex Archive mode |
2571 | @cindex mode, archive | |
259a88ca DL |
2572 | @cindex @code{arc} |
2573 | @cindex @code{jar} | |
2574 | @cindex @code{zip} | |
2575 | @cindex @code{lzh} | |
2576 | @cindex @code{zoo} | |
259a88ca DL |
2577 | @pindex arc |
2578 | @pindex jar | |
2579 | @pindex zip | |
2580 | @pindex lzh | |
2581 | @pindex zoo | |
2582 | @cindex Java class archives | |
366f22ff EZ |
2583 | @cindex unzip archives |
2584 | A separate but similar Archive mode is used for archives produced by | |
f02d86a3 RS |
2585 | the programs @code{arc}, @code{jar}, @code{lzh}, @code{zip}, and |
2586 | @code{zoo}, which have extensions corresponding to the program names. | |
a7535c24 CY |
2587 | Archive mode also works for those @code{exe} files that are |
2588 | self-extracting executables. | |
366f22ff | 2589 | |
d0960fb3 | 2590 | The key bindings of Archive mode are similar to those in Tar mode, |
f02d86a3 | 2591 | with the addition of the @kbd{m} key which marks a file for subsequent |
366f22ff | 2592 | operations, and @kbd{M-@key{DEL}} which unmarks all the marked files. |
f02d86a3 RS |
2593 | Also, the @kbd{a} key toggles the display of detailed file |
2594 | information, for those archive types where it won't fit in a single | |
2595 | line. Operations such as renaming a subfile, or changing its mode or | |
2596 | owner, are supported only for some of the archive formats. | |
366f22ff | 2597 | |
f02d86a3 RS |
2598 | Unlike Tar mode, Archive mode runs the archiving program to unpack |
2599 | and repack archives. Details of the program names and their options | |
2600 | can be set in the @samp{Archive} Customize group. However, you don't | |
d3ff0a57 RS |
2601 | need these programs to look at the archive table of contents, only to |
2602 | extract or manipulate the subfiles in the archive. | |
259a88ca | 2603 | |
6bf7aab6 DL |
2604 | @node Remote Files |
2605 | @section Remote Files | |
2606 | ||
63e889df | 2607 | @cindex Tramp |
6bf7aab6 DL |
2608 | @cindex FTP |
2609 | @cindex remote file access | |
83fa16cf KG |
2610 | You can refer to files on other machines using a special file name |
2611 | syntax: | |
6bf7aab6 DL |
2612 | |
2613 | @example | |
2614 | @group | |
2615 | /@var{host}:@var{filename} | |
2616 | /@var{user}@@@var{host}:@var{filename} | |
4f36dd62 | 2617 | /@var{user}@@@var{host}#@var{port}:@var{filename} |
83fa16cf KG |
2618 | /@var{method}:@var{user}@@@var{host}:@var{filename} |
2619 | /@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename} | |
6bf7aab6 DL |
2620 | @end group |
2621 | @end example | |
2622 | ||
2623 | @noindent | |
4a10556b RS |
2624 | To carry out this request, Emacs uses either the FTP program or a |
2625 | remote-login program such as @command{ssh}, @command{rlogin}, or | |
2626 | @command{telnet}. You can always specify in the file name which | |
2627 | method to use---for example, | |
ec6a646a | 2628 | @file{/ftp:@var{user}@@@var{host}:@var{filename}} uses FTP, whereas |
30f75e62 | 2629 | @file{/ssh:@var{user}@@@var{host}:@var{filename}} uses @command{ssh}. |
4a10556b RS |
2630 | When you don't specify a method in the file name, Emacs chooses |
2631 | the method as follows: | |
83fa16cf KG |
2632 | |
2633 | @enumerate | |
2634 | @item | |
4a10556b RS |
2635 | If the host name starts with @samp{ftp.} (with dot), then Emacs uses |
2636 | FTP. | |
83fa16cf | 2637 | @item |
4a10556b RS |
2638 | If the user name is @samp{ftp} or @samp{anonymous}, then Emacs uses |
2639 | FTP. | |
83fa16cf | 2640 | @item |
4a10556b | 2641 | Otherwise, Emacs uses @command{ssh}. |
83fa16cf | 2642 | @end enumerate |
63e889df KG |
2643 | |
2644 | @noindent | |
83fa16cf KG |
2645 | Remote file access through FTP is handled by the Ange-FTP package, which |
2646 | is documented in the following. Remote file access through the other | |
2647 | methods is handled by the Tramp package, which has its own manual. | |
2648 | @xref{Top, The Tramp Manual,, tramp, The Tramp Manual}. | |
2649 | ||
2650 | When the Ange-FTP package is used, Emacs logs in through FTP using your | |
2651 | user name or the name @var{user}. It may ask you for a password from | |
2652 | time to time; this is used for logging in on @var{host}. The form using | |
2653 | @var{port} allows you to access servers running on a non-default TCP | |
2654 | port. | |
63e889df | 2655 | |
436b2c06 EZ |
2656 | @cindex backups for remote files |
2657 | @vindex ange-ftp-make-backup-files | |
2658 | If you want to disable backups for remote files, set the variable | |
2659 | @code{ange-ftp-make-backup-files} to @code{nil}. | |
2660 | ||
5a2ce5f5 GM |
2661 | By default, the auto-save files (@pxref{Auto Save Files}) for remote |
2662 | files are made in the temporary file directory on the local machine. | |
2663 | This is achieved using the variable @code{auto-save-file-name-transforms}. | |
2664 | ||
6bf7aab6 DL |
2665 | @cindex ange-ftp |
2666 | @vindex ange-ftp-default-user | |
436b2c06 | 2667 | @cindex user name for remote file access |
6bf7aab6 DL |
2668 | Normally, if you do not specify a user name in a remote file name, |
2669 | that means to use your own user name. But if you set the variable | |
2670 | @code{ange-ftp-default-user} to a string, that string is used instead. | |
6bf7aab6 | 2671 | |
436b2c06 EZ |
2672 | @cindex anonymous FTP |
2673 | @vindex ange-ftp-generate-anonymous-password | |
2674 | To visit files accessible by anonymous FTP, you use special user | |
697e2b99 RS |
2675 | names @samp{anonymous} or @samp{ftp}. Passwords for these user names |
2676 | are handled specially. The variable | |
436b2c06 EZ |
2677 | @code{ange-ftp-generate-anonymous-password} controls what happens: if |
2678 | the value of this variable is a string, then that string is used as | |
2679 | the password; if non-@code{nil} (the default), then the value of | |
50a1bd4f RS |
2680 | @code{user-mail-address} is used; if @code{nil}, then Emacs prompts |
2681 | you for a password as usual. | |
436b2c06 EZ |
2682 | |
2683 | @cindex firewall, and accessing remote files | |
2684 | @cindex gateway, and remote file access with @code{ange-ftp} | |
2685 | @vindex ange-ftp-smart-gateway | |
2686 | @vindex ange-ftp-gateway-host | |
2687 | Sometimes you may be unable to access files on a remote machine | |
f02d86a3 RS |
2688 | because a @dfn{firewall} in between blocks the connection for security |
2689 | reasons. If you can log in on a @dfn{gateway} machine from which the | |
2690 | target files @emph{are} accessible, and whose FTP server supports | |
2691 | gatewaying features, you can still use remote file names; all you have | |
2692 | to do is specify the name of the gateway machine by setting the | |
2693 | variable @code{ange-ftp-gateway-host}, and set | |
2694 | @code{ange-ftp-smart-gateway} to @code{t}. Otherwise you may be able | |
2695 | to make remote file names work, but the procedure is complex. You can | |
2696 | read the instructions by typing @kbd{M-x finder-commentary @key{RET} | |
2697 | ange-ftp @key{RET}}. | |
436b2c06 | 2698 | |
6bf7aab6 | 2699 | @vindex file-name-handler-alist |
f02d86a3 | 2700 | @cindex disabling remote files |
4f36dd62 | 2701 | You can entirely turn off the FTP file name feature by removing the |
d3ff0a57 RS |
2702 | entries @code{ange-ftp-completion-hook-function} and |
2703 | @code{ange-ftp-hook-function} from the variable | |
7ed32bd8 DL |
2704 | @code{file-name-handler-alist}. You can turn off the feature in |
2705 | individual cases by quoting the file name with @samp{/:} (@pxref{Quoted | |
2706 | File Names}). | |
6bf7aab6 DL |
2707 | |
2708 | @node Quoted File Names | |
2709 | @section Quoted File Names | |
2710 | ||
2711 | @cindex quoting file names | |
7dc24a36 | 2712 | @cindex file names, quote special characters |
6bf7aab6 DL |
2713 | You can @dfn{quote} an absolute file name to prevent special |
2714 | characters and syntax in it from having their special effects. | |
2715 | The way to do this is to add @samp{/:} at the beginning. | |
2716 | ||
2717 | For example, you can quote a local file name which appears remote, to | |
2718 | prevent it from being treated as a remote file name. Thus, if you have | |
2719 | a directory named @file{/foo:} and a file named @file{bar} in it, you | |
2720 | can refer to that file in Emacs as @samp{/:/foo:/bar}. | |
2721 | ||
2722 | @samp{/:} can also prevent @samp{~} from being treated as a special | |
2723 | character for a user's home directory. For example, @file{/:/tmp/~hack} | |
2724 | refers to a file whose name is @file{~hack} in directory @file{/tmp}. | |
2725 | ||
e643ceae RS |
2726 | Quoting with @samp{/:} is also a way to enter in the minibuffer a |
2727 | file name that contains @samp{$}. In order for this to work, the | |
2728 | @samp{/:} must be at the beginning of the minibuffer contents. (You | |
d41d5dd4 | 2729 | can also double each @samp{$}; see @ref{File Names with $}.) |
6bf7aab6 DL |
2730 | |
2731 | You can also quote wildcard characters with @samp{/:}, for visiting. | |
e643ceae RS |
2732 | For example, @file{/:/tmp/foo*bar} visits the file |
2733 | @file{/tmp/foo*bar}. | |
2734 | ||
2735 | Another method of getting the same result is to enter | |
2736 | @file{/tmp/foo[*]bar}, which is a wildcard specification that matches | |
2737 | only @file{/tmp/foo*bar}. However, in many cases there is no need to | |
2738 | quote the wildcard characters because even unquoted they give the | |
2739 | right result. For example, if the only file name in @file{/tmp} that | |
2740 | starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar}, | |
2741 | then specifying @file{/tmp/foo*bar} will visit only | |
2742 | @file{/tmp/foo*bar}. | |
9a98ef18 | 2743 | |
f02d86a3 RS |
2744 | @node File Name Cache |
2745 | @section File Name Cache | |
2746 | ||
2747 | @cindex file name caching | |
2748 | @cindex cache of file names | |
2749 | @pindex find | |
2750 | @kindex C-@key{TAB} | |
2751 | @findex file-cache-minibuffer-complete | |
2752 | You can use the @dfn{file name cache} to make it easy to locate a | |
2753 | file by name, without having to remember exactly where it is located. | |
2754 | When typing a file name in the minibuffer, @kbd{C-@key{tab}} | |
2755 | (@code{file-cache-minibuffer-complete}) completes it using the file | |
2756 | name cache. If you repeat @kbd{C-@key{tab}}, that cycles through the | |
eba54dd4 EZ |
2757 | possible completions of what you had originally typed. (However, note |
2758 | that the @kbd{C-@key{tab}} character cannot be typed on most text-only | |
2759 | terminals.) | |
f02d86a3 RS |
2760 | |
2761 | The file name cache does not fill up automatically. Instead, you | |
2762 | load file names into the cache using these commands: | |
9a98ef18 | 2763 | |
f02d86a3 | 2764 | @findex file-cache-add-directory |
fa474484 | 2765 | @table @kbd |
fa474484 | 2766 | @item M-x file-cache-add-directory @key{RET} @var{directory} @key{RET} |
f02d86a3 RS |
2767 | Add each file name in @var{directory} to the file name cache. |
2768 | @item M-x file-cache-add-directory-using-find @key{RET} @var{directory} @key{RET} | |
2769 | Add each file name in @var{directory} and all of its nested | |
2770 | subdirectories to the file name cache. | |
2771 | @item M-x file-cache-add-directory-using-locate @key{RET} @var{directory} @key{RET} | |
2772 | Add each file name in @var{directory} and all of its nested | |
2773 | subdirectories to the file name cache, using @command{locate} to find | |
2774 | them all. | |
2775 | @item M-x file-cache-add-directory-list @key{RET} @var{variable} @key{RET} | |
2776 | Add each file name in each directory listed in @var{variable} | |
2777 | to the file name cache. @var{variable} should be a Lisp variable | |
2778 | such as @code{load-path} or @code{exec-path}, whose value is a list | |
2779 | of directory names. | |
2780 | @item M-x file-cache-clear-cache @key{RET} | |
2781 | Clear the cache; that is, remove all file names from it. | |
fa474484 | 2782 | @end table |
9a98ef18 | 2783 | |
eba54dd4 EZ |
2784 | The file name cache is not persistent: it is kept and maintained |
2785 | only for the duration of the Emacs session. You can view the contents | |
2786 | of the cache with the @code{file-cache-display} command. | |
2787 | ||
f02d86a3 RS |
2788 | @node File Conveniences |
2789 | @section Convenience Features for Finding Files | |
fa474484 | 2790 | |
30b1dff1 RS |
2791 | In this section, we introduce some convenient facilities for finding |
2792 | recently-opened files, reading file names from a buffer, and viewing | |
2793 | image files. | |
2794 | ||
fa474484 DL |
2795 | @findex recentf-mode |
2796 | @vindex recentf-mode | |
2797 | @findex recentf-save-list | |
2798 | @findex recentf-edit-list | |
f02d86a3 | 2799 | If you enable Recentf mode, with @kbd{M-x recentf-mode}, the |
d3ff0a57 | 2800 | @samp{File} menu includes a submenu containing a list of recently |
f02d86a3 | 2801 | opened files. @kbd{M-x recentf-save-list} saves the current |
d3ff0a57 RS |
2802 | @code{recent-file-list} to a file, and @kbd{M-x recentf-edit-list} |
2803 | edits it. | |
0d7a07f3 | 2804 | |
f02d86a3 RS |
2805 | The @kbd{M-x ffap} command generalizes @code{find-file} with more |
2806 | powerful heuristic defaults (@pxref{FFAP}), often based on the text at | |
2807 | point. Partial Completion mode offers other features extending | |
2808 | @code{find-file}, which can be used with @code{ffap}. | |
2809 | @xref{Completion Options}. | |
ab5796a9 | 2810 | |
9bc727cd RS |
2811 | @findex image-mode |
2812 | @findex image-toggle-display | |
2813 | @cindex images, viewing | |
2814 | Visiting image files automatically selects Image mode. This major | |
2815 | mode allows you to toggle between displaying the file as an image in | |
2816 | the Emacs buffer, and displaying its underlying text representation, | |
2817 | using the command @kbd{C-c C-c} (@code{image-toggle-display}). This | |
2438b9e4 CY |
2818 | works only when Emacs can display the specific image type. If the |
2819 | displayed image is wider or taller than the frame, the usual point | |
2820 | motion keys (@kbd{C-f}, @kbd{C-p}, and so forth) cause different parts | |
2821 | of the image to be displayed. | |
9bc727cd | 2822 | |
30b1dff1 RS |
2823 | @findex thumbs-mode |
2824 | @findex mode, thumbs | |
53b61ff1 | 2825 | See also the Image-Dired package (@pxref{Image-Dired}) for viewing |
3691dab4 | 2826 | images as thumbnails. |
30b1dff1 | 2827 | |
9bc727cd RS |
2828 | @node Filesets |
2829 | @section Filesets | |
2830 | @cindex filesets | |
2831 | ||
2832 | @findex filesets-init | |
2833 | If you regularly edit a certain group of files, you can define them | |
2834 | as a @dfn{fileset}. This lets you perform certain operations, such as | |
2835 | visiting, @code{query-replace}, and shell commands on all the files | |
2836 | at once. To make use of filesets, you must first add the expression | |
2837 | @code{(filesets-init)} to your @file{.emacs} file (@pxref{Init File}). | |
2838 | This adds a @samp{Filesets} menu to the menu bar. | |
2839 | ||
2840 | @findex filesets-add-buffer | |
2841 | @findex filesets-remove-buffer | |
50a1bd4f | 2842 | The simplest way to define a fileset is by adding files to it one |
9bc727cd RS |
2843 | at a time. To add a file to fileset @var{name}, visit the file and |
2844 | type @kbd{M-x filesets-add-buffer @kbd{RET} @var{name} @kbd{RET}}. If | |
2845 | there is no fileset @var{name}, this creates a new one, which | |
2846 | initially creates only the current file. The command @kbd{M-x | |
2847 | filesets-remove-buffer} removes the current file from a fileset. | |
2848 | ||
2849 | You can also edit the list of filesets directly, with @kbd{M-x | |
2850 | filesets-edit} (or by choosing @samp{Edit Filesets} from the | |
2851 | @samp{Filesets} menu). The editing is performed in a Customize buffer | |
2852 | (@pxref{Easy Customization}). Filesets need not be a simple list of | |
2853 | files---you can also define filesets using regular expression matching | |
2854 | file names. Some examples of these more complicated filesets are | |
2855 | shown in the Customize buffer. Remember to select @samp{Save for | |
2856 | future sessions} if you want to use the same filesets in future Emacs | |
2857 | sessions. | |
2858 | ||
2859 | You can use the command @kbd{M-x filesets-open} to visit all the | |
2860 | files in a fileset, and @kbd{M-x filesets-close} to close them. Use | |
2861 | @kbd{M-x filesets-run-cmd} to run a shell command on all the files in | |
2862 | a fileset. These commands are also available from the @samp{Filesets} | |
2863 | menu, where each existing fileset is represented by a submenu. | |
2864 | ||
ab5796a9 MB |
2865 | @ignore |
2866 | arch-tag: 768d32cb-e15a-4cc1-b7bf-62c00ee12250 | |
2867 | @end ignore |