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