annotate man/files.texi @ 29172:46ad5a027334

(run_pre_post_conversion_on_str): Set point to the beginning of buffer before calling coding->post_read_conversion. (decode_coding_string): Give correct args to run_pre_post_conversion_on_str. (encode_coding_string): Likewise.
author Kenichi Handa <handa@m17n.org>
date Thu, 25 May 2000 04:44:33 +0000
parents 203ba1f77b7b
children f973bf66d321
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1 @c This is part of the Emacs manual.
28123
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2 @c Copyright (C) 1985,86,87,93,94,95,97,99, 2000 Free Software Foundation, Inc.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
3 @c See file emacs.texi for copying conditions.
Dave Love <fx@gnu.org>
parents:
diff changeset
4 @node Files, Buffers, Fixit, Top
Dave Love <fx@gnu.org>
parents:
diff changeset
5 @chapter File Handling
Dave Love <fx@gnu.org>
parents:
diff changeset
6 @cindex files
Dave Love <fx@gnu.org>
parents:
diff changeset
7
Dave Love <fx@gnu.org>
parents:
diff changeset
8 The operating system stores data permanently in named @dfn{files}. So
Dave Love <fx@gnu.org>
parents:
diff changeset
9 most of the text you edit with Emacs comes from a file and is ultimately
Dave Love <fx@gnu.org>
parents:
diff changeset
10 stored in a file.
Dave Love <fx@gnu.org>
parents:
diff changeset
11
Dave Love <fx@gnu.org>
parents:
diff changeset
12 To edit a file, you must tell Emacs to read the file and prepare a
Dave Love <fx@gnu.org>
parents:
diff changeset
13 buffer containing a copy of the file's text. This is called
Dave Love <fx@gnu.org>
parents:
diff changeset
14 @dfn{visiting} the file. Editing commands apply directly to text in the
Dave Love <fx@gnu.org>
parents:
diff changeset
15 buffer; that is, to the copy inside Emacs. Your changes appear in the
Dave Love <fx@gnu.org>
parents:
diff changeset
16 file itself only when you @dfn{save} the buffer back into the file.
Dave Love <fx@gnu.org>
parents:
diff changeset
17
Dave Love <fx@gnu.org>
parents:
diff changeset
18 In addition to visiting and saving files, Emacs can delete, copy,
Dave Love <fx@gnu.org>
parents:
diff changeset
19 rename, and append to files, keep multiple versions of them, and operate
Dave Love <fx@gnu.org>
parents:
diff changeset
20 on file directories.
Dave Love <fx@gnu.org>
parents:
diff changeset
21
Dave Love <fx@gnu.org>
parents:
diff changeset
22 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
23 * File Names:: How to type and edit file-name arguments.
Dave Love <fx@gnu.org>
parents:
diff changeset
24 * Visiting:: Visiting a file prepares Emacs to edit the file.
Dave Love <fx@gnu.org>
parents:
diff changeset
25 * Saving:: Saving makes your changes permanent.
Dave Love <fx@gnu.org>
parents:
diff changeset
26 * Reverting:: Reverting cancels all the changes not saved.
Dave Love <fx@gnu.org>
parents:
diff changeset
27 * Auto Save:: Auto Save periodically protects against loss of data.
Dave Love <fx@gnu.org>
parents:
diff changeset
28 * File Aliases:: Handling multiple names for one file.
Dave Love <fx@gnu.org>
parents:
diff changeset
29 * Version Control:: Version control systems (RCS, CVS and SCCS).
Dave Love <fx@gnu.org>
parents:
diff changeset
30 * Directories:: Creating, deleting, and listing file directories.
Dave Love <fx@gnu.org>
parents:
diff changeset
31 * Comparing Files:: Finding where two files differ.
Dave Love <fx@gnu.org>
parents:
diff changeset
32 * Misc File Ops:: Other things you can do on files.
Dave Love <fx@gnu.org>
parents:
diff changeset
33 * Compressed Files:: Accessing compressed files.
28123
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
34 * File Archives:: Operating on tar, zip, jar etc. archive files.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
35 * Remote Files:: Accessing files on other sites.
Dave Love <fx@gnu.org>
parents:
diff changeset
36 * Quoted File Names:: Quoting special characters in file names.
28526
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
37 * File Conveniences:: Convenience Features for Finding Files.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
38 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
39
Dave Love <fx@gnu.org>
parents:
diff changeset
40 @node File Names
Dave Love <fx@gnu.org>
parents:
diff changeset
41 @section File Names
Dave Love <fx@gnu.org>
parents:
diff changeset
42 @cindex file names
Dave Love <fx@gnu.org>
parents:
diff changeset
43
Dave Love <fx@gnu.org>
parents:
diff changeset
44 Most Emacs commands that operate on a file require you to specify the
Dave Love <fx@gnu.org>
parents:
diff changeset
45 file name. (Saving and reverting are exceptions; the buffer knows which
Dave Love <fx@gnu.org>
parents:
diff changeset
46 file name to use for them.) You enter the file name using the
Dave Love <fx@gnu.org>
parents:
diff changeset
47 minibuffer (@pxref{Minibuffer}). @dfn{Completion} is available, to make
Dave Love <fx@gnu.org>
parents:
diff changeset
48 it easier to specify long file names. @xref{Completion}.
Dave Love <fx@gnu.org>
parents:
diff changeset
49
Dave Love <fx@gnu.org>
parents:
diff changeset
50 For most operations, there is a @dfn{default file name} which is used
Dave Love <fx@gnu.org>
parents:
diff changeset
51 if you type just @key{RET} to enter an empty argument. Normally the
Dave Love <fx@gnu.org>
parents:
diff changeset
52 default file name is the name of the file visited in the current buffer;
Dave Love <fx@gnu.org>
parents:
diff changeset
53 this makes it easy to operate on that file with any of the Emacs file
Dave Love <fx@gnu.org>
parents:
diff changeset
54 commands.
Dave Love <fx@gnu.org>
parents:
diff changeset
55
Dave Love <fx@gnu.org>
parents:
diff changeset
56 @vindex default-directory
Dave Love <fx@gnu.org>
parents:
diff changeset
57 Each buffer has a default directory, normally the same as the
Dave Love <fx@gnu.org>
parents:
diff changeset
58 directory of the file visited in that buffer. When you enter a file
Dave Love <fx@gnu.org>
parents:
diff changeset
59 name without a directory, the default directory is used. If you specify
Dave Love <fx@gnu.org>
parents:
diff changeset
60 a directory in a relative fashion, with a name that does not start with
Dave Love <fx@gnu.org>
parents:
diff changeset
61 a slash, it is interpreted with respect to the default directory. The
Dave Love <fx@gnu.org>
parents:
diff changeset
62 default directory is kept in the variable @code{default-directory},
Dave Love <fx@gnu.org>
parents:
diff changeset
63 which has a separate value in every buffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
64
Dave Love <fx@gnu.org>
parents:
diff changeset
65 For example, if the default file name is @file{/u/rms/gnu/gnu.tasks} then
Dave Love <fx@gnu.org>
parents:
diff changeset
66 the default directory is @file{/u/rms/gnu/}. If you type just @samp{foo},
Dave Love <fx@gnu.org>
parents:
diff changeset
67 which does not specify a directory, it is short for @file{/u/rms/gnu/foo}.
Dave Love <fx@gnu.org>
parents:
diff changeset
68 @samp{../.login} would stand for @file{/u/rms/.login}. @samp{new/foo}
Dave Love <fx@gnu.org>
parents:
diff changeset
69 would stand for the file name @file{/u/rms/gnu/new/foo}.
Dave Love <fx@gnu.org>
parents:
diff changeset
70
Dave Love <fx@gnu.org>
parents:
diff changeset
71 @findex cd
Dave Love <fx@gnu.org>
parents:
diff changeset
72 @findex pwd
Dave Love <fx@gnu.org>
parents:
diff changeset
73 The command @kbd{M-x pwd} prints the current buffer's default
Dave Love <fx@gnu.org>
parents:
diff changeset
74 directory, and the command @kbd{M-x cd} sets it (to a value read using
Dave Love <fx@gnu.org>
parents:
diff changeset
75 the minibuffer). A buffer's default directory changes only when the
Dave Love <fx@gnu.org>
parents:
diff changeset
76 @code{cd} command is used. A file-visiting buffer's default directory
Dave Love <fx@gnu.org>
parents:
diff changeset
77 is initialized to the directory of the file that is visited there. If
Dave Love <fx@gnu.org>
parents:
diff changeset
78 you create a buffer with @kbd{C-x b}, its default directory is copied
Dave Love <fx@gnu.org>
parents:
diff changeset
79 from that of the buffer that was current at the time.
Dave Love <fx@gnu.org>
parents:
diff changeset
80
Dave Love <fx@gnu.org>
parents:
diff changeset
81 @vindex insert-default-directory
Dave Love <fx@gnu.org>
parents:
diff changeset
82 The default directory actually appears in the minibuffer when the
Dave Love <fx@gnu.org>
parents:
diff changeset
83 minibuffer becomes active to read a file name. This serves two
Dave Love <fx@gnu.org>
parents:
diff changeset
84 purposes: it @emph{shows} you what the default is, so that you can type
Dave Love <fx@gnu.org>
parents:
diff changeset
85 a relative file name and know with certainty what it will mean, and it
Dave Love <fx@gnu.org>
parents:
diff changeset
86 allows you to @emph{edit} the default to specify a different directory.
Dave Love <fx@gnu.org>
parents:
diff changeset
87 This insertion of the default directory is inhibited if the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
88 @code{insert-default-directory} is set to @code{nil}.
Dave Love <fx@gnu.org>
parents:
diff changeset
89
Dave Love <fx@gnu.org>
parents:
diff changeset
90 Note that it is legitimate to type an absolute file name after you
Dave Love <fx@gnu.org>
parents:
diff changeset
91 enter the minibuffer, ignoring the presence of the default directory
Dave Love <fx@gnu.org>
parents:
diff changeset
92 name as part of the text. The final minibuffer contents may look
Dave Love <fx@gnu.org>
parents:
diff changeset
93 invalid, but that is not so. For example, if the minibuffer starts out
Dave Love <fx@gnu.org>
parents:
diff changeset
94 with @samp{/usr/tmp/} and you add @samp{/x1/rms/foo}, you get
Dave Love <fx@gnu.org>
parents:
diff changeset
95 @samp{/usr/tmp//x1/rms/foo}; but Emacs ignores everything through the
Dave Love <fx@gnu.org>
parents:
diff changeset
96 first slash in the double slash; the result is @samp{/x1/rms/foo}.
Dave Love <fx@gnu.org>
parents:
diff changeset
97 @xref{Minibuffer File}.
Dave Love <fx@gnu.org>
parents:
diff changeset
98
Dave Love <fx@gnu.org>
parents:
diff changeset
99 @samp{$} in a file name is used to substitute environment variables.
Dave Love <fx@gnu.org>
parents:
diff changeset
100 For example, if you have used the shell command @samp{export
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 28671
diff changeset
101 FOO=rms/hacks} to set up an environment variable named @env{FOO}, then
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
102 you can use @file{/u/$FOO/test.c} or @file{/u/$@{FOO@}/test.c} as an
Dave Love <fx@gnu.org>
parents:
diff changeset
103 abbreviation for @file{/u/rms/hacks/test.c}. The environment variable
Dave Love <fx@gnu.org>
parents:
diff changeset
104 name consists of all the alphanumeric characters after the @samp{$};
Dave Love <fx@gnu.org>
parents:
diff changeset
105 alternatively, it may be enclosed in braces after the @samp{$}. Note
Dave Love <fx@gnu.org>
parents:
diff changeset
106 that shell commands to set environment variables affect Emacs only if
Dave Love <fx@gnu.org>
parents:
diff changeset
107 done before Emacs is started.
Dave Love <fx@gnu.org>
parents:
diff changeset
108
Dave Love <fx@gnu.org>
parents:
diff changeset
109 To access a file with @samp{$} in its name, type @samp{$$}. This pair
Dave Love <fx@gnu.org>
parents:
diff changeset
110 is converted to a single @samp{$} at the same time as variable
Dave Love <fx@gnu.org>
parents:
diff changeset
111 substitution is performed for single @samp{$}. Alternatively, quote the
Dave Love <fx@gnu.org>
parents:
diff changeset
112 whole file name with @samp{/:} (@pxref{Quoted File Names}).
Dave Love <fx@gnu.org>
parents:
diff changeset
113
Dave Love <fx@gnu.org>
parents:
diff changeset
114 @findex substitute-in-file-name
Dave Love <fx@gnu.org>
parents:
diff changeset
115 The Lisp function that performs the substitution is called
Dave Love <fx@gnu.org>
parents:
diff changeset
116 @code{substitute-in-file-name}. The substitution is performed only on
Dave Love <fx@gnu.org>
parents:
diff changeset
117 file names read as such using the minibuffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
118
Dave Love <fx@gnu.org>
parents:
diff changeset
119 You can include non-ASCII characters in file names if you set the
Dave Love <fx@gnu.org>
parents:
diff changeset
120 variable @code{file-name-coding-system} to a non-@code{nil} value.
Dave Love <fx@gnu.org>
parents:
diff changeset
121 @xref{Specify Coding}.
Dave Love <fx@gnu.org>
parents:
diff changeset
122
Dave Love <fx@gnu.org>
parents:
diff changeset
123 @node Visiting
Dave Love <fx@gnu.org>
parents:
diff changeset
124 @section Visiting Files
Dave Love <fx@gnu.org>
parents:
diff changeset
125 @cindex visiting files
Dave Love <fx@gnu.org>
parents:
diff changeset
126
Dave Love <fx@gnu.org>
parents:
diff changeset
127 @c WideCommands
Dave Love <fx@gnu.org>
parents:
diff changeset
128 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
129 @item C-x C-f
Dave Love <fx@gnu.org>
parents:
diff changeset
130 Visit a file (@code{find-file}).
Dave Love <fx@gnu.org>
parents:
diff changeset
131 @item C-x C-r
Dave Love <fx@gnu.org>
parents:
diff changeset
132 Visit a file for viewing, without allowing changes to it
Dave Love <fx@gnu.org>
parents:
diff changeset
133 (@code{find-file-read-only}).
Dave Love <fx@gnu.org>
parents:
diff changeset
134 @item C-x C-v
Dave Love <fx@gnu.org>
parents:
diff changeset
135 Visit a different file instead of the one visited last
Dave Love <fx@gnu.org>
parents:
diff changeset
136 (@code{find-alternate-file}).
Dave Love <fx@gnu.org>
parents:
diff changeset
137 @item C-x 4 f
Dave Love <fx@gnu.org>
parents:
diff changeset
138 Visit a file, in another window (@code{find-file-other-window}). Don't
Dave Love <fx@gnu.org>
parents:
diff changeset
139 alter what is displayed in the selected window.
Dave Love <fx@gnu.org>
parents:
diff changeset
140 @item C-x 5 f
Dave Love <fx@gnu.org>
parents:
diff changeset
141 Visit a file, in a new frame (@code{find-file-other-frame}). Don't
Dave Love <fx@gnu.org>
parents:
diff changeset
142 alter what is displayed in the selected frame.
Dave Love <fx@gnu.org>
parents:
diff changeset
143 @item M-x find-file-literally
Dave Love <fx@gnu.org>
parents:
diff changeset
144 Visit a file with no conversion of the contents.
Dave Love <fx@gnu.org>
parents:
diff changeset
145 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
146
Dave Love <fx@gnu.org>
parents:
diff changeset
147 @cindex files, visiting and saving
Dave Love <fx@gnu.org>
parents:
diff changeset
148 @cindex visiting files
Dave Love <fx@gnu.org>
parents:
diff changeset
149 @cindex saving files
Dave Love <fx@gnu.org>
parents:
diff changeset
150 @dfn{Visiting} a file means copying its contents into an Emacs buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
151 so you can edit them. Emacs makes a new buffer for each file that you
Dave Love <fx@gnu.org>
parents:
diff changeset
152 visit. We say that this buffer is visiting the file that it was created
Dave Love <fx@gnu.org>
parents:
diff changeset
153 to hold. Emacs constructs the buffer name from the file name by
Dave Love <fx@gnu.org>
parents:
diff changeset
154 throwing away the directory, keeping just the name proper. For example,
Dave Love <fx@gnu.org>
parents:
diff changeset
155 a file named @file{/usr/rms/emacs.tex} would get a buffer named
Dave Love <fx@gnu.org>
parents:
diff changeset
156 @samp{emacs.tex}. If there is already a buffer with that name, a unique
Dave Love <fx@gnu.org>
parents:
diff changeset
157 name is constructed by appending @samp{<2>}, @samp{<3>}, or so on, using
Dave Love <fx@gnu.org>
parents:
diff changeset
158 the lowest number that makes a name that is not already in use.
Dave Love <fx@gnu.org>
parents:
diff changeset
159
Dave Love <fx@gnu.org>
parents:
diff changeset
160 Each window's mode line shows the name of the buffer that is being displayed
Dave Love <fx@gnu.org>
parents:
diff changeset
161 in that window, so you can always tell what buffer you are editing.
Dave Love <fx@gnu.org>
parents:
diff changeset
162
Dave Love <fx@gnu.org>
parents:
diff changeset
163 The changes you make with editing commands are made in the Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
164 buffer. They do not take effect in the file that you visited, or any
Dave Love <fx@gnu.org>
parents:
diff changeset
165 place permanent, until you @dfn{save} the buffer. Saving the buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
166 means that Emacs writes the current contents of the buffer into its
Dave Love <fx@gnu.org>
parents:
diff changeset
167 visited file. @xref{Saving}.
Dave Love <fx@gnu.org>
parents:
diff changeset
168
Dave Love <fx@gnu.org>
parents:
diff changeset
169 @cindex modified (buffer)
Dave Love <fx@gnu.org>
parents:
diff changeset
170 If a buffer contains changes that have not been saved, we say the
Dave Love <fx@gnu.org>
parents:
diff changeset
171 buffer is @dfn{modified}. This is important because it implies that
Dave Love <fx@gnu.org>
parents:
diff changeset
172 some changes will be lost if the buffer is not saved. The mode line
Dave Love <fx@gnu.org>
parents:
diff changeset
173 displays two stars near the left margin to indicate that the buffer is
Dave Love <fx@gnu.org>
parents:
diff changeset
174 modified.
Dave Love <fx@gnu.org>
parents:
diff changeset
175
Dave Love <fx@gnu.org>
parents:
diff changeset
176 @kindex C-x C-f
Dave Love <fx@gnu.org>
parents:
diff changeset
177 @findex find-file
Dave Love <fx@gnu.org>
parents:
diff changeset
178 To visit a file, use the command @kbd{C-x C-f} (@code{find-file}). Follow
Dave Love <fx@gnu.org>
parents:
diff changeset
179 the command with the name of the file you wish to visit, terminated by a
Dave Love <fx@gnu.org>
parents:
diff changeset
180 @key{RET}.
Dave Love <fx@gnu.org>
parents:
diff changeset
181
Dave Love <fx@gnu.org>
parents:
diff changeset
182 The file name is read using the minibuffer (@pxref{Minibuffer}), with
Dave Love <fx@gnu.org>
parents:
diff changeset
183 defaulting and completion in the standard manner (@pxref{File Names}).
Dave Love <fx@gnu.org>
parents:
diff changeset
184 While in the minibuffer, you can abort @kbd{C-x C-f} by typing @kbd{C-g}.
Dave Love <fx@gnu.org>
parents:
diff changeset
185
Dave Love <fx@gnu.org>
parents:
diff changeset
186 Your confirmation that @kbd{C-x C-f} has completed successfully is the
Dave Love <fx@gnu.org>
parents:
diff changeset
187 appearance of new text on the screen and a new buffer name in the mode
Dave Love <fx@gnu.org>
parents:
diff changeset
188 line. If the specified file does not exist and could not be created, or
Dave Love <fx@gnu.org>
parents:
diff changeset
189 cannot be read, then you get an error, with an error message displayed
Dave Love <fx@gnu.org>
parents:
diff changeset
190 in the echo area.
Dave Love <fx@gnu.org>
parents:
diff changeset
191
Dave Love <fx@gnu.org>
parents:
diff changeset
192 If you visit a file that is already in Emacs, @kbd{C-x C-f} does not make
Dave Love <fx@gnu.org>
parents:
diff changeset
193 another copy. It selects the existing buffer containing that file.
Dave Love <fx@gnu.org>
parents:
diff changeset
194 However, before doing so, it checks that the file itself has not changed
Dave Love <fx@gnu.org>
parents:
diff changeset
195 since you visited or saved it last. If the file has changed, a warning
Dave Love <fx@gnu.org>
parents:
diff changeset
196 message is printed. @xref{Interlocking,,Simultaneous Editing}.
Dave Love <fx@gnu.org>
parents:
diff changeset
197
Dave Love <fx@gnu.org>
parents:
diff changeset
198 @cindex creating files
Dave Love <fx@gnu.org>
parents:
diff changeset
199 What if you want to create a new file? Just visit it. Emacs prints
Dave Love <fx@gnu.org>
parents:
diff changeset
200 @samp{(New File)} in the echo area, but in other respects behaves as if
Dave Love <fx@gnu.org>
parents:
diff changeset
201 you had visited an existing empty file. If you make any changes and
Dave Love <fx@gnu.org>
parents:
diff changeset
202 save them, the file is created.
Dave Love <fx@gnu.org>
parents:
diff changeset
203
Dave Love <fx@gnu.org>
parents:
diff changeset
204 Emacs recognizes from the contents of a file which convention it uses
Dave Love <fx@gnu.org>
parents:
diff changeset
205 to separate lines---newline (used on GNU/Linux and on Unix),
Dave Love <fx@gnu.org>
parents:
diff changeset
206 carriage-return linefeed (used on Microsoft systems), or just
Dave Love <fx@gnu.org>
parents:
diff changeset
207 carriage-return (used on the Macintosh)---and automatically converts the
Dave Love <fx@gnu.org>
parents:
diff changeset
208 contents to the normal Emacs convention, which is that the newline
Dave Love <fx@gnu.org>
parents:
diff changeset
209 character separates lines. This is a part of the general feature of
Dave Love <fx@gnu.org>
parents:
diff changeset
210 coding system conversion (@pxref{Coding Systems}), and makes it possible
Dave Love <fx@gnu.org>
parents:
diff changeset
211 to edit files imported from various different operating systems with
Dave Love <fx@gnu.org>
parents:
diff changeset
212 equal convenience. If you change the text and save the file, Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
213 performs the inverse conversion, changing newlines back into
Dave Love <fx@gnu.org>
parents:
diff changeset
214 carriage-return linefeed or just carriage-return if appropriate.
Dave Love <fx@gnu.org>
parents:
diff changeset
215
Dave Love <fx@gnu.org>
parents:
diff changeset
216 @vindex find-file-run-dired
Dave Love <fx@gnu.org>
parents:
diff changeset
217 If the file you specify is actually a directory, @kbd{C-x C-f} invokes
Dave Love <fx@gnu.org>
parents:
diff changeset
218 Dired, the Emacs directory browser, so that you can ``edit'' the contents
Dave Love <fx@gnu.org>
parents:
diff changeset
219 of the directory (@pxref{Dired}). Dired is a convenient way to delete,
Dave Love <fx@gnu.org>
parents:
diff changeset
220 look at, or operate on the files in the directory. However, if the
Dave Love <fx@gnu.org>
parents:
diff changeset
221 variable @code{find-file-run-dired} is @code{nil}, then it is an error
Dave Love <fx@gnu.org>
parents:
diff changeset
222 to try to visit a directory.
Dave Love <fx@gnu.org>
parents:
diff changeset
223
28327
f7b17a6af3db (Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents: 28123
diff changeset
224 @cindex wildcard characters in file names
f7b17a6af3db (Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents: 28123
diff changeset
225 @vindex find-file-wildcards
f7b17a6af3db (Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents: 28123
diff changeset
226 If the file name you specify contains @code{sh}-style wildcard
f7b17a6af3db (Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents: 28123
diff changeset
227 characters, Emacs visits all the files that match it. @xref{Quoted File
f7b17a6af3db (Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents: 28123
diff changeset
228 Names}, if you want to visit a file whose name actually contains
f7b17a6af3db (Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents: 28123
diff changeset
229 wildcard characters. Wildcards comprise @samp{?}, @samp{*} and
f7b17a6af3db (Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents: 28123
diff changeset
230 @samp{[@dots{}]} sequences. The wildcard feature can be disabled by
f7b17a6af3db (Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents: 28123
diff changeset
231 customizing @code{find-file-wildcards}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
232
Dave Love <fx@gnu.org>
parents:
diff changeset
233 If you visit a file that the operating system won't let you modify,
Dave Love <fx@gnu.org>
parents:
diff changeset
234 Emacs makes the buffer read-only, so that you won't go ahead and make
Dave Love <fx@gnu.org>
parents:
diff changeset
235 changes that you'll have trouble saving afterward. You can make the
Dave Love <fx@gnu.org>
parents:
diff changeset
236 buffer writable with @kbd{C-x C-q} (@code{vc-toggle-read-only}).
Dave Love <fx@gnu.org>
parents:
diff changeset
237 @xref{Misc Buffer}.
Dave Love <fx@gnu.org>
parents:
diff changeset
238
Dave Love <fx@gnu.org>
parents:
diff changeset
239 @kindex C-x C-r
Dave Love <fx@gnu.org>
parents:
diff changeset
240 @findex find-file-read-only
Dave Love <fx@gnu.org>
parents:
diff changeset
241 Occasionally you might want to visit a file as read-only in order to
Dave Love <fx@gnu.org>
parents:
diff changeset
242 protect yourself from entering changes accidentally; do so by visiting
Dave Love <fx@gnu.org>
parents:
diff changeset
243 the file with the command @kbd{C-x C-r} (@code{find-file-read-only}).
Dave Love <fx@gnu.org>
parents:
diff changeset
244
Dave Love <fx@gnu.org>
parents:
diff changeset
245 @kindex C-x C-v
Dave Love <fx@gnu.org>
parents:
diff changeset
246 @findex find-alternate-file
Dave Love <fx@gnu.org>
parents:
diff changeset
247 If you visit a nonexistent file unintentionally (because you typed the
Dave Love <fx@gnu.org>
parents:
diff changeset
248 wrong file name), use the @kbd{C-x C-v} command
Dave Love <fx@gnu.org>
parents:
diff changeset
249 (@code{find-alternate-file}) to visit the file you really wanted.
Dave Love <fx@gnu.org>
parents:
diff changeset
250 @kbd{C-x C-v} is similar to @kbd{C-x C-f}, but it kills the current
Dave Love <fx@gnu.org>
parents:
diff changeset
251 buffer (after first offering to save it if it is modified). When it
Dave Love <fx@gnu.org>
parents:
diff changeset
252 reads the file name to visit, it inserts the entire default file name in
Dave Love <fx@gnu.org>
parents:
diff changeset
253 the buffer, with point just after the directory part; this is convenient
Dave Love <fx@gnu.org>
parents:
diff changeset
254 if you made a slight error in typing the name.
Dave Love <fx@gnu.org>
parents:
diff changeset
255
Dave Love <fx@gnu.org>
parents:
diff changeset
256 If you find a file which exists but cannot be read, @kbd{C-x C-f}
Dave Love <fx@gnu.org>
parents:
diff changeset
257 signals an error.
Dave Love <fx@gnu.org>
parents:
diff changeset
258
Dave Love <fx@gnu.org>
parents:
diff changeset
259 @kindex C-x 4 f
Dave Love <fx@gnu.org>
parents:
diff changeset
260 @findex find-file-other-window
Dave Love <fx@gnu.org>
parents:
diff changeset
261 @kbd{C-x 4 f} (@code{find-file-other-window}) is like @kbd{C-x C-f}
Dave Love <fx@gnu.org>
parents:
diff changeset
262 except that the buffer containing the specified file is selected in another
Dave Love <fx@gnu.org>
parents:
diff changeset
263 window. The window that was selected before @kbd{C-x 4 f} continues to
Dave Love <fx@gnu.org>
parents:
diff changeset
264 show the same buffer it was already showing. If this command is used when
Dave Love <fx@gnu.org>
parents:
diff changeset
265 only one window is being displayed, that window is split in two, with one
Dave Love <fx@gnu.org>
parents:
diff changeset
266 window showing the same buffer as before, and the other one showing the
Dave Love <fx@gnu.org>
parents:
diff changeset
267 newly requested file. @xref{Windows}.
Dave Love <fx@gnu.org>
parents:
diff changeset
268
Dave Love <fx@gnu.org>
parents:
diff changeset
269 @kindex C-x 5 f
Dave Love <fx@gnu.org>
parents:
diff changeset
270 @findex find-file-other-frame
Dave Love <fx@gnu.org>
parents:
diff changeset
271 @kbd{C-x 5 f} (@code{find-file-other-frame}) is similar, but opens a
Dave Love <fx@gnu.org>
parents:
diff changeset
272 new frame, or makes visible any existing frame showing the file you
Dave Love <fx@gnu.org>
parents:
diff changeset
273 seek. This feature is available only when you are using a window
Dave Love <fx@gnu.org>
parents:
diff changeset
274 system. @xref{Frames}.
Dave Love <fx@gnu.org>
parents:
diff changeset
275
Dave Love <fx@gnu.org>
parents:
diff changeset
276 @findex find-file-literally
Dave Love <fx@gnu.org>
parents:
diff changeset
277 If you wish to edit a file as a sequence of characters with no special
Dave Love <fx@gnu.org>
parents:
diff changeset
278 encoding or conversion, use the @kbd{M-x find-file-literally} command.
Dave Love <fx@gnu.org>
parents:
diff changeset
279 It visits a file, like @kbd{C-x C-f}, but does not do format conversion
Dave Love <fx@gnu.org>
parents:
diff changeset
280 (@pxref{Formatted Text}), character code conversion (@pxref{Coding
Dave Love <fx@gnu.org>
parents:
diff changeset
281 Systems}), or automatic uncompression (@pxref{Compressed Files}).
Dave Love <fx@gnu.org>
parents:
diff changeset
282 If you already have visited the same file in the usual (non-literal)
Dave Love <fx@gnu.org>
parents:
diff changeset
283 manner, this command asks you whether to visit it literally instead.
Dave Love <fx@gnu.org>
parents:
diff changeset
284
Dave Love <fx@gnu.org>
parents:
diff changeset
285 @vindex find-file-hooks
Dave Love <fx@gnu.org>
parents:
diff changeset
286 @vindex find-file-not-found-hooks
Dave Love <fx@gnu.org>
parents:
diff changeset
287 Two special hook variables allow extensions to modify the operation of
Dave Love <fx@gnu.org>
parents:
diff changeset
288 visiting files. Visiting a file that does not exist runs the functions
Dave Love <fx@gnu.org>
parents:
diff changeset
289 in the list @code{find-file-not-found-hooks}; this variable holds a list
Dave Love <fx@gnu.org>
parents:
diff changeset
290 of functions, and the functions are called one by one (with no
Dave Love <fx@gnu.org>
parents:
diff changeset
291 arguments) until one of them returns non-@code{nil}. This is not a
Dave Love <fx@gnu.org>
parents:
diff changeset
292 normal hook, and the name ends in @samp{-hooks} rather than @samp{-hook}
Dave Love <fx@gnu.org>
parents:
diff changeset
293 to indicate that fact.
Dave Love <fx@gnu.org>
parents:
diff changeset
294
Dave Love <fx@gnu.org>
parents:
diff changeset
295 Any visiting of a file, whether extant or not, expects
Dave Love <fx@gnu.org>
parents:
diff changeset
296 @code{find-file-hooks} to contain a list of functions, and calls them
Dave Love <fx@gnu.org>
parents:
diff changeset
297 all, one by one, with no arguments. This variable is really a normal
Dave Love <fx@gnu.org>
parents:
diff changeset
298 hook, but it has an abnormal name for historical compatibility. In the
Dave Love <fx@gnu.org>
parents:
diff changeset
299 case of a nonexistent file, the @code{find-file-not-found-hooks} are run
Dave Love <fx@gnu.org>
parents:
diff changeset
300 first. @xref{Hooks}.
Dave Love <fx@gnu.org>
parents:
diff changeset
301
Dave Love <fx@gnu.org>
parents:
diff changeset
302 There are several ways to specify automatically the major mode for
Dave Love <fx@gnu.org>
parents:
diff changeset
303 editing the file (@pxref{Choosing Modes}), and to specify local
Dave Love <fx@gnu.org>
parents:
diff changeset
304 variables defined for that file (@pxref{File Variables}).
Dave Love <fx@gnu.org>
parents:
diff changeset
305
Dave Love <fx@gnu.org>
parents:
diff changeset
306 @node Saving
Dave Love <fx@gnu.org>
parents:
diff changeset
307 @section Saving Files
Dave Love <fx@gnu.org>
parents:
diff changeset
308
Dave Love <fx@gnu.org>
parents:
diff changeset
309 @dfn{Saving} a buffer in Emacs means writing its contents back into the file
Dave Love <fx@gnu.org>
parents:
diff changeset
310 that was visited in the buffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
311
Dave Love <fx@gnu.org>
parents:
diff changeset
312 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
313 @item C-x C-s
Dave Love <fx@gnu.org>
parents:
diff changeset
314 Save the current buffer in its visited file (@code{save-buffer}).
Dave Love <fx@gnu.org>
parents:
diff changeset
315 @item C-x s
Dave Love <fx@gnu.org>
parents:
diff changeset
316 Save any or all buffers in their visited files (@code{save-some-buffers}).
Dave Love <fx@gnu.org>
parents:
diff changeset
317 @item M-~
Dave Love <fx@gnu.org>
parents:
diff changeset
318 Forget that the current buffer has been changed (@code{not-modified}).
Dave Love <fx@gnu.org>
parents:
diff changeset
319 @item C-x C-w
Dave Love <fx@gnu.org>
parents:
diff changeset
320 Save the current buffer in a specified file (@code{write-file}).
Dave Love <fx@gnu.org>
parents:
diff changeset
321 @item M-x set-visited-file-name
Dave Love <fx@gnu.org>
parents:
diff changeset
322 Change file the name under which the current buffer will be saved.
Dave Love <fx@gnu.org>
parents:
diff changeset
323 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
324
Dave Love <fx@gnu.org>
parents:
diff changeset
325 @kindex C-x C-s
Dave Love <fx@gnu.org>
parents:
diff changeset
326 @findex save-buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
327 When you wish to save the file and make your changes permanent, type
Dave Love <fx@gnu.org>
parents:
diff changeset
328 @kbd{C-x C-s} (@code{save-buffer}). After saving is finished, @kbd{C-x C-s}
Dave Love <fx@gnu.org>
parents:
diff changeset
329 displays a message like this:
Dave Love <fx@gnu.org>
parents:
diff changeset
330
Dave Love <fx@gnu.org>
parents:
diff changeset
331 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
332 Wrote /u/rms/gnu/gnu.tasks
Dave Love <fx@gnu.org>
parents:
diff changeset
333 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
334
Dave Love <fx@gnu.org>
parents:
diff changeset
335 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
336 If the selected buffer is not modified (no changes have been made in it
Dave Love <fx@gnu.org>
parents:
diff changeset
337 since the buffer was created or last saved), saving is not really done,
Dave Love <fx@gnu.org>
parents:
diff changeset
338 because it would have no effect. Instead, @kbd{C-x C-s} displays a message
Dave Love <fx@gnu.org>
parents:
diff changeset
339 like this in the echo area:
Dave Love <fx@gnu.org>
parents:
diff changeset
340
Dave Love <fx@gnu.org>
parents:
diff changeset
341 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
342 (No changes need to be saved)
Dave Love <fx@gnu.org>
parents:
diff changeset
343 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
344
Dave Love <fx@gnu.org>
parents:
diff changeset
345 @kindex C-x s
Dave Love <fx@gnu.org>
parents:
diff changeset
346 @findex save-some-buffers
Dave Love <fx@gnu.org>
parents:
diff changeset
347 The command @kbd{C-x s} (@code{save-some-buffers}) offers to save any
Dave Love <fx@gnu.org>
parents:
diff changeset
348 or all modified buffers. It asks you what to do with each buffer. The
Dave Love <fx@gnu.org>
parents:
diff changeset
349 possible responses are analogous to those of @code{query-replace}:
Dave Love <fx@gnu.org>
parents:
diff changeset
350
Dave Love <fx@gnu.org>
parents:
diff changeset
351 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
352 @item y
Dave Love <fx@gnu.org>
parents:
diff changeset
353 Save this buffer and ask about the rest of the buffers.
Dave Love <fx@gnu.org>
parents:
diff changeset
354 @item n
Dave Love <fx@gnu.org>
parents:
diff changeset
355 Don't save this buffer, but ask about the rest of the buffers.
Dave Love <fx@gnu.org>
parents:
diff changeset
356 @item !
Dave Love <fx@gnu.org>
parents:
diff changeset
357 Save this buffer and all the rest with no more questions.
Dave Love <fx@gnu.org>
parents:
diff changeset
358 @c following generates acceptable underfull hbox
Dave Love <fx@gnu.org>
parents:
diff changeset
359 @item @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
360 Terminate @code{save-some-buffers} without any more saving.
Dave Love <fx@gnu.org>
parents:
diff changeset
361 @item .
Dave Love <fx@gnu.org>
parents:
diff changeset
362 Save this buffer, then exit @code{save-some-buffers} without even asking
Dave Love <fx@gnu.org>
parents:
diff changeset
363 about other buffers.
Dave Love <fx@gnu.org>
parents:
diff changeset
364 @item C-r
Dave Love <fx@gnu.org>
parents:
diff changeset
365 View the buffer that you are currently being asked about. When you exit
Dave Love <fx@gnu.org>
parents:
diff changeset
366 View mode, you get back to @code{save-some-buffers}, which asks the
Dave Love <fx@gnu.org>
parents:
diff changeset
367 question again.
Dave Love <fx@gnu.org>
parents:
diff changeset
368 @item C-h
Dave Love <fx@gnu.org>
parents:
diff changeset
369 Display a help message about these options.
Dave Love <fx@gnu.org>
parents:
diff changeset
370 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
371
Dave Love <fx@gnu.org>
parents:
diff changeset
372 @kbd{C-x C-c}, the key sequence to exit Emacs, invokes
Dave Love <fx@gnu.org>
parents:
diff changeset
373 @code{save-some-buffers} and therefore asks the same questions.
Dave Love <fx@gnu.org>
parents:
diff changeset
374
Dave Love <fx@gnu.org>
parents:
diff changeset
375 @kindex M-~
Dave Love <fx@gnu.org>
parents:
diff changeset
376 @findex not-modified
Dave Love <fx@gnu.org>
parents:
diff changeset
377 If you have changed a buffer but you do not want to save the changes,
Dave Love <fx@gnu.org>
parents:
diff changeset
378 you should take some action to prevent it. Otherwise, each time you use
Dave Love <fx@gnu.org>
parents:
diff changeset
379 @kbd{C-x s} or @kbd{C-x C-c}, you are liable to save this buffer by
Dave Love <fx@gnu.org>
parents:
diff changeset
380 mistake. One thing you can do is type @kbd{M-~} (@code{not-modified}),
Dave Love <fx@gnu.org>
parents:
diff changeset
381 which clears out the indication that the buffer is modified. If you do
Dave Love <fx@gnu.org>
parents:
diff changeset
382 this, none of the save commands will believe that the buffer needs to be
Dave Love <fx@gnu.org>
parents:
diff changeset
383 saved. (@samp{~} is often used as a mathematical symbol for `not'; thus
Dave Love <fx@gnu.org>
parents:
diff changeset
384 @kbd{M-~} is `not', metafied.) You could also use
Dave Love <fx@gnu.org>
parents:
diff changeset
385 @code{set-visited-file-name} (see below) to mark the buffer as visiting
Dave Love <fx@gnu.org>
parents:
diff changeset
386 a different file name, one which is not in use for anything important.
Dave Love <fx@gnu.org>
parents:
diff changeset
387 Alternatively, you can cancel all the changes made since the file was
Dave Love <fx@gnu.org>
parents:
diff changeset
388 visited or saved, by reading the text from the file again. This is
Dave Love <fx@gnu.org>
parents:
diff changeset
389 called @dfn{reverting}. @xref{Reverting}. You could also undo all the
Dave Love <fx@gnu.org>
parents:
diff changeset
390 changes by repeating the undo command @kbd{C-x u} until you have undone
Dave Love <fx@gnu.org>
parents:
diff changeset
391 all the changes; but reverting is easier.
Dave Love <fx@gnu.org>
parents:
diff changeset
392
Dave Love <fx@gnu.org>
parents:
diff changeset
393 @findex set-visited-file-name
Dave Love <fx@gnu.org>
parents:
diff changeset
394 @kbd{M-x set-visited-file-name} alters the name of the file that the
Dave Love <fx@gnu.org>
parents:
diff changeset
395 current buffer is visiting. It reads the new file name using the
Dave Love <fx@gnu.org>
parents:
diff changeset
396 minibuffer. Then it specifies the visited file name and changes the
Dave Love <fx@gnu.org>
parents:
diff changeset
397 buffer name correspondingly (as long as the new name is not in use).
Dave Love <fx@gnu.org>
parents:
diff changeset
398 @code{set-visited-file-name} does not save the buffer in the newly
Dave Love <fx@gnu.org>
parents:
diff changeset
399 visited file; it just alters the records inside Emacs in case you do
Dave Love <fx@gnu.org>
parents:
diff changeset
400 save later. It also marks the buffer as ``modified'' so that @kbd{C-x
Dave Love <fx@gnu.org>
parents:
diff changeset
401 C-s} in that buffer @emph{will} save.
Dave Love <fx@gnu.org>
parents:
diff changeset
402
Dave Love <fx@gnu.org>
parents:
diff changeset
403 @kindex C-x C-w
Dave Love <fx@gnu.org>
parents:
diff changeset
404 @findex write-file
Dave Love <fx@gnu.org>
parents:
diff changeset
405 If you wish to mark the buffer as visiting a different file and save it
Dave Love <fx@gnu.org>
parents:
diff changeset
406 right away, use @kbd{C-x C-w} (@code{write-file}). It is precisely
Dave Love <fx@gnu.org>
parents:
diff changeset
407 equivalent to @code{set-visited-file-name} followed by @kbd{C-x C-s}.
Dave Love <fx@gnu.org>
parents:
diff changeset
408 @kbd{C-x C-s} used on a buffer that is not visiting a file has the
Dave Love <fx@gnu.org>
parents:
diff changeset
409 same effect as @kbd{C-x C-w}; that is, it reads a file name, marks the
Dave Love <fx@gnu.org>
parents:
diff changeset
410 buffer as visiting that file, and saves it there. The default file name in
Dave Love <fx@gnu.org>
parents:
diff changeset
411 a buffer that is not visiting a file is made by combining the buffer name
Dave Love <fx@gnu.org>
parents:
diff changeset
412 with the buffer's default directory.
Dave Love <fx@gnu.org>
parents:
diff changeset
413
Dave Love <fx@gnu.org>
parents:
diff changeset
414 If the new file name implies a major mode, then @kbd{C-x C-w} switches
Dave Love <fx@gnu.org>
parents:
diff changeset
415 to that major mode, in most cases. The command
Dave Love <fx@gnu.org>
parents:
diff changeset
416 @code{set-visited-file-name} also does this. @xref{Choosing Modes}.
Dave Love <fx@gnu.org>
parents:
diff changeset
417
Dave Love <fx@gnu.org>
parents:
diff changeset
418 If Emacs is about to save a file and sees that the date of the latest
Dave Love <fx@gnu.org>
parents:
diff changeset
419 version on disk does not match what Emacs last read or wrote, Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
420 notifies you of this fact, because it probably indicates a problem caused
Dave Love <fx@gnu.org>
parents:
diff changeset
421 by simultaneous editing and requires your immediate attention.
Dave Love <fx@gnu.org>
parents:
diff changeset
422 @xref{Interlocking,, Simultaneous Editing}.
Dave Love <fx@gnu.org>
parents:
diff changeset
423
Dave Love <fx@gnu.org>
parents:
diff changeset
424 @vindex require-final-newline
Dave Love <fx@gnu.org>
parents:
diff changeset
425 If the variable @code{require-final-newline} is non-@code{nil}, Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
426 puts a newline at the end of any file that doesn't already end in one,
Dave Love <fx@gnu.org>
parents:
diff changeset
427 every time a file is saved or written. The default is @code{nil}.
Dave Love <fx@gnu.org>
parents:
diff changeset
428
Dave Love <fx@gnu.org>
parents:
diff changeset
429 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
430 * Backup:: How Emacs saves the old version of your file.
Dave Love <fx@gnu.org>
parents:
diff changeset
431 * Interlocking:: How Emacs protects against simultaneous editing
Dave Love <fx@gnu.org>
parents:
diff changeset
432 of one file by two users.
Dave Love <fx@gnu.org>
parents:
diff changeset
433 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
434
Dave Love <fx@gnu.org>
parents:
diff changeset
435 @node Backup
Dave Love <fx@gnu.org>
parents:
diff changeset
436 @subsection Backup Files
Dave Love <fx@gnu.org>
parents:
diff changeset
437 @cindex backup file
Dave Love <fx@gnu.org>
parents:
diff changeset
438 @vindex make-backup-files
Dave Love <fx@gnu.org>
parents:
diff changeset
439 @vindex vc-make-backup-files
Dave Love <fx@gnu.org>
parents:
diff changeset
440 @vindex backup-enable-predicate
Dave Love <fx@gnu.org>
parents:
diff changeset
441
Dave Love <fx@gnu.org>
parents:
diff changeset
442 On most operating systems, rewriting a file automatically destroys all
Dave Love <fx@gnu.org>
parents:
diff changeset
443 record of what the file used to contain. Thus, saving a file from Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
444 throws away the old contents of the file---or it would, except that
Dave Love <fx@gnu.org>
parents:
diff changeset
445 Emacs carefully copies the old contents to another file, called the
Dave Love <fx@gnu.org>
parents:
diff changeset
446 @dfn{backup} file, before actually saving.
Dave Love <fx@gnu.org>
parents:
diff changeset
447
Dave Love <fx@gnu.org>
parents:
diff changeset
448 For most files, the variable @code{make-backup-files} determines
Dave Love <fx@gnu.org>
parents:
diff changeset
449 whether to make backup files. On most operating systems, its default
Dave Love <fx@gnu.org>
parents:
diff changeset
450 value is @code{t}, so that Emacs does write backup files.
Dave Love <fx@gnu.org>
parents:
diff changeset
451
Dave Love <fx@gnu.org>
parents:
diff changeset
452 For files managed by a version control system (@pxref{Version
Dave Love <fx@gnu.org>
parents:
diff changeset
453 Control}), the variable @code{vc-make-backup-files} determines whether
Dave Love <fx@gnu.org>
parents:
diff changeset
454 to make backup files. By default, it is @code{nil}, since backup files
Dave Love <fx@gnu.org>
parents:
diff changeset
455 are redundant when you store all the previous versions in a version
Dave Love <fx@gnu.org>
parents:
diff changeset
456 control system. @xref{VC Workfile Handling}.
Dave Love <fx@gnu.org>
parents:
diff changeset
457
28526
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
458 @vindex backup-enable-predicate
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
459 @vindex temporary-file-directory
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
460 @vindex small-temporary-file-directory
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
461 The default value of the @code{backup-enable-predicate} variable
28526
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
462 prevents backup files being written for files in the directories named
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
463 by @code{temporary-file-directory} or @code{small-temporary-file-directory}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
464
Dave Love <fx@gnu.org>
parents:
diff changeset
465 At your option, Emacs can keep either a single backup file or a series of
Dave Love <fx@gnu.org>
parents:
diff changeset
466 numbered backup files for each file that you edit.
Dave Love <fx@gnu.org>
parents:
diff changeset
467
Dave Love <fx@gnu.org>
parents:
diff changeset
468 Emacs makes a backup for a file only the first time the file is saved
Dave Love <fx@gnu.org>
parents:
diff changeset
469 from one buffer. No matter how many times you save a file, its backup file
Dave Love <fx@gnu.org>
parents:
diff changeset
470 continues to contain the contents from before the file was visited.
Dave Love <fx@gnu.org>
parents:
diff changeset
471 Normally this means that the backup file contains the contents from before
Dave Love <fx@gnu.org>
parents:
diff changeset
472 the current editing session; however, if you kill the buffer and then visit
Dave Love <fx@gnu.org>
parents:
diff changeset
473 the file again, a new backup file will be made by the next save.
Dave Love <fx@gnu.org>
parents:
diff changeset
474
Dave Love <fx@gnu.org>
parents:
diff changeset
475 You can also explicitly request making another backup file from a
Dave Love <fx@gnu.org>
parents:
diff changeset
476 buffer even though it has already been saved at least once. If you save
Dave Love <fx@gnu.org>
parents:
diff changeset
477 the buffer with @kbd{C-u C-x C-s}, the version thus saved will be made
Dave Love <fx@gnu.org>
parents:
diff changeset
478 into a backup file if you save the buffer again. @kbd{C-u C-u C-x C-s}
Dave Love <fx@gnu.org>
parents:
diff changeset
479 saves the buffer, but first makes the previous file contents into a new
Dave Love <fx@gnu.org>
parents:
diff changeset
480 backup file. @kbd{C-u C-u C-u C-x C-s} does both things: it makes a
Dave Love <fx@gnu.org>
parents:
diff changeset
481 backup from the previous contents, and arranges to make another from the
Dave Love <fx@gnu.org>
parents:
diff changeset
482 newly saved contents, if you save again.
Dave Love <fx@gnu.org>
parents:
diff changeset
483
Dave Love <fx@gnu.org>
parents:
diff changeset
484 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
485 * Names: Backup Names. How backup files are named;
Dave Love <fx@gnu.org>
parents:
diff changeset
486 choosing single or numbered backup files.
Dave Love <fx@gnu.org>
parents:
diff changeset
487 * Deletion: Backup Deletion. Emacs deletes excess numbered backups.
Dave Love <fx@gnu.org>
parents:
diff changeset
488 * Copying: Backup Copying. Backups can be made by copying or renaming.
Dave Love <fx@gnu.org>
parents:
diff changeset
489 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
490
Dave Love <fx@gnu.org>
parents:
diff changeset
491 @node Backup Names
Dave Love <fx@gnu.org>
parents:
diff changeset
492 @subsubsection Single or Numbered Backups
Dave Love <fx@gnu.org>
parents:
diff changeset
493
Dave Love <fx@gnu.org>
parents:
diff changeset
494 If you choose to have a single backup file (this is the default),
28526
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
495 the backup file's name is normally constructed by appending @samp{~} to the
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
496 file name being edited; thus, the backup file for @file{eval.c} would
Dave Love <fx@gnu.org>
parents:
diff changeset
497 be @file{eval.c~}.
Dave Love <fx@gnu.org>
parents:
diff changeset
498
28526
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
499 @vindex make-backup-file-name-function
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
500 @vindex backup-directory-alist
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
501 You can change this behaviour by defining the variable
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
502 @code{make-backup-file-name-function} to a suitable function.
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
503 Alternatively you can customize the variable
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
504 @var{backup-directory-alist} to specify that files matching certain
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
505 patterns should be backed up in specific directories. A typical use is
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
506 to add an element @code{("." . @var{dir})} to make all backups in the
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
507 directory with absolute name @var{dir}; the names will be mangled to
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
508 prevent clashes between files with the same names originating in
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
509 different directories. Alternatively, adding, say, @code{("." ".~")}
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
510 would make backups in the invisible sub-directory @file{.~} of the
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
511 original file's directory. The directories are created if necessary
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
512 when the backup is made.
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
513
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
514 If you choose to have a series of numbered backup files, backup file
Dave Love <fx@gnu.org>
parents:
diff changeset
515 names are made by appending @samp{.~}, the number, and another @samp{~} to
Dave Love <fx@gnu.org>
parents:
diff changeset
516 the original file name. Thus, the backup files of @file{eval.c} would be
Dave Love <fx@gnu.org>
parents:
diff changeset
517 called @file{eval.c.~1~}, @file{eval.c.~2~}, and so on, through names
28526
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
518 like @file{eval.c.~259~} and beyond. @code{backup-directory-alist} can
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
519 be used to control their location as for single backups.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
520
Dave Love <fx@gnu.org>
parents:
diff changeset
521 If protection stops you from writing backup files under the usual names,
Dave Love <fx@gnu.org>
parents:
diff changeset
522 the backup file is written as @file{%backup%~} in your home directory.
Dave Love <fx@gnu.org>
parents:
diff changeset
523 Only one such file can exist, so only the most recently made such backup is
Dave Love <fx@gnu.org>
parents:
diff changeset
524 available.
Dave Love <fx@gnu.org>
parents:
diff changeset
525
Dave Love <fx@gnu.org>
parents:
diff changeset
526 @vindex version-control
Dave Love <fx@gnu.org>
parents:
diff changeset
527 The choice of single backup or numbered backups is controlled by the
Dave Love <fx@gnu.org>
parents:
diff changeset
528 variable @code{version-control}. Its possible values are
Dave Love <fx@gnu.org>
parents:
diff changeset
529
Dave Love <fx@gnu.org>
parents:
diff changeset
530 @table @code
Dave Love <fx@gnu.org>
parents:
diff changeset
531 @item t
Dave Love <fx@gnu.org>
parents:
diff changeset
532 Make numbered backups.
Dave Love <fx@gnu.org>
parents:
diff changeset
533 @item nil
Dave Love <fx@gnu.org>
parents:
diff changeset
534 Make numbered backups for files that have numbered backups already.
Dave Love <fx@gnu.org>
parents:
diff changeset
535 Otherwise, make single backups.
Dave Love <fx@gnu.org>
parents:
diff changeset
536 @item never
Dave Love <fx@gnu.org>
parents:
diff changeset
537 Do not in any case make numbered backups; always make single backups.
Dave Love <fx@gnu.org>
parents:
diff changeset
538 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
539
Dave Love <fx@gnu.org>
parents:
diff changeset
540 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
541 You can set @code{version-control} locally in an individual buffer to
Dave Love <fx@gnu.org>
parents:
diff changeset
542 control the making of backups for that buffer's file. For example,
Dave Love <fx@gnu.org>
parents:
diff changeset
543 Rmail mode locally sets @code{version-control} to @code{never} to make sure
Dave Love <fx@gnu.org>
parents:
diff changeset
544 that there is only one backup for an Rmail file. @xref{Locals}.
Dave Love <fx@gnu.org>
parents:
diff changeset
545
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 28671
diff changeset
546 @cindex @env{VERSION_CONTROL} environment variable
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 28671
diff changeset
547 If you set the environment variable @env{VERSION_CONTROL}, to tell
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
548 various GNU utilities what to do with backup files, Emacs also obeys the
Dave Love <fx@gnu.org>
parents:
diff changeset
549 environment variable by setting the Lisp variable @code{version-control}
Dave Love <fx@gnu.org>
parents:
diff changeset
550 accordingly at startup. If the environment variable's value is @samp{t}
Dave Love <fx@gnu.org>
parents:
diff changeset
551 or @samp{numbered}, then @code{version-control} becomes @code{t}; if the
Dave Love <fx@gnu.org>
parents:
diff changeset
552 value is @samp{nil} or @samp{existing}, then @code{version-control}
Dave Love <fx@gnu.org>
parents:
diff changeset
553 becomes @code{nil}; if it is @samp{never} or @samp{simple}, then
Dave Love <fx@gnu.org>
parents:
diff changeset
554 @code{version-control} becomes @code{never}.
Dave Love <fx@gnu.org>
parents:
diff changeset
555
Dave Love <fx@gnu.org>
parents:
diff changeset
556 @node Backup Deletion
Dave Love <fx@gnu.org>
parents:
diff changeset
557 @subsubsection Automatic Deletion of Backups
Dave Love <fx@gnu.org>
parents:
diff changeset
558
Dave Love <fx@gnu.org>
parents:
diff changeset
559 To prevent unlimited consumption of disk space, Emacs can delete numbered
Dave Love <fx@gnu.org>
parents:
diff changeset
560 backup versions automatically. Generally Emacs keeps the first few backups
Dave Love <fx@gnu.org>
parents:
diff changeset
561 and the latest few backups, deleting any in between. This happens every
Dave Love <fx@gnu.org>
parents:
diff changeset
562 time a new backup is made.
Dave Love <fx@gnu.org>
parents:
diff changeset
563
Dave Love <fx@gnu.org>
parents:
diff changeset
564 @vindex kept-old-versions
Dave Love <fx@gnu.org>
parents:
diff changeset
565 @vindex kept-new-versions
Dave Love <fx@gnu.org>
parents:
diff changeset
566 The two variables @code{kept-old-versions} and
Dave Love <fx@gnu.org>
parents:
diff changeset
567 @code{kept-new-versions} control this deletion. Their values are,
Dave Love <fx@gnu.org>
parents:
diff changeset
568 respectively the number of oldest (lowest-numbered) backups to keep and
Dave Love <fx@gnu.org>
parents:
diff changeset
569 the number of newest (highest-numbered) ones to keep, each time a new
Dave Love <fx@gnu.org>
parents:
diff changeset
570 backup is made. Recall that these values are used just after a new
Dave Love <fx@gnu.org>
parents:
diff changeset
571 backup version is made; that newly made backup is included in the count
Dave Love <fx@gnu.org>
parents:
diff changeset
572 in @code{kept-new-versions}. By default, both variables are 2.
Dave Love <fx@gnu.org>
parents:
diff changeset
573
Dave Love <fx@gnu.org>
parents:
diff changeset
574 @vindex delete-old-versions
Dave Love <fx@gnu.org>
parents:
diff changeset
575 If @code{delete-old-versions} is non-@code{nil}, the excess
Dave Love <fx@gnu.org>
parents:
diff changeset
576 middle versions are deleted without a murmur. If it is @code{nil}, the
Dave Love <fx@gnu.org>
parents:
diff changeset
577 default, then you are asked whether the excess middle versions should
Dave Love <fx@gnu.org>
parents:
diff changeset
578 really be deleted.
Dave Love <fx@gnu.org>
parents:
diff changeset
579
Dave Love <fx@gnu.org>
parents:
diff changeset
580 Dired's @kbd{.} (Period) command can also be used to delete old versions.
Dave Love <fx@gnu.org>
parents:
diff changeset
581 @xref{Dired Deletion}.
Dave Love <fx@gnu.org>
parents:
diff changeset
582
Dave Love <fx@gnu.org>
parents:
diff changeset
583 @node Backup Copying
Dave Love <fx@gnu.org>
parents:
diff changeset
584 @subsubsection Copying vs.@: Renaming
Dave Love <fx@gnu.org>
parents:
diff changeset
585
Dave Love <fx@gnu.org>
parents:
diff changeset
586 Backup files can be made by copying the old file or by renaming it. This
Dave Love <fx@gnu.org>
parents:
diff changeset
587 makes a difference when the old file has multiple names. If the old file
Dave Love <fx@gnu.org>
parents:
diff changeset
588 is renamed into the backup file, then the alternate names become names for
Dave Love <fx@gnu.org>
parents:
diff changeset
589 the backup file. If the old file is copied instead, then the alternate
Dave Love <fx@gnu.org>
parents:
diff changeset
590 names remain names for the file that you are editing, and the contents
Dave Love <fx@gnu.org>
parents:
diff changeset
591 accessed by those names will be the new contents.
Dave Love <fx@gnu.org>
parents:
diff changeset
592
Dave Love <fx@gnu.org>
parents:
diff changeset
593 The method of making a backup file may also affect the file's owner
Dave Love <fx@gnu.org>
parents:
diff changeset
594 and group. If copying is used, these do not change. If renaming is used,
Dave Love <fx@gnu.org>
parents:
diff changeset
595 you become the file's owner, and the file's group becomes the default
Dave Love <fx@gnu.org>
parents:
diff changeset
596 (different operating systems have different defaults for the group).
Dave Love <fx@gnu.org>
parents:
diff changeset
597
Dave Love <fx@gnu.org>
parents:
diff changeset
598 Having the owner change is usually a good idea, because then the owner
Dave Love <fx@gnu.org>
parents:
diff changeset
599 always shows who last edited the file. Also, the owners of the backups
Dave Love <fx@gnu.org>
parents:
diff changeset
600 show who produced those versions. Occasionally there is a file whose
Dave Love <fx@gnu.org>
parents:
diff changeset
601 owner should not change; it is a good idea for such files to contain
Dave Love <fx@gnu.org>
parents:
diff changeset
602 local variable lists to set @code{backup-by-copying-when-mismatch}
Dave Love <fx@gnu.org>
parents:
diff changeset
603 locally (@pxref{File Variables}).
Dave Love <fx@gnu.org>
parents:
diff changeset
604
Dave Love <fx@gnu.org>
parents:
diff changeset
605 @vindex backup-by-copying
Dave Love <fx@gnu.org>
parents:
diff changeset
606 @vindex backup-by-copying-when-linked
Dave Love <fx@gnu.org>
parents:
diff changeset
607 @vindex backup-by-copying-when-mismatch
Dave Love <fx@gnu.org>
parents:
diff changeset
608 The choice of renaming or copying is controlled by three variables.
Dave Love <fx@gnu.org>
parents:
diff changeset
609 Renaming is the default choice. If the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
610 @code{backup-by-copying} is non-@code{nil}, copying is used. Otherwise,
Dave Love <fx@gnu.org>
parents:
diff changeset
611 if the variable @code{backup-by-copying-when-linked} is non-@code{nil},
Dave Love <fx@gnu.org>
parents:
diff changeset
612 then copying is used for files that have multiple names, but renaming
Dave Love <fx@gnu.org>
parents:
diff changeset
613 may still be used when the file being edited has only one name. If the
Dave Love <fx@gnu.org>
parents:
diff changeset
614 variable @code{backup-by-copying-when-mismatch} is non-@code{nil}, then
Dave Love <fx@gnu.org>
parents:
diff changeset
615 copying is used if renaming would cause the file's owner or group to
Dave Love <fx@gnu.org>
parents:
diff changeset
616 change. @code{backup-by-copying-when-mismatch} is @code{t} by default
Dave Love <fx@gnu.org>
parents:
diff changeset
617 if you start Emacs as the superuser.
Dave Love <fx@gnu.org>
parents:
diff changeset
618
Dave Love <fx@gnu.org>
parents:
diff changeset
619 When a file is managed with a version control system (@pxref{Version
Dave Love <fx@gnu.org>
parents:
diff changeset
620 Control}), Emacs does not normally make backups in the usual way for
Dave Love <fx@gnu.org>
parents:
diff changeset
621 that file. But check-in and check-out are similar in some ways to
Dave Love <fx@gnu.org>
parents:
diff changeset
622 making backups. One unfortunate similarity is that these operations
Dave Love <fx@gnu.org>
parents:
diff changeset
623 typically break hard links, disconnecting the file name you visited from
Dave Love <fx@gnu.org>
parents:
diff changeset
624 any alternate names for the same file. This has nothing to do with
Dave Love <fx@gnu.org>
parents:
diff changeset
625 Emacs---the version control system does it.
Dave Love <fx@gnu.org>
parents:
diff changeset
626
Dave Love <fx@gnu.org>
parents:
diff changeset
627 @node Interlocking
Dave Love <fx@gnu.org>
parents:
diff changeset
628 @subsection Protection against Simultaneous Editing
Dave Love <fx@gnu.org>
parents:
diff changeset
629
Dave Love <fx@gnu.org>
parents:
diff changeset
630 @cindex file dates
Dave Love <fx@gnu.org>
parents:
diff changeset
631 @cindex simultaneous editing
Dave Love <fx@gnu.org>
parents:
diff changeset
632 Simultaneous editing occurs when two users visit the same file, both
Dave Love <fx@gnu.org>
parents:
diff changeset
633 make changes, and then both save them. If nobody were informed that
Dave Love <fx@gnu.org>
parents:
diff changeset
634 this was happening, whichever user saved first would later find that his
Dave Love <fx@gnu.org>
parents:
diff changeset
635 changes were lost.
Dave Love <fx@gnu.org>
parents:
diff changeset
636
Dave Love <fx@gnu.org>
parents:
diff changeset
637 On some systems, Emacs notices immediately when the second user starts
Dave Love <fx@gnu.org>
parents:
diff changeset
638 to change the file, and issues an immediate warning. On all systems,
Dave Love <fx@gnu.org>
parents:
diff changeset
639 Emacs checks when you save the file, and warns if you are about to
Dave Love <fx@gnu.org>
parents:
diff changeset
640 overwrite another user's changes. You can prevent loss of the other
Dave Love <fx@gnu.org>
parents:
diff changeset
641 user's work by taking the proper corrective action instead of saving the
Dave Love <fx@gnu.org>
parents:
diff changeset
642 file.
Dave Love <fx@gnu.org>
parents:
diff changeset
643
Dave Love <fx@gnu.org>
parents:
diff changeset
644 @findex ask-user-about-lock
Dave Love <fx@gnu.org>
parents:
diff changeset
645 @cindex locking files
Dave Love <fx@gnu.org>
parents:
diff changeset
646 When you make the first modification in an Emacs buffer that is
Dave Love <fx@gnu.org>
parents:
diff changeset
647 visiting a file, Emacs records that the file is @dfn{locked} by you.
Dave Love <fx@gnu.org>
parents:
diff changeset
648 (It does this by creating a symbolic link in the same directory with a
Dave Love <fx@gnu.org>
parents:
diff changeset
649 different name.) Emacs removes the lock when you save the changes. The
Dave Love <fx@gnu.org>
parents:
diff changeset
650 idea is that the file is locked whenever an Emacs buffer visiting it has
Dave Love <fx@gnu.org>
parents:
diff changeset
651 unsaved changes.
Dave Love <fx@gnu.org>
parents:
diff changeset
652
Dave Love <fx@gnu.org>
parents:
diff changeset
653 @cindex collision
Dave Love <fx@gnu.org>
parents:
diff changeset
654 If you begin to modify the buffer while the visited file is locked by
Dave Love <fx@gnu.org>
parents:
diff changeset
655 someone else, this constitutes a @dfn{collision}. When Emacs detects a
Dave Love <fx@gnu.org>
parents:
diff changeset
656 collision, it asks you what to do, by calling the Lisp function
Dave Love <fx@gnu.org>
parents:
diff changeset
657 @code{ask-user-about-lock}. You can redefine this function for the sake
Dave Love <fx@gnu.org>
parents:
diff changeset
658 of customization. The standard definition of this function asks you a
Dave Love <fx@gnu.org>
parents:
diff changeset
659 question and accepts three possible answers:
Dave Love <fx@gnu.org>
parents:
diff changeset
660
Dave Love <fx@gnu.org>
parents:
diff changeset
661 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
662 @item s
Dave Love <fx@gnu.org>
parents:
diff changeset
663 Steal the lock. Whoever was already changing the file loses the lock,
Dave Love <fx@gnu.org>
parents:
diff changeset
664 and you gain the lock.
Dave Love <fx@gnu.org>
parents:
diff changeset
665 @item p
Dave Love <fx@gnu.org>
parents:
diff changeset
666 Proceed. Go ahead and edit the file despite its being locked by someone else.
Dave Love <fx@gnu.org>
parents:
diff changeset
667 @item q
Dave Love <fx@gnu.org>
parents:
diff changeset
668 Quit. This causes an error (@code{file-locked}) and the modification you
Dave Love <fx@gnu.org>
parents:
diff changeset
669 were trying to make in the buffer does not actually take place.
Dave Love <fx@gnu.org>
parents:
diff changeset
670 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
671
Dave Love <fx@gnu.org>
parents:
diff changeset
672 Note that locking works on the basis of a file name; if a file has
Dave Love <fx@gnu.org>
parents:
diff changeset
673 multiple names, Emacs does not realize that the two names are the same file
Dave Love <fx@gnu.org>
parents:
diff changeset
674 and cannot prevent two users from editing it simultaneously under different
Dave Love <fx@gnu.org>
parents:
diff changeset
675 names. However, basing locking on names means that Emacs can interlock the
Dave Love <fx@gnu.org>
parents:
diff changeset
676 editing of new files that will not really exist until they are saved.
Dave Love <fx@gnu.org>
parents:
diff changeset
677
Dave Love <fx@gnu.org>
parents:
diff changeset
678 Some systems are not configured to allow Emacs to make locks, and
Dave Love <fx@gnu.org>
parents:
diff changeset
679 there are cases where lock files cannot be written. In these cases,
Dave Love <fx@gnu.org>
parents:
diff changeset
680 Emacs cannot detect trouble in advance, but it still can detect the
Dave Love <fx@gnu.org>
parents:
diff changeset
681 collision when you try to save a file and overwrite someone else's
Dave Love <fx@gnu.org>
parents:
diff changeset
682 changes.
Dave Love <fx@gnu.org>
parents:
diff changeset
683
Dave Love <fx@gnu.org>
parents:
diff changeset
684 If Emacs or the operating system crashes, this may leave behind lock
Dave Love <fx@gnu.org>
parents:
diff changeset
685 files which are stale. So you may occasionally get warnings about
Dave Love <fx@gnu.org>
parents:
diff changeset
686 spurious collisions. When you determine that the collision is spurious,
Dave Love <fx@gnu.org>
parents:
diff changeset
687 just use @kbd{p} to tell Emacs to go ahead anyway.
Dave Love <fx@gnu.org>
parents:
diff changeset
688
Dave Love <fx@gnu.org>
parents:
diff changeset
689 Every time Emacs saves a buffer, it first checks the last-modification
Dave Love <fx@gnu.org>
parents:
diff changeset
690 date of the existing file on disk to verify that it has not changed since the
Dave Love <fx@gnu.org>
parents:
diff changeset
691 file was last visited or saved. If the date does not match, it implies
Dave Love <fx@gnu.org>
parents:
diff changeset
692 that changes were made in the file in some other way, and these changes are
Dave Love <fx@gnu.org>
parents:
diff changeset
693 about to be lost if Emacs actually does save. To prevent this, Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
694 prints a warning message and asks for confirmation before saving.
Dave Love <fx@gnu.org>
parents:
diff changeset
695 Occasionally you will know why the file was changed and know that it does
Dave Love <fx@gnu.org>
parents:
diff changeset
696 not matter; then you can answer @kbd{yes} and proceed. Otherwise, you should
Dave Love <fx@gnu.org>
parents:
diff changeset
697 cancel the save with @kbd{C-g} and investigate the situation.
Dave Love <fx@gnu.org>
parents:
diff changeset
698
Dave Love <fx@gnu.org>
parents:
diff changeset
699 The first thing you should do when notified that simultaneous editing
Dave Love <fx@gnu.org>
parents:
diff changeset
700 has already taken place is to list the directory with @kbd{C-u C-x C-d}
Dave Love <fx@gnu.org>
parents:
diff changeset
701 (@pxref{Directories}). This shows the file's current author. You
Dave Love <fx@gnu.org>
parents:
diff changeset
702 should attempt to contact him to warn him not to continue editing.
Dave Love <fx@gnu.org>
parents:
diff changeset
703 Often the next step is to save the contents of your Emacs buffer under a
Dave Love <fx@gnu.org>
parents:
diff changeset
704 different name, and use @code{diff} to compare the two files.@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
705
Dave Love <fx@gnu.org>
parents:
diff changeset
706 @node Reverting
Dave Love <fx@gnu.org>
parents:
diff changeset
707 @section Reverting a Buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
708 @findex revert-buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
709 @cindex drastic changes
Dave Love <fx@gnu.org>
parents:
diff changeset
710
Dave Love <fx@gnu.org>
parents:
diff changeset
711 If you have made extensive changes to a file and then change your mind
Dave Love <fx@gnu.org>
parents:
diff changeset
712 about them, you can get rid of them by reading in the previous version
Dave Love <fx@gnu.org>
parents:
diff changeset
713 of the file. To do this, use @kbd{M-x revert-buffer}, which operates on
Dave Love <fx@gnu.org>
parents:
diff changeset
714 the current buffer. Since reverting a buffer unintentionally could lose
Dave Love <fx@gnu.org>
parents:
diff changeset
715 a lot of work, you must confirm this command with @kbd{yes}.
Dave Love <fx@gnu.org>
parents:
diff changeset
716
Dave Love <fx@gnu.org>
parents:
diff changeset
717 @code{revert-buffer} keeps point at the same distance (measured in
Dave Love <fx@gnu.org>
parents:
diff changeset
718 characters) from the beginning of the file. If the file was edited only
Dave Love <fx@gnu.org>
parents:
diff changeset
719 slightly, you will be at approximately the same piece of text after
Dave Love <fx@gnu.org>
parents:
diff changeset
720 reverting as before. If you have made drastic changes, the same value of
Dave Love <fx@gnu.org>
parents:
diff changeset
721 point in the old file may address a totally different piece of text.
Dave Love <fx@gnu.org>
parents:
diff changeset
722
Dave Love <fx@gnu.org>
parents:
diff changeset
723 Reverting marks the buffer as ``not modified'' until another change is
Dave Love <fx@gnu.org>
parents:
diff changeset
724 made.
Dave Love <fx@gnu.org>
parents:
diff changeset
725
Dave Love <fx@gnu.org>
parents:
diff changeset
726 Some kinds of buffers whose contents reflect data bases other than files,
Dave Love <fx@gnu.org>
parents:
diff changeset
727 such as Dired buffers, can also be reverted. For them, reverting means
Dave Love <fx@gnu.org>
parents:
diff changeset
728 recalculating their contents from the appropriate data base. Buffers
Dave Love <fx@gnu.org>
parents:
diff changeset
729 created explicitly with @kbd{C-x b} cannot be reverted; @code{revert-buffer}
Dave Love <fx@gnu.org>
parents:
diff changeset
730 reports an error when asked to do so.
Dave Love <fx@gnu.org>
parents:
diff changeset
731
Dave Love <fx@gnu.org>
parents:
diff changeset
732 @vindex revert-without-query
Dave Love <fx@gnu.org>
parents:
diff changeset
733 When you edit a file that changes automatically and frequently---for
Dave Love <fx@gnu.org>
parents:
diff changeset
734 example, a log of output from a process that continues to run---it may be
Dave Love <fx@gnu.org>
parents:
diff changeset
735 useful for Emacs to revert the file without querying you, whenever you
Dave Love <fx@gnu.org>
parents:
diff changeset
736 visit the file again with @kbd{C-x C-f}.
Dave Love <fx@gnu.org>
parents:
diff changeset
737
Dave Love <fx@gnu.org>
parents:
diff changeset
738 To request this behavior, set the variable @code{revert-without-query}
Dave Love <fx@gnu.org>
parents:
diff changeset
739 to a list of regular expressions. When a file name matches one of these
Dave Love <fx@gnu.org>
parents:
diff changeset
740 regular expressions, @code{find-file} and @code{revert-buffer} will
Dave Love <fx@gnu.org>
parents:
diff changeset
741 revert it automatically if it has changed---provided the buffer itself
Dave Love <fx@gnu.org>
parents:
diff changeset
742 is not modified. (If you have edited the text, it would be wrong to
Dave Love <fx@gnu.org>
parents:
diff changeset
743 discard your changes.)
Dave Love <fx@gnu.org>
parents:
diff changeset
744
Dave Love <fx@gnu.org>
parents:
diff changeset
745 @node Auto Save
Dave Love <fx@gnu.org>
parents:
diff changeset
746 @section Auto-Saving: Protection Against Disasters
Dave Love <fx@gnu.org>
parents:
diff changeset
747 @cindex Auto Save mode
Dave Love <fx@gnu.org>
parents:
diff changeset
748 @cindex mode, Auto Save
Dave Love <fx@gnu.org>
parents:
diff changeset
749 @cindex crashes
Dave Love <fx@gnu.org>
parents:
diff changeset
750
Dave Love <fx@gnu.org>
parents:
diff changeset
751 Emacs saves all the visited files from time to time (based on counting
Dave Love <fx@gnu.org>
parents:
diff changeset
752 your keystrokes) without being asked. This is called @dfn{auto-saving}.
Dave Love <fx@gnu.org>
parents:
diff changeset
753 It prevents you from losing more than a limited amount of work if the
Dave Love <fx@gnu.org>
parents:
diff changeset
754 system crashes.
Dave Love <fx@gnu.org>
parents:
diff changeset
755
Dave Love <fx@gnu.org>
parents:
diff changeset
756 When Emacs determines that it is time for auto-saving, each buffer is
Dave Love <fx@gnu.org>
parents:
diff changeset
757 considered, and is auto-saved if auto-saving is turned on for it and it
Dave Love <fx@gnu.org>
parents:
diff changeset
758 has been changed since the last time it was auto-saved. The message
Dave Love <fx@gnu.org>
parents:
diff changeset
759 @samp{Auto-saving...} is displayed in the echo area during auto-saving,
Dave Love <fx@gnu.org>
parents:
diff changeset
760 if any files are actually auto-saved. Errors occurring during
Dave Love <fx@gnu.org>
parents:
diff changeset
761 auto-saving are caught so that they do not interfere with the execution
Dave Love <fx@gnu.org>
parents:
diff changeset
762 of commands you have been typing.
Dave Love <fx@gnu.org>
parents:
diff changeset
763
Dave Love <fx@gnu.org>
parents:
diff changeset
764 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
765 * Files: Auto Save Files. The file where auto-saved changes are
Dave Love <fx@gnu.org>
parents:
diff changeset
766 actually made until you save the file.
Dave Love <fx@gnu.org>
parents:
diff changeset
767 * Control: Auto Save Control. Controlling when and how often to auto-save.
Dave Love <fx@gnu.org>
parents:
diff changeset
768 * Recover:: Recovering text from auto-save files.
Dave Love <fx@gnu.org>
parents:
diff changeset
769 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
770
Dave Love <fx@gnu.org>
parents:
diff changeset
771 @node Auto Save Files
Dave Love <fx@gnu.org>
parents:
diff changeset
772 @subsection Auto-Save Files
Dave Love <fx@gnu.org>
parents:
diff changeset
773
Dave Love <fx@gnu.org>
parents:
diff changeset
774 Auto-saving does not normally save in the files that you visited, because
Dave Love <fx@gnu.org>
parents:
diff changeset
775 it can be very undesirable to save a program that is in an inconsistent
Dave Love <fx@gnu.org>
parents:
diff changeset
776 state when you have made half of a planned change. Instead, auto-saving
Dave Love <fx@gnu.org>
parents:
diff changeset
777 is done in a different file called the @dfn{auto-save file}, and the
Dave Love <fx@gnu.org>
parents:
diff changeset
778 visited file is changed only when you request saving explicitly (such as
Dave Love <fx@gnu.org>
parents:
diff changeset
779 with @kbd{C-x C-s}).
Dave Love <fx@gnu.org>
parents:
diff changeset
780
Dave Love <fx@gnu.org>
parents:
diff changeset
781 Normally, the auto-save file name is made by appending @samp{#} to the
Dave Love <fx@gnu.org>
parents:
diff changeset
782 front and rear of the visited file name. Thus, a buffer visiting file
Dave Love <fx@gnu.org>
parents:
diff changeset
783 @file{foo.c} is auto-saved in a file @file{#foo.c#}. Most buffers that
Dave Love <fx@gnu.org>
parents:
diff changeset
784 are not visiting files are auto-saved only if you request it explicitly;
Dave Love <fx@gnu.org>
parents:
diff changeset
785 when they are auto-saved, the auto-save file name is made by appending
Dave Love <fx@gnu.org>
parents:
diff changeset
786 @samp{#%} to the front and @samp{#} to the rear of buffer name. For
Dave Love <fx@gnu.org>
parents:
diff changeset
787 example, the @samp{*mail*} buffer in which you compose messages to be
Dave Love <fx@gnu.org>
parents:
diff changeset
788 sent is auto-saved in a file named @file{#%*mail*#}. Auto-save file
Dave Love <fx@gnu.org>
parents:
diff changeset
789 names are made this way unless you reprogram parts of Emacs to do
Dave Love <fx@gnu.org>
parents:
diff changeset
790 something different (the functions @code{make-auto-save-file-name} and
Dave Love <fx@gnu.org>
parents:
diff changeset
791 @code{auto-save-file-name-p}). The file name to be used for auto-saving
Dave Love <fx@gnu.org>
parents:
diff changeset
792 in a buffer is calculated when auto-saving is turned on in that buffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
793
Dave Love <fx@gnu.org>
parents:
diff changeset
794 When you delete a substantial part of the text in a large buffer, auto
Dave Love <fx@gnu.org>
parents:
diff changeset
795 save turns off temporarily in that buffer. This is because if you
Dave Love <fx@gnu.org>
parents:
diff changeset
796 deleted the text unintentionally, you might find the auto-save file more
Dave Love <fx@gnu.org>
parents:
diff changeset
797 useful if it contains the deleted text. To reenable auto-saving after
Dave Love <fx@gnu.org>
parents:
diff changeset
798 this happens, save the buffer with @kbd{C-x C-s}, or use @kbd{C-u 1 M-x
Dave Love <fx@gnu.org>
parents:
diff changeset
799 auto-save}.
Dave Love <fx@gnu.org>
parents:
diff changeset
800
Dave Love <fx@gnu.org>
parents:
diff changeset
801 @vindex auto-save-visited-file-name
Dave Love <fx@gnu.org>
parents:
diff changeset
802 If you want auto-saving to be done in the visited file, set the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
803 @code{auto-save-visited-file-name} to be non-@code{nil}. In this mode,
Dave Love <fx@gnu.org>
parents:
diff changeset
804 there is really no difference between auto-saving and explicit saving.
Dave Love <fx@gnu.org>
parents:
diff changeset
805
Dave Love <fx@gnu.org>
parents:
diff changeset
806 @vindex delete-auto-save-files
Dave Love <fx@gnu.org>
parents:
diff changeset
807 A buffer's auto-save file is deleted when you save the buffer in its
Dave Love <fx@gnu.org>
parents:
diff changeset
808 visited file. To inhibit this, set the variable @code{delete-auto-save-files}
Dave Love <fx@gnu.org>
parents:
diff changeset
809 to @code{nil}. Changing the visited file name with @kbd{C-x C-w} or
Dave Love <fx@gnu.org>
parents:
diff changeset
810 @code{set-visited-file-name} renames any auto-save file to go with
Dave Love <fx@gnu.org>
parents:
diff changeset
811 the new visited name.
Dave Love <fx@gnu.org>
parents:
diff changeset
812
Dave Love <fx@gnu.org>
parents:
diff changeset
813 @node Auto Save Control
Dave Love <fx@gnu.org>
parents:
diff changeset
814 @subsection Controlling Auto-Saving
Dave Love <fx@gnu.org>
parents:
diff changeset
815
Dave Love <fx@gnu.org>
parents:
diff changeset
816 @vindex auto-save-default
Dave Love <fx@gnu.org>
parents:
diff changeset
817 @findex auto-save-mode
Dave Love <fx@gnu.org>
parents:
diff changeset
818 Each time you visit a file, auto-saving is turned on for that file's
Dave Love <fx@gnu.org>
parents:
diff changeset
819 buffer if the variable @code{auto-save-default} is non-@code{nil} (but not
Dave Love <fx@gnu.org>
parents:
diff changeset
820 in batch mode; @pxref{Entering Emacs}). The default for this variable is
Dave Love <fx@gnu.org>
parents:
diff changeset
821 @code{t}, so auto-saving is the usual practice for file-visiting buffers.
Dave Love <fx@gnu.org>
parents:
diff changeset
822 Auto-saving can be turned on or off for any existing buffer with the
Dave Love <fx@gnu.org>
parents:
diff changeset
823 command @kbd{M-x auto-save-mode}. Like other minor mode commands, @kbd{M-x
Dave Love <fx@gnu.org>
parents:
diff changeset
824 auto-save-mode} turns auto-saving on with a positive argument, off with a
Dave Love <fx@gnu.org>
parents:
diff changeset
825 zero or negative argument; with no argument, it toggles.
Dave Love <fx@gnu.org>
parents:
diff changeset
826
Dave Love <fx@gnu.org>
parents:
diff changeset
827 @vindex auto-save-interval
Dave Love <fx@gnu.org>
parents:
diff changeset
828 Emacs does auto-saving periodically based on counting how many characters
Dave Love <fx@gnu.org>
parents:
diff changeset
829 you have typed since the last time auto-saving was done. The variable
Dave Love <fx@gnu.org>
parents:
diff changeset
830 @code{auto-save-interval} specifies how many characters there are between
Dave Love <fx@gnu.org>
parents:
diff changeset
831 auto-saves. By default, it is 300.
Dave Love <fx@gnu.org>
parents:
diff changeset
832
Dave Love <fx@gnu.org>
parents:
diff changeset
833 @vindex auto-save-timeout
Dave Love <fx@gnu.org>
parents:
diff changeset
834 Auto-saving also takes place when you stop typing for a while. The
Dave Love <fx@gnu.org>
parents:
diff changeset
835 variable @code{auto-save-timeout} says how many seconds Emacs should
Dave Love <fx@gnu.org>
parents:
diff changeset
836 wait before it does an auto save (and perhaps also a garbage
Dave Love <fx@gnu.org>
parents:
diff changeset
837 collection). (The actual time period is longer if the current buffer is
Dave Love <fx@gnu.org>
parents:
diff changeset
838 long; this is a heuristic which aims to keep out of your way when you
Dave Love <fx@gnu.org>
parents:
diff changeset
839 are editing long buffers, in which auto-save takes an appreciable amount
Dave Love <fx@gnu.org>
parents:
diff changeset
840 of time.) Auto-saving during idle periods accomplishes two things:
Dave Love <fx@gnu.org>
parents:
diff changeset
841 first, it makes sure all your work is saved if you go away from the
Dave Love <fx@gnu.org>
parents:
diff changeset
842 terminal for a while; second, it may avoid some auto-saving while you
Dave Love <fx@gnu.org>
parents:
diff changeset
843 are actually typing.
Dave Love <fx@gnu.org>
parents:
diff changeset
844
Dave Love <fx@gnu.org>
parents:
diff changeset
845 Emacs also does auto-saving whenever it gets a fatal error. This
Dave Love <fx@gnu.org>
parents:
diff changeset
846 includes killing the Emacs job with a shell command such as @samp{kill
Dave Love <fx@gnu.org>
parents:
diff changeset
847 %emacs}, or disconnecting a phone line or network connection.
Dave Love <fx@gnu.org>
parents:
diff changeset
848
Dave Love <fx@gnu.org>
parents:
diff changeset
849 @findex do-auto-save
Dave Love <fx@gnu.org>
parents:
diff changeset
850 You can request an auto-save explicitly with the command @kbd{M-x
Dave Love <fx@gnu.org>
parents:
diff changeset
851 do-auto-save}.
Dave Love <fx@gnu.org>
parents:
diff changeset
852
Dave Love <fx@gnu.org>
parents:
diff changeset
853 @node Recover
Dave Love <fx@gnu.org>
parents:
diff changeset
854 @subsection Recovering Data from Auto-Saves
Dave Love <fx@gnu.org>
parents:
diff changeset
855
Dave Love <fx@gnu.org>
parents:
diff changeset
856 @findex recover-file
Dave Love <fx@gnu.org>
parents:
diff changeset
857 You can use the contents of an auto-save file to recover from a loss
Dave Love <fx@gnu.org>
parents:
diff changeset
858 of data with the command @kbd{M-x recover-file @key{RET} @var{file}
Dave Love <fx@gnu.org>
parents:
diff changeset
859 @key{RET}}. This visits @var{file} and then (after your confirmation)
Dave Love <fx@gnu.org>
parents:
diff changeset
860 restores the contents from its auto-save file @file{#@var{file}#}.
Dave Love <fx@gnu.org>
parents:
diff changeset
861 You can then save with @kbd{C-x C-s} to put the recovered text into
Dave Love <fx@gnu.org>
parents:
diff changeset
862 @var{file} itself. For example, to recover file @file{foo.c} from its
Dave Love <fx@gnu.org>
parents:
diff changeset
863 auto-save file @file{#foo.c#}, do:@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
864
Dave Love <fx@gnu.org>
parents:
diff changeset
865 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
866 M-x recover-file @key{RET} foo.c @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
867 yes @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
868 C-x C-s
Dave Love <fx@gnu.org>
parents:
diff changeset
869 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
870
Dave Love <fx@gnu.org>
parents:
diff changeset
871 Before asking for confirmation, @kbd{M-x recover-file} displays a
Dave Love <fx@gnu.org>
parents:
diff changeset
872 directory listing describing the specified file and the auto-save file,
Dave Love <fx@gnu.org>
parents:
diff changeset
873 so you can compare their sizes and dates. If the auto-save file
Dave Love <fx@gnu.org>
parents:
diff changeset
874 is older, @kbd{M-x recover-file} does not offer to read it.
Dave Love <fx@gnu.org>
parents:
diff changeset
875
Dave Love <fx@gnu.org>
parents:
diff changeset
876 @findex recover-session
Dave Love <fx@gnu.org>
parents:
diff changeset
877 If Emacs or the computer crashes, you can recover all the files you
Dave Love <fx@gnu.org>
parents:
diff changeset
878 were editing from their auto save files with the command @kbd{M-x
Dave Love <fx@gnu.org>
parents:
diff changeset
879 recover-session}. This first shows you a list of recorded interrupted
Dave Love <fx@gnu.org>
parents:
diff changeset
880 sessions. Move point to the one you choose, and type @kbd{C-c C-c}.
Dave Love <fx@gnu.org>
parents:
diff changeset
881
Dave Love <fx@gnu.org>
parents:
diff changeset
882 Then @code{recover-session} asks about each of the files that were
Dave Love <fx@gnu.org>
parents:
diff changeset
883 being edited during that session, asking whether to recover that file.
Dave Love <fx@gnu.org>
parents:
diff changeset
884 If you answer @kbd{y}, it calls @code{recover-file}, which works in its
Dave Love <fx@gnu.org>
parents:
diff changeset
885 normal fashion. It shows the dates of the original file and its
Dave Love <fx@gnu.org>
parents:
diff changeset
886 auto-save file, and asks once again whether to recover that file.
Dave Love <fx@gnu.org>
parents:
diff changeset
887
Dave Love <fx@gnu.org>
parents:
diff changeset
888 When @code{recover-session} is done, the files you've chosen to
Dave Love <fx@gnu.org>
parents:
diff changeset
889 recover are present in Emacs buffers. You should then save them. Only
Dave Love <fx@gnu.org>
parents:
diff changeset
890 this---saving them---updates the files themselves.
Dave Love <fx@gnu.org>
parents:
diff changeset
891
Dave Love <fx@gnu.org>
parents:
diff changeset
892 @vindex auto-save-list-file-prefix
Dave Love <fx@gnu.org>
parents:
diff changeset
893 Interrupted sessions are recorded for later recovery in files named
Dave Love <fx@gnu.org>
parents:
diff changeset
894 @file{~/.saves-@var{pid}-@var{hostname}}. The @samp{~/.saves} portion of
Dave Love <fx@gnu.org>
parents:
diff changeset
895 these names comes from the value of @code{auto-save-list-file-prefix}.
Dave Love <fx@gnu.org>
parents:
diff changeset
896 You can arrange to record sessions in a different place by setting that
Dave Love <fx@gnu.org>
parents:
diff changeset
897 variable in your @file{.emacs} file, but you'll have to redefine
Dave Love <fx@gnu.org>
parents:
diff changeset
898 @code{recover-session} as well to make it look in the new place. If you
Dave Love <fx@gnu.org>
parents:
diff changeset
899 set @code{auto-save-list-file-prefix} to @code{nil} in your
Dave Love <fx@gnu.org>
parents:
diff changeset
900 @file{.emacs} file, sessions are not recorded for recovery.
Dave Love <fx@gnu.org>
parents:
diff changeset
901
Dave Love <fx@gnu.org>
parents:
diff changeset
902 @node File Aliases
Dave Love <fx@gnu.org>
parents:
diff changeset
903 @section File Name Aliases
Dave Love <fx@gnu.org>
parents:
diff changeset
904
Dave Love <fx@gnu.org>
parents:
diff changeset
905 Symbolic links and hard links both make it possible for several file
Dave Love <fx@gnu.org>
parents:
diff changeset
906 names to refer to the same file. Hard links are alternate names that
Dave Love <fx@gnu.org>
parents:
diff changeset
907 refer directly to the file; all the names are equally valid, and no one
Dave Love <fx@gnu.org>
parents:
diff changeset
908 of them is preferred. By contrast, a symbolic link is a kind of defined
Dave Love <fx@gnu.org>
parents:
diff changeset
909 alias: when @file{foo} is a symbolic link to @file{bar}, you can use
Dave Love <fx@gnu.org>
parents:
diff changeset
910 either name to refer to the file, but @file{bar} is the real name, while
Dave Love <fx@gnu.org>
parents:
diff changeset
911 @file{foo} is just an alias. More complex cases occur when symbolic
Dave Love <fx@gnu.org>
parents:
diff changeset
912 links point to directories.
Dave Love <fx@gnu.org>
parents:
diff changeset
913
Dave Love <fx@gnu.org>
parents:
diff changeset
914 If you visit two names for the same file, normally Emacs makes
Dave Love <fx@gnu.org>
parents:
diff changeset
915 two different buffers, but it warns you about the situation.
Dave Love <fx@gnu.org>
parents:
diff changeset
916
Dave Love <fx@gnu.org>
parents:
diff changeset
917 @vindex find-file-existing-other-name
Dave Love <fx@gnu.org>
parents:
diff changeset
918 If you wish to avoid visiting the same file in two buffers under
Dave Love <fx@gnu.org>
parents:
diff changeset
919 different names, set the variable @code{find-file-existing-other-name}
Dave Love <fx@gnu.org>
parents:
diff changeset
920 to a non-@code{nil} value. Then @code{find-file} uses the existing
Dave Love <fx@gnu.org>
parents:
diff changeset
921 buffer visiting the file, no matter which of the file's names you
Dave Love <fx@gnu.org>
parents:
diff changeset
922 specify.
Dave Love <fx@gnu.org>
parents:
diff changeset
923
Dave Love <fx@gnu.org>
parents:
diff changeset
924 @vindex find-file-visit-truename
Dave Love <fx@gnu.org>
parents:
diff changeset
925 @cindex truenames of files
Dave Love <fx@gnu.org>
parents:
diff changeset
926 @cindex file truenames
Dave Love <fx@gnu.org>
parents:
diff changeset
927 If the variable @code{find-file-visit-truename} is non-@code{nil},
Dave Love <fx@gnu.org>
parents:
diff changeset
928 then the file name recorded for a buffer is the file's @dfn{truename}
Dave Love <fx@gnu.org>
parents:
diff changeset
929 (made by replacing all symbolic links with their target names), rather
Dave Love <fx@gnu.org>
parents:
diff changeset
930 than the name you specify. Setting @code{find-file-visit-truename} also
Dave Love <fx@gnu.org>
parents:
diff changeset
931 implies the effect of @code{find-file-existing-other-name}.
Dave Love <fx@gnu.org>
parents:
diff changeset
932
Dave Love <fx@gnu.org>
parents:
diff changeset
933 @node Version Control
Dave Love <fx@gnu.org>
parents:
diff changeset
934 @section Version Control
Dave Love <fx@gnu.org>
parents:
diff changeset
935 @cindex version control
Dave Love <fx@gnu.org>
parents:
diff changeset
936
Dave Love <fx@gnu.org>
parents:
diff changeset
937 @dfn{Version control systems} are packages that can record multiple
Dave Love <fx@gnu.org>
parents:
diff changeset
938 versions of a source file, usually storing the unchanged parts of the
Dave Love <fx@gnu.org>
parents:
diff changeset
939 file just once. Version control systems also record history information
Dave Love <fx@gnu.org>
parents:
diff changeset
940 such as the creation time of each version, who created it, and a
Dave Love <fx@gnu.org>
parents:
diff changeset
941 description of what was changed in that version.
Dave Love <fx@gnu.org>
parents:
diff changeset
942
Dave Love <fx@gnu.org>
parents:
diff changeset
943 The Emacs version control interface is called VC. Its commands work
Dave Love <fx@gnu.org>
parents:
diff changeset
944 with three version control systems---RCS, CVS and SCCS. The GNU project
Dave Love <fx@gnu.org>
parents:
diff changeset
945 recommends RCS and CVS, which are free software and available from the
Dave Love <fx@gnu.org>
parents:
diff changeset
946 Free Software Foundation.
Dave Love <fx@gnu.org>
parents:
diff changeset
947
Dave Love <fx@gnu.org>
parents:
diff changeset
948 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
949 * Introduction to VC:: How version control works in general.
Dave Love <fx@gnu.org>
parents:
diff changeset
950 * VC Mode Line:: How the mode line shows version control status.
Dave Love <fx@gnu.org>
parents:
diff changeset
951 * Basic VC Editing:: How to edit a file under version control.
Dave Love <fx@gnu.org>
parents:
diff changeset
952 * Old Versions:: Examining and comparing old versions.
Dave Love <fx@gnu.org>
parents:
diff changeset
953 * Secondary VC Commands:: The commands used a little less frequently.
Dave Love <fx@gnu.org>
parents:
diff changeset
954 * Branches:: Multiple lines of development.
Dave Love <fx@gnu.org>
parents:
diff changeset
955 * Snapshots:: Sets of file versions treated as a unit.
Dave Love <fx@gnu.org>
parents:
diff changeset
956 * Miscellaneous VC:: Various other commands and features of VC.
Dave Love <fx@gnu.org>
parents:
diff changeset
957 * Customizing VC:: Variables that change VC's behavior.
Dave Love <fx@gnu.org>
parents:
diff changeset
958 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
959
Dave Love <fx@gnu.org>
parents:
diff changeset
960 @node Introduction to VC
Dave Love <fx@gnu.org>
parents:
diff changeset
961 @subsection Introduction to Version Control
Dave Love <fx@gnu.org>
parents:
diff changeset
962
Dave Love <fx@gnu.org>
parents:
diff changeset
963 VC allows you to use a version control system from within Emacs,
Dave Love <fx@gnu.org>
parents:
diff changeset
964 integrating the version control operations smoothly with editing. VC
Dave Love <fx@gnu.org>
parents:
diff changeset
965 provides a uniform interface to version control, so that regardless of
Dave Love <fx@gnu.org>
parents:
diff changeset
966 which version control system is in use, you can use it the same way.
Dave Love <fx@gnu.org>
parents:
diff changeset
967
Dave Love <fx@gnu.org>
parents:
diff changeset
968 This section provides a general overview of version control, and
Dave Love <fx@gnu.org>
parents:
diff changeset
969 describes the version control systems that VC supports. You can skip
Dave Love <fx@gnu.org>
parents:
diff changeset
970 this section if you are already familiar with the version control system
Dave Love <fx@gnu.org>
parents:
diff changeset
971 you want to use.
Dave Love <fx@gnu.org>
parents:
diff changeset
972
Dave Love <fx@gnu.org>
parents:
diff changeset
973 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
974 * Version Systems:: Supported version control back-end systems.
Dave Love <fx@gnu.org>
parents:
diff changeset
975 * VC Concepts:: Words and concepts related to version control.
Dave Love <fx@gnu.org>
parents:
diff changeset
976 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
977
Dave Love <fx@gnu.org>
parents:
diff changeset
978 @node Version Systems
Dave Love <fx@gnu.org>
parents:
diff changeset
979 @subsubsection Supported Version Control Systems
Dave Love <fx@gnu.org>
parents:
diff changeset
980
Dave Love <fx@gnu.org>
parents:
diff changeset
981 @cindex RCS
Dave Love <fx@gnu.org>
parents:
diff changeset
982 @cindex back end (version control)
Dave Love <fx@gnu.org>
parents:
diff changeset
983 VC currently works with three different version control systems or
Dave Love <fx@gnu.org>
parents:
diff changeset
984 ``back ends'': RCS, CVS, and SCCS.
Dave Love <fx@gnu.org>
parents:
diff changeset
985
Dave Love <fx@gnu.org>
parents:
diff changeset
986 RCS is a free version control system that is available from the Free
Dave Love <fx@gnu.org>
parents:
diff changeset
987 Software Foundation. It is perhaps the most mature of the supported
Dave Love <fx@gnu.org>
parents:
diff changeset
988 back ends, and the VC commands are conceptually closest to RCS. Almost
Dave Love <fx@gnu.org>
parents:
diff changeset
989 everything you can do with RCS can be done through VC.
Dave Love <fx@gnu.org>
parents:
diff changeset
990
Dave Love <fx@gnu.org>
parents:
diff changeset
991 @cindex CVS
Dave Love <fx@gnu.org>
parents:
diff changeset
992 CVS is built on top of RCS, and extends the features of RCS, allowing
Dave Love <fx@gnu.org>
parents:
diff changeset
993 for more sophisticated release management, and concurrent multi-user
Dave Love <fx@gnu.org>
parents:
diff changeset
994 development. VC supports basic editing operations under CVS, but for
Dave Love <fx@gnu.org>
parents:
diff changeset
995 some less common tasks you still need to call CVS from the command line.
Dave Love <fx@gnu.org>
parents:
diff changeset
996 Note also that before using CVS you must set up a repository, which is a
Dave Love <fx@gnu.org>
parents:
diff changeset
997 subject too complex to treat here.
Dave Love <fx@gnu.org>
parents:
diff changeset
998
Dave Love <fx@gnu.org>
parents:
diff changeset
999 @cindex SCCS
Dave Love <fx@gnu.org>
parents:
diff changeset
1000 SCCS is a proprietary but widely used version control system. In
Dave Love <fx@gnu.org>
parents:
diff changeset
1001 terms of capabilities, it is the weakest of the three that VC
Dave Love <fx@gnu.org>
parents:
diff changeset
1002 supports. VC compensates for certain features missing in SCCS
Dave Love <fx@gnu.org>
parents:
diff changeset
1003 (snapshots, for example) by implementing them itself, but some other VC
Dave Love <fx@gnu.org>
parents:
diff changeset
1004 features, such as multiple branches, are not available with SCCS. You
Dave Love <fx@gnu.org>
parents:
diff changeset
1005 should use SCCS only if for some reason you cannot use RCS.
Dave Love <fx@gnu.org>
parents:
diff changeset
1006
Dave Love <fx@gnu.org>
parents:
diff changeset
1007 @node VC Concepts
Dave Love <fx@gnu.org>
parents:
diff changeset
1008 @subsubsection Concepts of Version Control
Dave Love <fx@gnu.org>
parents:
diff changeset
1009
Dave Love <fx@gnu.org>
parents:
diff changeset
1010 @cindex master file
Dave Love <fx@gnu.org>
parents:
diff changeset
1011 @cindex registered file
Dave Love <fx@gnu.org>
parents:
diff changeset
1012 When a file is under version control, we also say that it is
Dave Love <fx@gnu.org>
parents:
diff changeset
1013 @dfn{registered} in the version control system. Each registered file
Dave Love <fx@gnu.org>
parents:
diff changeset
1014 has a corresponding @dfn{master file} which represents the file's
Dave Love <fx@gnu.org>
parents:
diff changeset
1015 present state plus its change history---enough to reconstruct the
Dave Love <fx@gnu.org>
parents:
diff changeset
1016 current version or any earlier version. Usually the master file also
Dave Love <fx@gnu.org>
parents:
diff changeset
1017 records a @dfn{log entry} for each version, describing in words what was
Dave Love <fx@gnu.org>
parents:
diff changeset
1018 changed in that version.
Dave Love <fx@gnu.org>
parents:
diff changeset
1019
Dave Love <fx@gnu.org>
parents:
diff changeset
1020 @cindex work file
Dave Love <fx@gnu.org>
parents:
diff changeset
1021 @cindex checking out files
Dave Love <fx@gnu.org>
parents:
diff changeset
1022 The file that is maintained under version control is sometimes called
Dave Love <fx@gnu.org>
parents:
diff changeset
1023 the @dfn{work file} corresponding to its master file. You edit the work
Dave Love <fx@gnu.org>
parents:
diff changeset
1024 file and make changes in it, as you would with an ordinary file. (With
Dave Love <fx@gnu.org>
parents:
diff changeset
1025 SCCS and RCS, you must @dfn{lock} the file before you start to edit it.)
Dave Love <fx@gnu.org>
parents:
diff changeset
1026 After you are done with a set of changes, you @dfn{check the file in},
Dave Love <fx@gnu.org>
parents:
diff changeset
1027 which records the changes in the master file, along with a log entry for
Dave Love <fx@gnu.org>
parents:
diff changeset
1028 them.
Dave Love <fx@gnu.org>
parents:
diff changeset
1029
Dave Love <fx@gnu.org>
parents:
diff changeset
1030 With CVS, there are usually multiple work files corresponding to a
Dave Love <fx@gnu.org>
parents:
diff changeset
1031 single master file---often each user has his own copy. It is also
Dave Love <fx@gnu.org>
parents:
diff changeset
1032 possible to use RCS in this way, but this is not the usual way to use
Dave Love <fx@gnu.org>
parents:
diff changeset
1033 RCS.
Dave Love <fx@gnu.org>
parents:
diff changeset
1034
Dave Love <fx@gnu.org>
parents:
diff changeset
1035 @cindex locking and version control
Dave Love <fx@gnu.org>
parents:
diff changeset
1036 A version control system typically has some mechanism to coordinate
Dave Love <fx@gnu.org>
parents:
diff changeset
1037 between users who want to change the same file. One method is
Dave Love <fx@gnu.org>
parents:
diff changeset
1038 @dfn{locking} (analogous to the locking that Emacs uses to detect
Dave Love <fx@gnu.org>
parents:
diff changeset
1039 simultaneous editing of a file, but distinct from it). The other method
Dave Love <fx@gnu.org>
parents:
diff changeset
1040 is to merge your changes with other people's changes when you check them
Dave Love <fx@gnu.org>
parents:
diff changeset
1041 in.
Dave Love <fx@gnu.org>
parents:
diff changeset
1042
Dave Love <fx@gnu.org>
parents:
diff changeset
1043 With version control locking, work files are normally read-only so
Dave Love <fx@gnu.org>
parents:
diff changeset
1044 that you cannot change them. You ask the version control system to make
Dave Love <fx@gnu.org>
parents:
diff changeset
1045 a work file writable for you by locking it; only one user can do
Dave Love <fx@gnu.org>
parents:
diff changeset
1046 this at any given time. When you check in your changes, that unlocks
Dave Love <fx@gnu.org>
parents:
diff changeset
1047 the file, making the work file read-only again. This allows other users
Dave Love <fx@gnu.org>
parents:
diff changeset
1048 to lock the file to make further changes. SCCS always uses locking, and
Dave Love <fx@gnu.org>
parents:
diff changeset
1049 RCS normally does.
Dave Love <fx@gnu.org>
parents:
diff changeset
1050
Dave Love <fx@gnu.org>
parents:
diff changeset
1051 The other alternative for RCS is to let each user modify the work file
Dave Love <fx@gnu.org>
parents:
diff changeset
1052 at any time. In this mode, locking is not required, but it is
Dave Love <fx@gnu.org>
parents:
diff changeset
1053 permitted; check-in is still the way to record a new version.
Dave Love <fx@gnu.org>
parents:
diff changeset
1054
Dave Love <fx@gnu.org>
parents:
diff changeset
1055 CVS normally allows each user to modify his own copy of the work file
Dave Love <fx@gnu.org>
parents:
diff changeset
1056 at any time, but requires merging with changes from other users at
Dave Love <fx@gnu.org>
parents:
diff changeset
1057 check-in time. However, CVS can also be set up to require locking.
Dave Love <fx@gnu.org>
parents:
diff changeset
1058 (@pxref{Backend Options}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1059
Dave Love <fx@gnu.org>
parents:
diff changeset
1060 @node VC Mode Line
Dave Love <fx@gnu.org>
parents:
diff changeset
1061 @subsection Version Control and the Mode Line
Dave Love <fx@gnu.org>
parents:
diff changeset
1062
Dave Love <fx@gnu.org>
parents:
diff changeset
1063 When you visit a file that is under version control, Emacs indicates
Dave Love <fx@gnu.org>
parents:
diff changeset
1064 this on the mode line. For example, @samp{RCS-1.3} says that RCS is
Dave Love <fx@gnu.org>
parents:
diff changeset
1065 used for that file, and the current version is 1.3.
Dave Love <fx@gnu.org>
parents:
diff changeset
1066
Dave Love <fx@gnu.org>
parents:
diff changeset
1067 The character between the back-end name and the version number
Dave Love <fx@gnu.org>
parents:
diff changeset
1068 indicates the version control status of the file. @samp{-} means that
Dave Love <fx@gnu.org>
parents:
diff changeset
1069 the work file is not locked (if locking is in use), or not modified (if
Dave Love <fx@gnu.org>
parents:
diff changeset
1070 locking is not in use). @samp{:} indicates that the file is locked, or
Dave Love <fx@gnu.org>
parents:
diff changeset
1071 that it is modified. If the file is locked by some other user (for
Dave Love <fx@gnu.org>
parents:
diff changeset
1072 instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1073
Dave Love <fx@gnu.org>
parents:
diff changeset
1074 @node Basic VC Editing
Dave Love <fx@gnu.org>
parents:
diff changeset
1075 @subsection Basic Editing under Version Control
Dave Love <fx@gnu.org>
parents:
diff changeset
1076
Dave Love <fx@gnu.org>
parents:
diff changeset
1077 The principal VC command is an all-purpose command that performs
Dave Love <fx@gnu.org>
parents:
diff changeset
1078 either locking or check-in, depending on the situation.
Dave Love <fx@gnu.org>
parents:
diff changeset
1079
Dave Love <fx@gnu.org>
parents:
diff changeset
1080 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
1081 @item C-x C-q
Dave Love <fx@gnu.org>
parents:
diff changeset
1082 @itemx C-x v v
Dave Love <fx@gnu.org>
parents:
diff changeset
1083 Perform the next logical version control operation on this file.
Dave Love <fx@gnu.org>
parents:
diff changeset
1084 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1085
Dave Love <fx@gnu.org>
parents:
diff changeset
1086 @findex vc-next-action
Dave Love <fx@gnu.org>
parents:
diff changeset
1087 @findex vc-toggle-read-only
Dave Love <fx@gnu.org>
parents:
diff changeset
1088 @kindex C-x v v
Dave Love <fx@gnu.org>
parents:
diff changeset
1089 @kindex C-x C-q @r{(Version Control)}
Dave Love <fx@gnu.org>
parents:
diff changeset
1090 Strictly speaking, the command for this job is @code{vc-next-action},
Dave Love <fx@gnu.org>
parents:
diff changeset
1091 bound to @kbd{C-x v v}. However, the normal meaning of @kbd{C-x C-q} is
Dave Love <fx@gnu.org>
parents:
diff changeset
1092 to make a read-only buffer writable, or vice versa; we have extended it
Dave Love <fx@gnu.org>
parents:
diff changeset
1093 to do the same job properly for files managed by version control, by
Dave Love <fx@gnu.org>
parents:
diff changeset
1094 performing the appropriate version control operations. When you type
Dave Love <fx@gnu.org>
parents:
diff changeset
1095 @kbd{C-x C-q} on a registered file, it acts like @kbd{C-x v v}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1096
Dave Love <fx@gnu.org>
parents:
diff changeset
1097 The precise action of this command depends on the state of the file,
Dave Love <fx@gnu.org>
parents:
diff changeset
1098 and whether the version control system uses locking or not. SCCS and
Dave Love <fx@gnu.org>
parents:
diff changeset
1099 RCS normally use locking; CVS normally does not use locking.
Dave Love <fx@gnu.org>
parents:
diff changeset
1100
Dave Love <fx@gnu.org>
parents:
diff changeset
1101 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1102 * VC with Locking:: RCS in its default mode, SCCS, and optionally CVS.
Dave Love <fx@gnu.org>
parents:
diff changeset
1103 * Without Locking:: Without locking: default mode for CVS.
Dave Love <fx@gnu.org>
parents:
diff changeset
1104 * Log Buffer:: Features available in log entry buffers.
Dave Love <fx@gnu.org>
parents:
diff changeset
1105 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1106
Dave Love <fx@gnu.org>
parents:
diff changeset
1107 @node VC with Locking
Dave Love <fx@gnu.org>
parents:
diff changeset
1108 @subsubsection Basic Version Control with Locking
Dave Love <fx@gnu.org>
parents:
diff changeset
1109
Dave Love <fx@gnu.org>
parents:
diff changeset
1110 If locking is used for the file (as with SCCS, and RCS in its default
Dave Love <fx@gnu.org>
parents:
diff changeset
1111 mode), @kbd{C-x C-q} can either lock a file or check it in:
Dave Love <fx@gnu.org>
parents:
diff changeset
1112
Dave Love <fx@gnu.org>
parents:
diff changeset
1113 @itemize @bullet
Dave Love <fx@gnu.org>
parents:
diff changeset
1114 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
1115 If the file is not locked, @kbd{C-x C-q} locks it, and
Dave Love <fx@gnu.org>
parents:
diff changeset
1116 makes it writable so that you can change it.
Dave Love <fx@gnu.org>
parents:
diff changeset
1117
Dave Love <fx@gnu.org>
parents:
diff changeset
1118 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
1119 If the file is locked by you, and contains changes, @kbd{C-x C-q} checks
Dave Love <fx@gnu.org>
parents:
diff changeset
1120 in the changes. In order to do this, it first reads the log entry
Dave Love <fx@gnu.org>
parents:
diff changeset
1121 for the new version. @xref{Log Buffer}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1122
Dave Love <fx@gnu.org>
parents:
diff changeset
1123 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
1124 If the file is locked by you, but you have not changed it since you
Dave Love <fx@gnu.org>
parents:
diff changeset
1125 locked it, @kbd{C-x C-q} releases the lock and makes the file read-only
Dave Love <fx@gnu.org>
parents:
diff changeset
1126 again.
Dave Love <fx@gnu.org>
parents:
diff changeset
1127
Dave Love <fx@gnu.org>
parents:
diff changeset
1128 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
1129 If the file is locked by some other user, @kbd{C-x C-q} asks you whether
Dave Love <fx@gnu.org>
parents:
diff changeset
1130 you want to ``steal the lock'' from that user. If you say yes, the file
Dave Love <fx@gnu.org>
parents:
diff changeset
1131 becomes locked by you, but a message is sent to the person who had
Dave Love <fx@gnu.org>
parents:
diff changeset
1132 formerly locked the file, to inform him of what has happened.
Dave Love <fx@gnu.org>
parents:
diff changeset
1133 @end itemize
Dave Love <fx@gnu.org>
parents:
diff changeset
1134
Dave Love <fx@gnu.org>
parents:
diff changeset
1135 These rules also apply when you use CVS in locking mode, except
Dave Love <fx@gnu.org>
parents:
diff changeset
1136 that there is no such thing as stealing a lock.
Dave Love <fx@gnu.org>
parents:
diff changeset
1137
Dave Love <fx@gnu.org>
parents:
diff changeset
1138 @node Without Locking
Dave Love <fx@gnu.org>
parents:
diff changeset
1139 @subsubsection Basic Version Control without Locking
Dave Love <fx@gnu.org>
parents:
diff changeset
1140
Dave Love <fx@gnu.org>
parents:
diff changeset
1141 When there is no locking---the default for CVS---work files are always
Dave Love <fx@gnu.org>
parents:
diff changeset
1142 writable; you do not need to do anything before you begin to edit a
Dave Love <fx@gnu.org>
parents:
diff changeset
1143 file. The status indicator on the mode line is @samp{-} if the file is
Dave Love <fx@gnu.org>
parents:
diff changeset
1144 unmodified; it flips to @samp{:} as soon as you save any changes in the
Dave Love <fx@gnu.org>
parents:
diff changeset
1145 work file.
Dave Love <fx@gnu.org>
parents:
diff changeset
1146
Dave Love <fx@gnu.org>
parents:
diff changeset
1147 Here is what @kbd{C-x C-q} does when using CVS:
Dave Love <fx@gnu.org>
parents:
diff changeset
1148
Dave Love <fx@gnu.org>
parents:
diff changeset
1149 @itemize @bullet
Dave Love <fx@gnu.org>
parents:
diff changeset
1150 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
1151 If some other user has checked in changes into the master file,
Dave Love <fx@gnu.org>
parents:
diff changeset
1152 Emacs asks you whether you want to merge those changes into your own
Dave Love <fx@gnu.org>
parents:
diff changeset
1153 work file (@pxref{Merging}). You must do this before you can check in
Dave Love <fx@gnu.org>
parents:
diff changeset
1154 your own changes.
Dave Love <fx@gnu.org>
parents:
diff changeset
1155
Dave Love <fx@gnu.org>
parents:
diff changeset
1156 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
1157 If there are no new changes in the master file, but you have made
Dave Love <fx@gnu.org>
parents:
diff changeset
1158 modifications in your work file, @kbd{C-x C-q} checks in your changes.
Dave Love <fx@gnu.org>
parents:
diff changeset
1159 In order to do this, it first reads the log entry for the new version.
Dave Love <fx@gnu.org>
parents:
diff changeset
1160 @xref{Log Buffer}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1161
Dave Love <fx@gnu.org>
parents:
diff changeset
1162 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
1163 If the file is not modified, the @kbd{C-x C-q} does nothing.
Dave Love <fx@gnu.org>
parents:
diff changeset
1164 @end itemize
Dave Love <fx@gnu.org>
parents:
diff changeset
1165
Dave Love <fx@gnu.org>
parents:
diff changeset
1166 These rules also apply when you use RCS in the mode that does not
Dave Love <fx@gnu.org>
parents:
diff changeset
1167 require locking, except that automatic merging of changes from the
Dave Love <fx@gnu.org>
parents:
diff changeset
1168 master file is not implemented. Unfortunately, this means that nothing
Dave Love <fx@gnu.org>
parents:
diff changeset
1169 informs you if another user has checked in changes in the same file
Dave Love <fx@gnu.org>
parents:
diff changeset
1170 since you began editing it, and when this happens, his changes will be
Dave Love <fx@gnu.org>
parents:
diff changeset
1171 effectively removed when you check in your version (though they will
Dave Love <fx@gnu.org>
parents:
diff changeset
1172 remain in the master file, so they will not be entirely lost). You must
Dave Love <fx@gnu.org>
parents:
diff changeset
1173 therefore verify the current version is unchanged, before you check in your
Dave Love <fx@gnu.org>
parents:
diff changeset
1174 changes. We hope to eliminate this risk and provide automatic merging
Dave Love <fx@gnu.org>
parents:
diff changeset
1175 with RCS in a future Emacs version.
Dave Love <fx@gnu.org>
parents:
diff changeset
1176
Dave Love <fx@gnu.org>
parents:
diff changeset
1177 In addition, locking is possible with RCS even in this mode, although
Dave Love <fx@gnu.org>
parents:
diff changeset
1178 it is not required; @kbd{C-x C-q} with an unmodified file locks the
Dave Love <fx@gnu.org>
parents:
diff changeset
1179 file, just as it does with RCS in its normal (locking) mode.
Dave Love <fx@gnu.org>
parents:
diff changeset
1180
Dave Love <fx@gnu.org>
parents:
diff changeset
1181 @node Log Buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
1182 @subsubsection Features of the Log Entry Buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
1183
Dave Love <fx@gnu.org>
parents:
diff changeset
1184 When you check in changes, @kbd{C-x C-q} first reads a log entry. It
Dave Love <fx@gnu.org>
parents:
diff changeset
1185 pops up a buffer called @samp{*VC-Log*} for you to enter the log entry.
Dave Love <fx@gnu.org>
parents:
diff changeset
1186 When you are finished, type @kbd{C-c C-c} in the @samp{*VC-Log*} buffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
1187 That is when check-in really happens.
Dave Love <fx@gnu.org>
parents:
diff changeset
1188
Dave Love <fx@gnu.org>
parents:
diff changeset
1189 To abort check-in, just @strong{don't} type @kbd{C-c C-c} in that
Dave Love <fx@gnu.org>
parents:
diff changeset
1190 buffer. You can switch buffers and do other editing. As long as you
Dave Love <fx@gnu.org>
parents:
diff changeset
1191 don't try to check in another file, the entry you were editing remains
Dave Love <fx@gnu.org>
parents:
diff changeset
1192 in the @samp{*VC-Log*} buffer, and you can go back to that buffer at any
Dave Love <fx@gnu.org>
parents:
diff changeset
1193 time to complete the check-in.
Dave Love <fx@gnu.org>
parents:
diff changeset
1194
Dave Love <fx@gnu.org>
parents:
diff changeset
1195 If you change several source files for the same reason, it is often
Dave Love <fx@gnu.org>
parents:
diff changeset
1196 convenient to specify the same log entry for many of the files. To do
Dave Love <fx@gnu.org>
parents:
diff changeset
1197 this, use the history of previous log entries. The commands @kbd{M-n},
Dave Love <fx@gnu.org>
parents:
diff changeset
1198 @kbd{M-p}, @kbd{M-s} and @kbd{M-r} for doing this work just like the
Dave Love <fx@gnu.org>
parents:
diff changeset
1199 minibuffer history commands (except that these versions are used outside
Dave Love <fx@gnu.org>
parents:
diff changeset
1200 the minibuffer).
Dave Love <fx@gnu.org>
parents:
diff changeset
1201
Dave Love <fx@gnu.org>
parents:
diff changeset
1202 @vindex vc-log-mode-hook
Dave Love <fx@gnu.org>
parents:
diff changeset
1203 Each time you check in a file, the log entry buffer is put into VC Log
Dave Love <fx@gnu.org>
parents:
diff changeset
1204 mode, which involves running two hooks: @code{text-mode-hook} and
Dave Love <fx@gnu.org>
parents:
diff changeset
1205 @code{vc-log-mode-hook}. @xref{Hooks}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1206
Dave Love <fx@gnu.org>
parents:
diff changeset
1207 @node Old Versions
Dave Love <fx@gnu.org>
parents:
diff changeset
1208 @subsection Examining And Comparing Old Versions
Dave Love <fx@gnu.org>
parents:
diff changeset
1209
Dave Love <fx@gnu.org>
parents:
diff changeset
1210 One of the convenient features of version control is the ability
Dave Love <fx@gnu.org>
parents:
diff changeset
1211 to examine any version of a file, or compare two versions.
Dave Love <fx@gnu.org>
parents:
diff changeset
1212
Dave Love <fx@gnu.org>
parents:
diff changeset
1213 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
1214 @item C-x v ~ @var{version} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
1215 Examine version @var{version} of the visited file, in a buffer of its
Dave Love <fx@gnu.org>
parents:
diff changeset
1216 own.
Dave Love <fx@gnu.org>
parents:
diff changeset
1217
Dave Love <fx@gnu.org>
parents:
diff changeset
1218 @item C-x v =
Dave Love <fx@gnu.org>
parents:
diff changeset
1219 Compare the current buffer contents with the latest checked-in version
Dave Love <fx@gnu.org>
parents:
diff changeset
1220 of the file.
Dave Love <fx@gnu.org>
parents:
diff changeset
1221
Dave Love <fx@gnu.org>
parents:
diff changeset
1222 @item C-u C-x v = @var{file} @key{RET} @var{oldvers} @key{RET} @var{newvers} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
1223 Compare the specified two versions of @var{file}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1224
Dave Love <fx@gnu.org>
parents:
diff changeset
1225 @item C-x v g
Dave Love <fx@gnu.org>
parents:
diff changeset
1226 Display the result of the CVS annotate command using colors.
Dave Love <fx@gnu.org>
parents:
diff changeset
1227 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1228
Dave Love <fx@gnu.org>
parents:
diff changeset
1229 @findex vc-version-other-window
Dave Love <fx@gnu.org>
parents:
diff changeset
1230 @kindex C-x v ~
Dave Love <fx@gnu.org>
parents:
diff changeset
1231 To examine an old version in toto, visit the file and then type
Dave Love <fx@gnu.org>
parents:
diff changeset
1232 @kbd{C-x v ~ @var{version} @key{RET}} (@code{vc-version-other-window}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1233 This puts the text of version @var{version} in a file named
Dave Love <fx@gnu.org>
parents:
diff changeset
1234 @file{@var{filename}.~@var{version}~}, and visits it in its own buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
1235 in a separate window. (In RCS, you can also select an old version
Dave Love <fx@gnu.org>
parents:
diff changeset
1236 and create a branch from it. @xref{Branches}.)
Dave Love <fx@gnu.org>
parents:
diff changeset
1237
Dave Love <fx@gnu.org>
parents:
diff changeset
1238 @findex vc-diff
Dave Love <fx@gnu.org>
parents:
diff changeset
1239 @kindex C-x v =
Dave Love <fx@gnu.org>
parents:
diff changeset
1240 But usually it is more convenient to compare two versions of the file,
Dave Love <fx@gnu.org>
parents:
diff changeset
1241 with the command @kbd{C-x v =} (@code{vc-diff}). Plain @kbd{C-x v =}
Dave Love <fx@gnu.org>
parents:
diff changeset
1242 compares the current buffer contents (saving them in the file if
Dave Love <fx@gnu.org>
parents:
diff changeset
1243 necessary) with the last checked-in version of the file. @kbd{C-u C-x v
Dave Love <fx@gnu.org>
parents:
diff changeset
1244 =}, with a numeric argument, reads a file name and two version numbers,
Dave Love <fx@gnu.org>
parents:
diff changeset
1245 then compares those versions of the specified file.
Dave Love <fx@gnu.org>
parents:
diff changeset
1246
Dave Love <fx@gnu.org>
parents:
diff changeset
1247 If you supply a directory name instead of the name of a registered
Dave Love <fx@gnu.org>
parents:
diff changeset
1248 file, this command compares the two specified versions of all registered
Dave Love <fx@gnu.org>
parents:
diff changeset
1249 files in that directory and its subdirectories.
Dave Love <fx@gnu.org>
parents:
diff changeset
1250
Dave Love <fx@gnu.org>
parents:
diff changeset
1251 You can specify a checked-in version by its number; an empty input
Dave Love <fx@gnu.org>
parents:
diff changeset
1252 specifies the current contents of the work file (which may be different
Dave Love <fx@gnu.org>
parents:
diff changeset
1253 from all the checked-in versions). You can also specify a snapshot name
Dave Love <fx@gnu.org>
parents:
diff changeset
1254 (@pxref{Snapshots}) instead of one or both version numbers.
Dave Love <fx@gnu.org>
parents:
diff changeset
1255
Dave Love <fx@gnu.org>
parents:
diff changeset
1256 This command works by running the @code{diff} utility, getting the
Dave Love <fx@gnu.org>
parents:
diff changeset
1257 options from the variable @code{diff-switches}. It displays the output
Dave Love <fx@gnu.org>
parents:
diff changeset
1258 in a special buffer in another window. Unlike the @kbd{M-x diff}
Dave Love <fx@gnu.org>
parents:
diff changeset
1259 command, @kbd{C-x v =} does not try to locate the changes in the old and
Dave Love <fx@gnu.org>
parents:
diff changeset
1260 new versions. This is because normally one or both versions do not
Dave Love <fx@gnu.org>
parents:
diff changeset
1261 exist as files when you compare them; they exist only in the records of
Dave Love <fx@gnu.org>
parents:
diff changeset
1262 the master file. @xref{Comparing Files}, for more information about
Dave Love <fx@gnu.org>
parents:
diff changeset
1263 @kbd{M-x diff}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1264
Dave Love <fx@gnu.org>
parents:
diff changeset
1265 @findex vc-annotate
Dave Love <fx@gnu.org>
parents:
diff changeset
1266 @kindex C-x v g
Dave Love <fx@gnu.org>
parents:
diff changeset
1267 For CVS-controlled files, you can display the result of the CVS
Dave Love <fx@gnu.org>
parents:
diff changeset
1268 annotate command, using colors to enhance the visual appearance. Use
Dave Love <fx@gnu.org>
parents:
diff changeset
1269 the command @kbd{M-x vc-annotate} to do this. Red means new, blue means
Dave Love <fx@gnu.org>
parents:
diff changeset
1270 old, and intermediate colors indicate intermediate ages. A prefix
Dave Love <fx@gnu.org>
parents:
diff changeset
1271 argument @var{n} specifies a stretch factor for the time scale; it makes
Dave Love <fx@gnu.org>
parents:
diff changeset
1272 each color cover a period @var{n} times as long.
Dave Love <fx@gnu.org>
parents:
diff changeset
1273
Dave Love <fx@gnu.org>
parents:
diff changeset
1274 @node Secondary VC Commands
Dave Love <fx@gnu.org>
parents:
diff changeset
1275 @subsection The Secondary Commands of VC
Dave Love <fx@gnu.org>
parents:
diff changeset
1276
Dave Love <fx@gnu.org>
parents:
diff changeset
1277 This section explains the secondary commands of VC; those that you might
Dave Love <fx@gnu.org>
parents:
diff changeset
1278 use once a day.
Dave Love <fx@gnu.org>
parents:
diff changeset
1279
Dave Love <fx@gnu.org>
parents:
diff changeset
1280 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1281 * Registering:: Putting a file under version control.
Dave Love <fx@gnu.org>
parents:
diff changeset
1282 * VC Status:: Viewing the VC status of files.
Dave Love <fx@gnu.org>
parents:
diff changeset
1283 * VC Undo:: Cancelling changes before or after check-in.
Dave Love <fx@gnu.org>
parents:
diff changeset
1284 * VC Dired Mode:: Listing files managed by version control.
Dave Love <fx@gnu.org>
parents:
diff changeset
1285 * VC Dired Commands:: Commands to use in a VC Dired buffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
1286 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1287
Dave Love <fx@gnu.org>
parents:
diff changeset
1288 @node Registering
Dave Love <fx@gnu.org>
parents:
diff changeset
1289 @subsubsection Registering a File for Version Control
Dave Love <fx@gnu.org>
parents:
diff changeset
1290
Dave Love <fx@gnu.org>
parents:
diff changeset
1291 @kindex C-x v i
Dave Love <fx@gnu.org>
parents:
diff changeset
1292 @findex vc-register
Dave Love <fx@gnu.org>
parents:
diff changeset
1293 You can put any file under version control by simply visiting it, and
Dave Love <fx@gnu.org>
parents:
diff changeset
1294 then typing @w{@kbd{C-x v i}} (@code{vc-register}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1295
Dave Love <fx@gnu.org>
parents:
diff changeset
1296 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
1297 @item C-x v i
Dave Love <fx@gnu.org>
parents:
diff changeset
1298 Register the visited file for version control.
Dave Love <fx@gnu.org>
parents:
diff changeset
1299 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1300
Dave Love <fx@gnu.org>
parents:
diff changeset
1301 @vindex vc-default-back-end
Dave Love <fx@gnu.org>
parents:
diff changeset
1302 To register the file, Emacs must choose which version control system
Dave Love <fx@gnu.org>
parents:
diff changeset
1303 to use for it. You can specify your choice explicitly by setting
Dave Love <fx@gnu.org>
parents:
diff changeset
1304 @code{vc-default-back-end} to @code{RCS}, @code{CVS} or @code{SCCS}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1305 Otherwise, if there is a subdirectory named @file{RCS}, @file{SCCS}, or
Dave Love <fx@gnu.org>
parents:
diff changeset
1306 @file{CVS}, Emacs uses the corresponding version control system. In the
Dave Love <fx@gnu.org>
parents:
diff changeset
1307 absence of any specification, the default choice is RCS if RCS is
Dave Love <fx@gnu.org>
parents:
diff changeset
1308 installed, otherwise SCCS.
Dave Love <fx@gnu.org>
parents:
diff changeset
1309
Dave Love <fx@gnu.org>
parents:
diff changeset
1310 If locking is in use, @kbd{C-x v i} leaves the file unlocked and
Dave Love <fx@gnu.org>
parents:
diff changeset
1311 read-only. Type @kbd{C-x C-q} if you wish to start editing it. After
Dave Love <fx@gnu.org>
parents:
diff changeset
1312 registering a file with CVS, you must subsequently commit the initial
Dave Love <fx@gnu.org>
parents:
diff changeset
1313 version by typing @kbd{C-x C-q}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1314
Dave Love <fx@gnu.org>
parents:
diff changeset
1315 @vindex vc-default-init-version
Dave Love <fx@gnu.org>
parents:
diff changeset
1316 The initial version number for a newly registered file is 1.1, by
Dave Love <fx@gnu.org>
parents:
diff changeset
1317 default. You can specify a different default by setting the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
1318 @code{vc-default-init-version}, or you can give @kbd{C-x v i} a numeric
Dave Love <fx@gnu.org>
parents:
diff changeset
1319 argument; then it reads the initial version number for this particular
Dave Love <fx@gnu.org>
parents:
diff changeset
1320 file using the minibuffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
1321
Dave Love <fx@gnu.org>
parents:
diff changeset
1322 @vindex vc-initial-comment
Dave Love <fx@gnu.org>
parents:
diff changeset
1323 If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an
Dave Love <fx@gnu.org>
parents:
diff changeset
1324 initial comment to describe the purpose of this source file. Reading
Dave Love <fx@gnu.org>
parents:
diff changeset
1325 the initial comment works like reading a log entry (@pxref{Log Buffer}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1326
Dave Love <fx@gnu.org>
parents:
diff changeset
1327 @node VC Status
Dave Love <fx@gnu.org>
parents:
diff changeset
1328 @subsubsection VC Status Commands
Dave Love <fx@gnu.org>
parents:
diff changeset
1329
Dave Love <fx@gnu.org>
parents:
diff changeset
1330 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
1331 @item C-x v l
Dave Love <fx@gnu.org>
parents:
diff changeset
1332 Display version control state and change history.
Dave Love <fx@gnu.org>
parents:
diff changeset
1333 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1334
Dave Love <fx@gnu.org>
parents:
diff changeset
1335 @kindex C-x v l
Dave Love <fx@gnu.org>
parents:
diff changeset
1336 @findex vc-print-log
Dave Love <fx@gnu.org>
parents:
diff changeset
1337 To view the detailed version control status and history of a file,
Dave Love <fx@gnu.org>
parents:
diff changeset
1338 type @kbd{C-x v l} (@code{vc-print-log}). It displays the history of
Dave Love <fx@gnu.org>
parents:
diff changeset
1339 changes to the current file, including the text of the log entries. The
Dave Love <fx@gnu.org>
parents:
diff changeset
1340 output appears in a separate window.
Dave Love <fx@gnu.org>
parents:
diff changeset
1341
Dave Love <fx@gnu.org>
parents:
diff changeset
1342 @node VC Undo
Dave Love <fx@gnu.org>
parents:
diff changeset
1343 @subsubsection Undoing Version Control Actions
Dave Love <fx@gnu.org>
parents:
diff changeset
1344
Dave Love <fx@gnu.org>
parents:
diff changeset
1345 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
1346 @item C-x v u
Dave Love <fx@gnu.org>
parents:
diff changeset
1347 Revert the buffer and the file to the last checked-in version.
Dave Love <fx@gnu.org>
parents:
diff changeset
1348
Dave Love <fx@gnu.org>
parents:
diff changeset
1349 @item C-x v c
Dave Love <fx@gnu.org>
parents:
diff changeset
1350 Remove the last-entered change from the master for the visited file.
Dave Love <fx@gnu.org>
parents:
diff changeset
1351 This undoes your last check-in.
Dave Love <fx@gnu.org>
parents:
diff changeset
1352 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1353
Dave Love <fx@gnu.org>
parents:
diff changeset
1354 @kindex C-x v u
Dave Love <fx@gnu.org>
parents:
diff changeset
1355 @findex vc-revert-buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
1356 If you want to discard your current set of changes and revert to the
Dave Love <fx@gnu.org>
parents:
diff changeset
1357 last version checked in, use @kbd{C-x v u} (@code{vc-revert-buffer}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1358 This leaves the file unlocked; if locking is in use, you must first lock
Dave Love <fx@gnu.org>
parents:
diff changeset
1359 the file again before you change it again. @kbd{C-x v u} requires
Dave Love <fx@gnu.org>
parents:
diff changeset
1360 confirmation, unless it sees that you haven't made any changes since the
Dave Love <fx@gnu.org>
parents:
diff changeset
1361 last checked-in version.
Dave Love <fx@gnu.org>
parents:
diff changeset
1362
Dave Love <fx@gnu.org>
parents:
diff changeset
1363 @kbd{C-x v u} is also the command to unlock a file if you lock it and
Dave Love <fx@gnu.org>
parents:
diff changeset
1364 then decide not to change it.
Dave Love <fx@gnu.org>
parents:
diff changeset
1365
Dave Love <fx@gnu.org>
parents:
diff changeset
1366 @kindex C-x v c
Dave Love <fx@gnu.org>
parents:
diff changeset
1367 @findex vc-cancel-version
Dave Love <fx@gnu.org>
parents:
diff changeset
1368 To cancel a change that you already checked in, use @kbd{C-x v c}
Dave Love <fx@gnu.org>
parents:
diff changeset
1369 (@code{vc-cancel-version}). This command discards all record of the
Dave Love <fx@gnu.org>
parents:
diff changeset
1370 most recent checked-in version. @kbd{C-x v c} also offers to revert
Dave Love <fx@gnu.org>
parents:
diff changeset
1371 your work file and buffer to the previous version (the one that precedes
Dave Love <fx@gnu.org>
parents:
diff changeset
1372 the version that is deleted).
Dave Love <fx@gnu.org>
parents:
diff changeset
1373
Dave Love <fx@gnu.org>
parents:
diff changeset
1374 If you answer @kbd{no}, VC keeps your changes in the buffer, and locks
Dave Love <fx@gnu.org>
parents:
diff changeset
1375 the file. The no-revert option is useful when you have checked in a
Dave Love <fx@gnu.org>
parents:
diff changeset
1376 change and then discover a trivial error in it; you can cancel the
Dave Love <fx@gnu.org>
parents:
diff changeset
1377 erroneous check-in, fix the error, and check the file in again.
Dave Love <fx@gnu.org>
parents:
diff changeset
1378
Dave Love <fx@gnu.org>
parents:
diff changeset
1379 When @kbd{C-x v c} does not revert the buffer, it unexpands all
Dave Love <fx@gnu.org>
parents:
diff changeset
1380 version control headers in the buffer instead (@pxref{Version Headers}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1381 This is because the buffer no longer corresponds to any existing
Dave Love <fx@gnu.org>
parents:
diff changeset
1382 version. If you check it in again, the check-in process will expand the
Dave Love <fx@gnu.org>
parents:
diff changeset
1383 headers properly for the new version number.
Dave Love <fx@gnu.org>
parents:
diff changeset
1384
Dave Love <fx@gnu.org>
parents:
diff changeset
1385 However, it is impossible to unexpand the RCS @samp{@w{$}Log$} header
Dave Love <fx@gnu.org>
parents:
diff changeset
1386 automatically. If you use that header feature, you have to unexpand it
Dave Love <fx@gnu.org>
parents:
diff changeset
1387 by hand---by deleting the entry for the version that you just canceled.
Dave Love <fx@gnu.org>
parents:
diff changeset
1388
Dave Love <fx@gnu.org>
parents:
diff changeset
1389 Be careful when invoking @kbd{C-x v c}, as it is easy to lose a lot of
Dave Love <fx@gnu.org>
parents:
diff changeset
1390 work with it. To help you be careful, this command always requires
Dave Love <fx@gnu.org>
parents:
diff changeset
1391 confirmation with @kbd{yes}. Note also that this command is disabled
Dave Love <fx@gnu.org>
parents:
diff changeset
1392 under CVS, because canceling versions is very dangerous and discouraged
Dave Love <fx@gnu.org>
parents:
diff changeset
1393 with CVS.
Dave Love <fx@gnu.org>
parents:
diff changeset
1394
Dave Love <fx@gnu.org>
parents:
diff changeset
1395 @node VC Dired Mode
Dave Love <fx@gnu.org>
parents:
diff changeset
1396 @subsubsection Dired under VC
Dave Love <fx@gnu.org>
parents:
diff changeset
1397
Dave Love <fx@gnu.org>
parents:
diff changeset
1398 @kindex C-x v d
Dave Love <fx@gnu.org>
parents:
diff changeset
1399 @findex vc-directory
Dave Love <fx@gnu.org>
parents:
diff changeset
1400 When you are working on a large program, it is often useful to find
Dave Love <fx@gnu.org>
parents:
diff changeset
1401 out which files have changed within an entire directory tree, or to view
Dave Love <fx@gnu.org>
parents:
diff changeset
1402 the status of all files under version control at once, and to perform
Dave Love <fx@gnu.org>
parents:
diff changeset
1403 version control operations on collections of files. You can use the
Dave Love <fx@gnu.org>
parents:
diff changeset
1404 command @kbd{C-x v d} (@code{vc-directory}) to make a directory listing
Dave Love <fx@gnu.org>
parents:
diff changeset
1405 that includes only files relevant for version control.
Dave Love <fx@gnu.org>
parents:
diff changeset
1406
Dave Love <fx@gnu.org>
parents:
diff changeset
1407 @vindex vc-dired-terse-display
Dave Love <fx@gnu.org>
parents:
diff changeset
1408 @kbd{C-x v d} creates a buffer which uses VC Dired Mode. This looks
Dave Love <fx@gnu.org>
parents:
diff changeset
1409 much like an ordinary Dired buffer (@pxref{Dired}); however, normally it
Dave Love <fx@gnu.org>
parents:
diff changeset
1410 shows only the noteworthy files (those locked or not up-to-date). This
Dave Love <fx@gnu.org>
parents:
diff changeset
1411 is called @dfn{terse display}. If you set the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
1412 @code{vc-dired-terse-display} to @code{nil}, then VC Dired shows all
Dave Love <fx@gnu.org>
parents:
diff changeset
1413 relevant files---those managed under version control, plus all
Dave Love <fx@gnu.org>
parents:
diff changeset
1414 subdirectories (@dfn{full display}). The command @kbd{v t} in a VC
Dave Love <fx@gnu.org>
parents:
diff changeset
1415 Dired buffer toggles between terse display and full display (@pxref{VC
Dave Love <fx@gnu.org>
parents:
diff changeset
1416 Dired Commands}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1417
Dave Love <fx@gnu.org>
parents:
diff changeset
1418 @vindex vc-dired-recurse
Dave Love <fx@gnu.org>
parents:
diff changeset
1419 By default, VC Dired produces a recursive listing of noteworthy or
Dave Love <fx@gnu.org>
parents:
diff changeset
1420 relevant files at or below the given directory. You can change this by
Dave Love <fx@gnu.org>
parents:
diff changeset
1421 setting the variable @code{vc-dired-recurse} to @code{nil}; then VC
Dave Love <fx@gnu.org>
parents:
diff changeset
1422 Dired shows only the files in the given directory.
Dave Love <fx@gnu.org>
parents:
diff changeset
1423
Dave Love <fx@gnu.org>
parents:
diff changeset
1424 The line for an individual file shows the version control state in the
Dave Love <fx@gnu.org>
parents:
diff changeset
1425 place of the hard link count, owner, group, and size of the file. If
Dave Love <fx@gnu.org>
parents:
diff changeset
1426 the file is unmodified, in sync with the master file, the version
Dave Love <fx@gnu.org>
parents:
diff changeset
1427 control state shown is blank. Otherwise it consists of text in
Dave Love <fx@gnu.org>
parents:
diff changeset
1428 parentheses. Under RCS and SCCS, the name of the user locking the file
Dave Love <fx@gnu.org>
parents:
diff changeset
1429 is shown; under CVS, an abbreviated version of the @samp{cvs status}
Dave Love <fx@gnu.org>
parents:
diff changeset
1430 output is used. Here is an example using RCS:
Dave Love <fx@gnu.org>
parents:
diff changeset
1431
Dave Love <fx@gnu.org>
parents:
diff changeset
1432 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1433 @group
Dave Love <fx@gnu.org>
parents:
diff changeset
1434 /home/jim/project:
Dave Love <fx@gnu.org>
parents:
diff changeset
1435
Dave Love <fx@gnu.org>
parents:
diff changeset
1436 -rw-r--r-- (jim) Apr 2 23:39 file1
Dave Love <fx@gnu.org>
parents:
diff changeset
1437 -r--r--r-- Apr 5 20:21 file2
Dave Love <fx@gnu.org>
parents:
diff changeset
1438 @end group
Dave Love <fx@gnu.org>
parents:
diff changeset
1439 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1440
Dave Love <fx@gnu.org>
parents:
diff changeset
1441 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
1442 The files @samp{file1} and @samp{file2} are under version control,
Dave Love <fx@gnu.org>
parents:
diff changeset
1443 @samp{file1} is locked by user jim, and @samp{file2} is unlocked.
Dave Love <fx@gnu.org>
parents:
diff changeset
1444
Dave Love <fx@gnu.org>
parents:
diff changeset
1445 Here is an example using CVS:
Dave Love <fx@gnu.org>
parents:
diff changeset
1446
Dave Love <fx@gnu.org>
parents:
diff changeset
1447 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1448 @group
Dave Love <fx@gnu.org>
parents:
diff changeset
1449 /home/joe/develop:
Dave Love <fx@gnu.org>
parents:
diff changeset
1450
Dave Love <fx@gnu.org>
parents:
diff changeset
1451 -rw-r--r-- (modified) Aug 2 1997 file1.c
Dave Love <fx@gnu.org>
parents:
diff changeset
1452 -rw-r--r-- Apr 4 20:09 file2.c
Dave Love <fx@gnu.org>
parents:
diff changeset
1453 -rw-r--r-- (merge) Sep 13 1996 file3.c
Dave Love <fx@gnu.org>
parents:
diff changeset
1454 @end group
Dave Love <fx@gnu.org>
parents:
diff changeset
1455 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1456
Dave Love <fx@gnu.org>
parents:
diff changeset
1457 Here @samp{file1.c} is modified with respect to the repository, and
Dave Love <fx@gnu.org>
parents:
diff changeset
1458 @samp{file2.c} is not. @samp{file3.c} is modified, but other changes
Dave Love <fx@gnu.org>
parents:
diff changeset
1459 have also been checked in to the repository---you need to merge them
Dave Love <fx@gnu.org>
parents:
diff changeset
1460 with the work file before you can check it in.
Dave Love <fx@gnu.org>
parents:
diff changeset
1461
Dave Love <fx@gnu.org>
parents:
diff changeset
1462 @vindex vc-directory-exclusion-list
Dave Love <fx@gnu.org>
parents:
diff changeset
1463 When VC Dired displays subdirectories (in the ``full'' display mode),
Dave Love <fx@gnu.org>
parents:
diff changeset
1464 it omits some that should never contain any files under version control.
Dave Love <fx@gnu.org>
parents:
diff changeset
1465 By default, this includes Version Control subdirectories such as
Dave Love <fx@gnu.org>
parents:
diff changeset
1466 @samp{RCS} and @samp{CVS}; you can customize this by setting the
Dave Love <fx@gnu.org>
parents:
diff changeset
1467 variable @code{vc-directory-exclusion-list}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1468
Dave Love <fx@gnu.org>
parents:
diff changeset
1469 You can fine-tune VC Dired's format by typing @kbd{C-u C-x v d}---as in
Dave Love <fx@gnu.org>
parents:
diff changeset
1470 ordinary Dired, that allows you to specify additional switches for the
Dave Love <fx@gnu.org>
parents:
diff changeset
1471 @samp{ls} command.
Dave Love <fx@gnu.org>
parents:
diff changeset
1472
Dave Love <fx@gnu.org>
parents:
diff changeset
1473 @node VC Dired Commands
Dave Love <fx@gnu.org>
parents:
diff changeset
1474 @subsubsection VC Dired Commands
Dave Love <fx@gnu.org>
parents:
diff changeset
1475
Dave Love <fx@gnu.org>
parents:
diff changeset
1476 All the usual Dired commands work normally in VC Dired mode, except
Dave Love <fx@gnu.org>
parents:
diff changeset
1477 for @kbd{v}, which is redefined as the version control prefix. You can
Dave Love <fx@gnu.org>
parents:
diff changeset
1478 invoke VC commands such as @code{vc-diff} and @code{vc-print-log} by
Dave Love <fx@gnu.org>
parents:
diff changeset
1479 typing @kbd{v =}, or @kbd{v l}, and so on. Most of these commands apply
Dave Love <fx@gnu.org>
parents:
diff changeset
1480 to the file name on the current line.
Dave Love <fx@gnu.org>
parents:
diff changeset
1481
Dave Love <fx@gnu.org>
parents:
diff changeset
1482 The command @kbd{v v} (@code{vc-next-action}) operates on all the
Dave Love <fx@gnu.org>
parents:
diff changeset
1483 marked files, so that you can lock or check in several files at once.
Dave Love <fx@gnu.org>
parents:
diff changeset
1484 If it operates on more than one file, it handles each file according to
Dave Love <fx@gnu.org>
parents:
diff changeset
1485 its current state; thus, it might lock one file, but check in another
Dave Love <fx@gnu.org>
parents:
diff changeset
1486 file. This could be confusing; it is up to you to avoid confusing
Dave Love <fx@gnu.org>
parents:
diff changeset
1487 behavior by marking a set of files that are in a similar state.
Dave Love <fx@gnu.org>
parents:
diff changeset
1488
Dave Love <fx@gnu.org>
parents:
diff changeset
1489 If any files call for check-in, @kbd{v v} reads a single log entry,
Dave Love <fx@gnu.org>
parents:
diff changeset
1490 then uses it for all the files being checked in. This is convenient for
Dave Love <fx@gnu.org>
parents:
diff changeset
1491 registering or checking in several files at once, as part of the same
Dave Love <fx@gnu.org>
parents:
diff changeset
1492 change.
Dave Love <fx@gnu.org>
parents:
diff changeset
1493
Dave Love <fx@gnu.org>
parents:
diff changeset
1494 @findex vc-dired-toggle-terse-mode
Dave Love <fx@gnu.org>
parents:
diff changeset
1495 @findex vc-dired-mark-locked
Dave Love <fx@gnu.org>
parents:
diff changeset
1496 You can toggle between terse display (only locked files, or files not
Dave Love <fx@gnu.org>
parents:
diff changeset
1497 up-to-date) and full display at any time by typing @kbd{v t}
Dave Love <fx@gnu.org>
parents:
diff changeset
1498 @code{vc-dired-toggle-terse-mode}. There is also a special command
Dave Love <fx@gnu.org>
parents:
diff changeset
1499 @kbd{* l} (@code{vc-dired-mark-locked}), which marks all files currently
Dave Love <fx@gnu.org>
parents:
diff changeset
1500 locked (or, with CVS, all files not up-to-date). Thus, typing @kbd{* l
Dave Love <fx@gnu.org>
parents:
diff changeset
1501 t k} is another way to delete from the buffer all files except those
Dave Love <fx@gnu.org>
parents:
diff changeset
1502 currently locked.
Dave Love <fx@gnu.org>
parents:
diff changeset
1503
Dave Love <fx@gnu.org>
parents:
diff changeset
1504 @node Branches
Dave Love <fx@gnu.org>
parents:
diff changeset
1505 @subsection Multiple Branches of a File
Dave Love <fx@gnu.org>
parents:
diff changeset
1506 @cindex branch (version control)
Dave Love <fx@gnu.org>
parents:
diff changeset
1507 @cindex trunk (version control)
Dave Love <fx@gnu.org>
parents:
diff changeset
1508
Dave Love <fx@gnu.org>
parents:
diff changeset
1509 One use of version control is to maintain multiple ``current''
Dave Love <fx@gnu.org>
parents:
diff changeset
1510 versions of a file. For example, you might have different versions of a
Dave Love <fx@gnu.org>
parents:
diff changeset
1511 program in which you are gradually adding various unfinished new
Dave Love <fx@gnu.org>
parents:
diff changeset
1512 features. Each such independent line of development is called a
Dave Love <fx@gnu.org>
parents:
diff changeset
1513 @dfn{branch}. VC allows you to create branches, switch between
Dave Love <fx@gnu.org>
parents:
diff changeset
1514 different branches, and merge changes from one branch to another.
Dave Love <fx@gnu.org>
parents:
diff changeset
1515 Please note, however, that branches are only supported for RCS at the
Dave Love <fx@gnu.org>
parents:
diff changeset
1516 moment.
Dave Love <fx@gnu.org>
parents:
diff changeset
1517
Dave Love <fx@gnu.org>
parents:
diff changeset
1518 A file's main line of development is usually called the @dfn{trunk}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1519 The versions on the trunk are normally numbered 1.1, 1.2, 1.3, etc. At
Dave Love <fx@gnu.org>
parents:
diff changeset
1520 any such version, you can start an independent branch. A branch
Dave Love <fx@gnu.org>
parents:
diff changeset
1521 starting at version 1.2 would have version number 1.2.1.1, and consecutive
Dave Love <fx@gnu.org>
parents:
diff changeset
1522 versions on this branch would have numbers 1.2.1.2, 1.2.1.3, 1.2.1.4,
Dave Love <fx@gnu.org>
parents:
diff changeset
1523 and so on. If there is a second branch also starting at version 1.2, it
Dave Love <fx@gnu.org>
parents:
diff changeset
1524 would consist of versions 1.2.2.1, 1.2.2.2, 1.2.2.3, etc.
Dave Love <fx@gnu.org>
parents:
diff changeset
1525
Dave Love <fx@gnu.org>
parents:
diff changeset
1526 @cindex head version
Dave Love <fx@gnu.org>
parents:
diff changeset
1527 If you omit the final component of a version number, that is called a
Dave Love <fx@gnu.org>
parents:
diff changeset
1528 @dfn{branch number}. It refers to the highest existing version on that
Dave Love <fx@gnu.org>
parents:
diff changeset
1529 branch---the @dfn{head version} of that branch. The branches in the
Dave Love <fx@gnu.org>
parents:
diff changeset
1530 example above have branch numbers 1.2.1 and 1.2.2.
Dave Love <fx@gnu.org>
parents:
diff changeset
1531
Dave Love <fx@gnu.org>
parents:
diff changeset
1532 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1533 * Switching Branches:: How to get to another existing branch.
Dave Love <fx@gnu.org>
parents:
diff changeset
1534 * Creating Branches:: How to start a new branch.
Dave Love <fx@gnu.org>
parents:
diff changeset
1535 * Merging:: Transferring changes between branches.
Dave Love <fx@gnu.org>
parents:
diff changeset
1536 * Multi-User Branching:: Multiple users working at multiple branches
Dave Love <fx@gnu.org>
parents:
diff changeset
1537 in parallel.
Dave Love <fx@gnu.org>
parents:
diff changeset
1538 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1539
Dave Love <fx@gnu.org>
parents:
diff changeset
1540 @node Switching Branches
Dave Love <fx@gnu.org>
parents:
diff changeset
1541 @subsubsection Switching between Branches
Dave Love <fx@gnu.org>
parents:
diff changeset
1542
Dave Love <fx@gnu.org>
parents:
diff changeset
1543 To switch between branches, type @kbd{C-u C-x C-q} and specify the
Dave Love <fx@gnu.org>
parents:
diff changeset
1544 version number you want to select. This version is then visited
Dave Love <fx@gnu.org>
parents:
diff changeset
1545 @emph{unlocked} (write-protected), so you can examine it before locking
Dave Love <fx@gnu.org>
parents:
diff changeset
1546 it. Switching branches in this way is allowed only when the file is not
Dave Love <fx@gnu.org>
parents:
diff changeset
1547 locked.
Dave Love <fx@gnu.org>
parents:
diff changeset
1548
Dave Love <fx@gnu.org>
parents:
diff changeset
1549 You can omit the minor version number, thus giving only the branch
Dave Love <fx@gnu.org>
parents:
diff changeset
1550 number; this takes you to the head version on the chosen branch. If you
Dave Love <fx@gnu.org>
parents:
diff changeset
1551 only type @key{RET}, Emacs goes to the highest version on the trunk.
Dave Love <fx@gnu.org>
parents:
diff changeset
1552
Dave Love <fx@gnu.org>
parents:
diff changeset
1553 After you have switched to any branch (including the main branch), you
Dave Love <fx@gnu.org>
parents:
diff changeset
1554 stay on it for subsequent VC commands, until you explicitly select some
Dave Love <fx@gnu.org>
parents:
diff changeset
1555 other branch.
Dave Love <fx@gnu.org>
parents:
diff changeset
1556
Dave Love <fx@gnu.org>
parents:
diff changeset
1557 @node Creating Branches
Dave Love <fx@gnu.org>
parents:
diff changeset
1558 @subsubsection Creating New Branches
Dave Love <fx@gnu.org>
parents:
diff changeset
1559
Dave Love <fx@gnu.org>
parents:
diff changeset
1560 To create a new branch from a head version (one that is the latest in
Dave Love <fx@gnu.org>
parents:
diff changeset
1561 the branch that contains it), first select that version if necessary,
Dave Love <fx@gnu.org>
parents:
diff changeset
1562 lock it with @kbd{C-x C-q}, and make whatever changes you want. Then,
Dave Love <fx@gnu.org>
parents:
diff changeset
1563 when you check in the changes, use @kbd{C-u C-x C-q}. This lets you
Dave Love <fx@gnu.org>
parents:
diff changeset
1564 specify the version number for the new version. You should specify a
Dave Love <fx@gnu.org>
parents:
diff changeset
1565 suitable branch number for a branch starting at the current version.
Dave Love <fx@gnu.org>
parents:
diff changeset
1566 For example, if the current version is 2.5, the branch number should be
Dave Love <fx@gnu.org>
parents:
diff changeset
1567 2.5.1, 2.5.2, and so on, depending on the number of existing branches at
Dave Love <fx@gnu.org>
parents:
diff changeset
1568 that point.
Dave Love <fx@gnu.org>
parents:
diff changeset
1569
Dave Love <fx@gnu.org>
parents:
diff changeset
1570 To create a new branch at an older version (one that is no longer the
Dave Love <fx@gnu.org>
parents:
diff changeset
1571 head of a branch), first select that version (@pxref{Switching
Dave Love <fx@gnu.org>
parents:
diff changeset
1572 Branches}), then lock it with @kbd{C-x C-q}. You'll be asked to
Dave Love <fx@gnu.org>
parents:
diff changeset
1573 confirm, when you lock the old version, that you really mean to create a
Dave Love <fx@gnu.org>
parents:
diff changeset
1574 new branch---if you say no, you'll be offered a chance to lock the
Dave Love <fx@gnu.org>
parents:
diff changeset
1575 latest version instead.
Dave Love <fx@gnu.org>
parents:
diff changeset
1576
Dave Love <fx@gnu.org>
parents:
diff changeset
1577 Then make your changes and type @kbd{C-x C-q} again to check in a new
Dave Love <fx@gnu.org>
parents:
diff changeset
1578 version. This automatically creates a new branch starting from the
Dave Love <fx@gnu.org>
parents:
diff changeset
1579 selected version. You need not specially request a new branch, because
Dave Love <fx@gnu.org>
parents:
diff changeset
1580 that's the only way to add a new version at a point that is not the head
Dave Love <fx@gnu.org>
parents:
diff changeset
1581 of a branch.
Dave Love <fx@gnu.org>
parents:
diff changeset
1582
Dave Love <fx@gnu.org>
parents:
diff changeset
1583 After the branch is created, you ``stay'' on it. That means that
Dave Love <fx@gnu.org>
parents:
diff changeset
1584 subsequent check-ins create new versions on that branch. To leave the
Dave Love <fx@gnu.org>
parents:
diff changeset
1585 branch, you must explicitly select a different version with @kbd{C-u C-x
Dave Love <fx@gnu.org>
parents:
diff changeset
1586 C-q}. To transfer changes from one branch to another, use the merge
Dave Love <fx@gnu.org>
parents:
diff changeset
1587 command, described in the next section.
Dave Love <fx@gnu.org>
parents:
diff changeset
1588
Dave Love <fx@gnu.org>
parents:
diff changeset
1589 @node Merging
Dave Love <fx@gnu.org>
parents:
diff changeset
1590 @subsubsection Merging Branches
Dave Love <fx@gnu.org>
parents:
diff changeset
1591
Dave Love <fx@gnu.org>
parents:
diff changeset
1592 @cindex merging changes
Dave Love <fx@gnu.org>
parents:
diff changeset
1593 When you have finished the changes on a certain branch, you will
Dave Love <fx@gnu.org>
parents:
diff changeset
1594 often want to incorporate them into the file's main line of development
Dave Love <fx@gnu.org>
parents:
diff changeset
1595 (the trunk). This is not a trivial operation, because development might
Dave Love <fx@gnu.org>
parents:
diff changeset
1596 also have proceeded on the trunk, so that you must @dfn{merge} the
Dave Love <fx@gnu.org>
parents:
diff changeset
1597 changes into a file that has already been changed otherwise. VC allows
Dave Love <fx@gnu.org>
parents:
diff changeset
1598 you to do this (and other things) with the @code{vc-merge} command.
Dave Love <fx@gnu.org>
parents:
diff changeset
1599
Dave Love <fx@gnu.org>
parents:
diff changeset
1600 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
1601 @item C-x v m (vc-merge)
Dave Love <fx@gnu.org>
parents:
diff changeset
1602 Merge changes into the work file.
Dave Love <fx@gnu.org>
parents:
diff changeset
1603 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1604
Dave Love <fx@gnu.org>
parents:
diff changeset
1605 @kindex C-x v m
Dave Love <fx@gnu.org>
parents:
diff changeset
1606 @findex vc-merge
Dave Love <fx@gnu.org>
parents:
diff changeset
1607 @kbd{C-x v m} (@code{vc-merge}) takes a set of changes and merges it
Dave Love <fx@gnu.org>
parents:
diff changeset
1608 into the current version of the work file. It first asks you for a
Dave Love <fx@gnu.org>
parents:
diff changeset
1609 branch number or a pair of version numbers in the minibuffer. Then it
Dave Love <fx@gnu.org>
parents:
diff changeset
1610 finds the changes from that branch, or between the two versions you
Dave Love <fx@gnu.org>
parents:
diff changeset
1611 specified, and merges them into the current version of the current file.
Dave Love <fx@gnu.org>
parents:
diff changeset
1612
Dave Love <fx@gnu.org>
parents:
diff changeset
1613 As an example, suppose that you have finished a certain feature on
Dave Love <fx@gnu.org>
parents:
diff changeset
1614 branch 1.3.1. In the meantime, development on the trunk has proceeded
Dave Love <fx@gnu.org>
parents:
diff changeset
1615 to version 1.5. To merge the changes from the branch to the trunk,
Dave Love <fx@gnu.org>
parents:
diff changeset
1616 first go to the head version of the trunk, by typing @kbd{C-u C-x C-q
Dave Love <fx@gnu.org>
parents:
diff changeset
1617 RET}. Version 1.5 is now current. If locking is used for the file,
Dave Love <fx@gnu.org>
parents:
diff changeset
1618 type @kbd{C-x C-q} to lock version 1.5 so that you can change it. Next,
Dave Love <fx@gnu.org>
parents:
diff changeset
1619 type @kbd{C-x v m 1.3.1 RET}. This takes the entire set of changes on
Dave Love <fx@gnu.org>
parents:
diff changeset
1620 branch 1.3.1 (relative to version 1.3, where the branch started, up to
Dave Love <fx@gnu.org>
parents:
diff changeset
1621 the last version on the branch) and merges it into the current version
Dave Love <fx@gnu.org>
parents:
diff changeset
1622 of the work file. You can now check in the changed file, thus creating
Dave Love <fx@gnu.org>
parents:
diff changeset
1623 version 1.6 containing the changes from the branch.
Dave Love <fx@gnu.org>
parents:
diff changeset
1624
Dave Love <fx@gnu.org>
parents:
diff changeset
1625 It is possible to do further editing after merging the branch, before
Dave Love <fx@gnu.org>
parents:
diff changeset
1626 the next check-in. But it is usually wiser to check in the merged
Dave Love <fx@gnu.org>
parents:
diff changeset
1627 version, then lock it and make the further changes. This will keep
Dave Love <fx@gnu.org>
parents:
diff changeset
1628 a better record of the history of changes.
Dave Love <fx@gnu.org>
parents:
diff changeset
1629
Dave Love <fx@gnu.org>
parents:
diff changeset
1630 @cindex conflicts
Dave Love <fx@gnu.org>
parents:
diff changeset
1631 @cindex resolving conflicts
Dave Love <fx@gnu.org>
parents:
diff changeset
1632 When you merge changes into a file that has itself been modified, the
Dave Love <fx@gnu.org>
parents:
diff changeset
1633 changes might overlap. We call this situation a @dfn{conflict}, and
Dave Love <fx@gnu.org>
parents:
diff changeset
1634 reconciling the conflicting changes is called @dfn{resolving a
Dave Love <fx@gnu.org>
parents:
diff changeset
1635 conflict}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1636
Dave Love <fx@gnu.org>
parents:
diff changeset
1637 Whenever conflicts occur during merging, VC detects them, tells you
Dave Love <fx@gnu.org>
parents:
diff changeset
1638 about them in the echo area, and asks whether you want help in merging.
Dave Love <fx@gnu.org>
parents:
diff changeset
1639 If you say yes, it starts an Ediff session (@pxref{Top,
Dave Love <fx@gnu.org>
parents:
diff changeset
1640 Ediff, Ediff, ediff, The Ediff Manual}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1641
Dave Love <fx@gnu.org>
parents:
diff changeset
1642 If you say no, the conflicting changes are both inserted into the
Dave Love <fx@gnu.org>
parents:
diff changeset
1643 file, surrounded by @dfn{conflict markers}. The example below shows how
Dave Love <fx@gnu.org>
parents:
diff changeset
1644 a conflict region looks; the file is called @samp{name} and the current
Dave Love <fx@gnu.org>
parents:
diff changeset
1645 master file version with user B's changes in it is 1.11.
Dave Love <fx@gnu.org>
parents:
diff changeset
1646
Dave Love <fx@gnu.org>
parents:
diff changeset
1647 @c @w here is so CVS won't think this is a conflict.
Dave Love <fx@gnu.org>
parents:
diff changeset
1648 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1649 @group
Dave Love <fx@gnu.org>
parents:
diff changeset
1650 @w{<}<<<<<< name
Dave Love <fx@gnu.org>
parents:
diff changeset
1651 @var{User A's version}
Dave Love <fx@gnu.org>
parents:
diff changeset
1652 =======
Dave Love <fx@gnu.org>
parents:
diff changeset
1653 @var{User B's version}
Dave Love <fx@gnu.org>
parents:
diff changeset
1654 @w{>}>>>>>> 1.11
Dave Love <fx@gnu.org>
parents:
diff changeset
1655 @end group
Dave Love <fx@gnu.org>
parents:
diff changeset
1656 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1657
Dave Love <fx@gnu.org>
parents:
diff changeset
1658 @cindex vc-resolve-conflicts
Dave Love <fx@gnu.org>
parents:
diff changeset
1659 Then you can resolve the conflicts by editing the file manually. Or
Dave Love <fx@gnu.org>
parents:
diff changeset
1660 you can type @code{M-x vc-resolve-conflicts} after visiting the file.
Dave Love <fx@gnu.org>
parents:
diff changeset
1661 This starts an Ediff session, as described above.
Dave Love <fx@gnu.org>
parents:
diff changeset
1662
Dave Love <fx@gnu.org>
parents:
diff changeset
1663 @node Multi-User Branching
Dave Love <fx@gnu.org>
parents:
diff changeset
1664 @subsubsection Multi-User Branching
Dave Love <fx@gnu.org>
parents:
diff changeset
1665
Dave Love <fx@gnu.org>
parents:
diff changeset
1666 It is often useful for multiple developers to work simultaneously on
Dave Love <fx@gnu.org>
parents:
diff changeset
1667 different branches of a file. CVS allows this by default; for RCS, it
Dave Love <fx@gnu.org>
parents:
diff changeset
1668 is possible if you create multiple source directories. Each source
Dave Love <fx@gnu.org>
parents:
diff changeset
1669 directory should have a link named @file{RCS} which points to a common
Dave Love <fx@gnu.org>
parents:
diff changeset
1670 directory of RCS master files. Then each source directory can have its
Dave Love <fx@gnu.org>
parents:
diff changeset
1671 own choice of selected versions, but all share the same common RCS
Dave Love <fx@gnu.org>
parents:
diff changeset
1672 records.
Dave Love <fx@gnu.org>
parents:
diff changeset
1673
Dave Love <fx@gnu.org>
parents:
diff changeset
1674 This technique works reliably and automatically, provided that the
Dave Love <fx@gnu.org>
parents:
diff changeset
1675 source files contain RCS version headers (@pxref{Version Headers}). The
Dave Love <fx@gnu.org>
parents:
diff changeset
1676 headers enable Emacs to be sure, at all times, which version number is
Dave Love <fx@gnu.org>
parents:
diff changeset
1677 present in the work file.
Dave Love <fx@gnu.org>
parents:
diff changeset
1678
Dave Love <fx@gnu.org>
parents:
diff changeset
1679 If the files do not have version headers, you must instead tell Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
1680 explicitly in each session which branch you are working on. To do this,
Dave Love <fx@gnu.org>
parents:
diff changeset
1681 first find the file, then type @kbd{C-u C-x C-q} and specify the correct
Dave Love <fx@gnu.org>
parents:
diff changeset
1682 branch number. This ensures that Emacs knows which branch it is using
Dave Love <fx@gnu.org>
parents:
diff changeset
1683 during this particular editing session.
Dave Love <fx@gnu.org>
parents:
diff changeset
1684
Dave Love <fx@gnu.org>
parents:
diff changeset
1685 @node Snapshots
Dave Love <fx@gnu.org>
parents:
diff changeset
1686 @subsection Snapshots
Dave Love <fx@gnu.org>
parents:
diff changeset
1687 @cindex snapshots and version control
Dave Love <fx@gnu.org>
parents:
diff changeset
1688
Dave Love <fx@gnu.org>
parents:
diff changeset
1689 A @dfn{snapshot} is a named set of file versions (one for each
Dave Love <fx@gnu.org>
parents:
diff changeset
1690 registered file) that you can treat as a unit. One important kind of
Dave Love <fx@gnu.org>
parents:
diff changeset
1691 snapshot is a @dfn{release}, a (theoretically) stable version of the
Dave Love <fx@gnu.org>
parents:
diff changeset
1692 system that is ready for distribution to users.
Dave Love <fx@gnu.org>
parents:
diff changeset
1693
Dave Love <fx@gnu.org>
parents:
diff changeset
1694 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1695 * Making Snapshots:: The snapshot facilities.
Dave Love <fx@gnu.org>
parents:
diff changeset
1696 * Snapshot Caveats:: Things to be careful of when using snapshots.
Dave Love <fx@gnu.org>
parents:
diff changeset
1697 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1698
Dave Love <fx@gnu.org>
parents:
diff changeset
1699 @node Making Snapshots
Dave Love <fx@gnu.org>
parents:
diff changeset
1700 @subsubsection Making and Using Snapshots
Dave Love <fx@gnu.org>
parents:
diff changeset
1701
Dave Love <fx@gnu.org>
parents:
diff changeset
1702 There are two basic commands for snapshots; one makes a
Dave Love <fx@gnu.org>
parents:
diff changeset
1703 snapshot with a given name, the other retrieves a named snapshot.
Dave Love <fx@gnu.org>
parents:
diff changeset
1704
Dave Love <fx@gnu.org>
parents:
diff changeset
1705 @table @code
Dave Love <fx@gnu.org>
parents:
diff changeset
1706 @kindex C-x v s
Dave Love <fx@gnu.org>
parents:
diff changeset
1707 @findex vc-create-snapshot
Dave Love <fx@gnu.org>
parents:
diff changeset
1708 @item C-x v s @var{name} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
1709 Define the last saved versions of every registered file in or under the
Dave Love <fx@gnu.org>
parents:
diff changeset
1710 current directory as a snapshot named @var{name}
Dave Love <fx@gnu.org>
parents:
diff changeset
1711 (@code{vc-create-snapshot}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1712
Dave Love <fx@gnu.org>
parents:
diff changeset
1713 @kindex C-x v r
Dave Love <fx@gnu.org>
parents:
diff changeset
1714 @findex vc-retrieve-snapshot
Dave Love <fx@gnu.org>
parents:
diff changeset
1715 @item C-x v r @var{name} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
1716 For all registered files at or below the current directory level, select
Dave Love <fx@gnu.org>
parents:
diff changeset
1717 whatever versions correspond to the snapshot @var{name}
Dave Love <fx@gnu.org>
parents:
diff changeset
1718 (@code{vc-retrieve-snapshot}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1719
Dave Love <fx@gnu.org>
parents:
diff changeset
1720 This command reports an error if any files are locked at or below the
Dave Love <fx@gnu.org>
parents:
diff changeset
1721 current directory, without changing anything; this is to avoid
Dave Love <fx@gnu.org>
parents:
diff changeset
1722 overwriting work in progress.
Dave Love <fx@gnu.org>
parents:
diff changeset
1723 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1724
Dave Love <fx@gnu.org>
parents:
diff changeset
1725 A snapshot uses a very small amount of resources---just enough to record
Dave Love <fx@gnu.org>
parents:
diff changeset
1726 the list of file names and which version belongs to the snapshot. Thus,
Dave Love <fx@gnu.org>
parents:
diff changeset
1727 you need not hesitate to create snapshots whenever they are useful.
Dave Love <fx@gnu.org>
parents:
diff changeset
1728
Dave Love <fx@gnu.org>
parents:
diff changeset
1729 You can give a snapshot name as an argument to @kbd{C-x v =} or
Dave Love <fx@gnu.org>
parents:
diff changeset
1730 @kbd{C-x v ~} (@pxref{Old Versions}). Thus, you can use it to compare a
Dave Love <fx@gnu.org>
parents:
diff changeset
1731 snapshot against the current files, or two snapshots against each other,
Dave Love <fx@gnu.org>
parents:
diff changeset
1732 or a snapshot against a named version.
Dave Love <fx@gnu.org>
parents:
diff changeset
1733
Dave Love <fx@gnu.org>
parents:
diff changeset
1734 @node Snapshot Caveats
Dave Love <fx@gnu.org>
parents:
diff changeset
1735 @subsubsection Snapshot Caveats
Dave Love <fx@gnu.org>
parents:
diff changeset
1736
Dave Love <fx@gnu.org>
parents:
diff changeset
1737 @cindex named configurations (RCS)
Dave Love <fx@gnu.org>
parents:
diff changeset
1738 VC's snapshot facilities are modeled on RCS's named-configuration
Dave Love <fx@gnu.org>
parents:
diff changeset
1739 support. They use RCS's native facilities for this, so under VC
Dave Love <fx@gnu.org>
parents:
diff changeset
1740 snapshots made using RCS are visible even when you bypass VC.
Dave Love <fx@gnu.org>
parents:
diff changeset
1741
Dave Love <fx@gnu.org>
parents:
diff changeset
1742 @c worded verbosely to avoid overfull hbox.
Dave Love <fx@gnu.org>
parents:
diff changeset
1743 For SCCS, VC implements snapshots itself. The files it uses contain
Dave Love <fx@gnu.org>
parents:
diff changeset
1744 name/file/version-number triples. These snapshots are visible only
Dave Love <fx@gnu.org>
parents:
diff changeset
1745 through VC.
Dave Love <fx@gnu.org>
parents:
diff changeset
1746
Dave Love <fx@gnu.org>
parents:
diff changeset
1747 A snapshot is a set of checked-in versions. So make sure that all the
Dave Love <fx@gnu.org>
parents:
diff changeset
1748 files are checked in and not locked when you make a snapshot.
Dave Love <fx@gnu.org>
parents:
diff changeset
1749
Dave Love <fx@gnu.org>
parents:
diff changeset
1750 File renaming and deletion can create some difficulties with snapshots.
Dave Love <fx@gnu.org>
parents:
diff changeset
1751 This is not a VC-specific problem, but a general design issue in version
Dave Love <fx@gnu.org>
parents:
diff changeset
1752 control systems that no one has solved very well yet.
Dave Love <fx@gnu.org>
parents:
diff changeset
1753
Dave Love <fx@gnu.org>
parents:
diff changeset
1754 If you rename a registered file, you need to rename its master along
Dave Love <fx@gnu.org>
parents:
diff changeset
1755 with it (the command @code{vc-rename-file} does this automatically). If
Dave Love <fx@gnu.org>
parents:
diff changeset
1756 you are using SCCS, you must also update the records of the snapshot, to
Dave Love <fx@gnu.org>
parents:
diff changeset
1757 mention the file by its new name (@code{vc-rename-file} does this,
Dave Love <fx@gnu.org>
parents:
diff changeset
1758 too). An old snapshot that refers to a master file that no longer
Dave Love <fx@gnu.org>
parents:
diff changeset
1759 exists under the recorded name is invalid; VC can no longer retrieve
Dave Love <fx@gnu.org>
parents:
diff changeset
1760 it. It would be beyond the scope of this manual to explain enough about
Dave Love <fx@gnu.org>
parents:
diff changeset
1761 RCS and SCCS to explain how to update the snapshots by hand.
Dave Love <fx@gnu.org>
parents:
diff changeset
1762
Dave Love <fx@gnu.org>
parents:
diff changeset
1763 Using @code{vc-rename-file} makes the snapshot remain valid for
Dave Love <fx@gnu.org>
parents:
diff changeset
1764 retrieval, but it does not solve all problems. For example, some of the
Dave Love <fx@gnu.org>
parents:
diff changeset
1765 files in the program probably refer to others by name. At the very
Dave Love <fx@gnu.org>
parents:
diff changeset
1766 least, the makefile probably mentions the file that you renamed. If you
Dave Love <fx@gnu.org>
parents:
diff changeset
1767 retrieve an old snapshot, the renamed file is retrieved under its new
Dave Love <fx@gnu.org>
parents:
diff changeset
1768 name, which is not the name that the makefile expects. So the program
Dave Love <fx@gnu.org>
parents:
diff changeset
1769 won't really work as retrieved.
Dave Love <fx@gnu.org>
parents:
diff changeset
1770
Dave Love <fx@gnu.org>
parents:
diff changeset
1771 @node Miscellaneous VC
Dave Love <fx@gnu.org>
parents:
diff changeset
1772 @subsection Miscellaneous Commands and Features of VC
Dave Love <fx@gnu.org>
parents:
diff changeset
1773
Dave Love <fx@gnu.org>
parents:
diff changeset
1774 This section explains the less-frequently-used features of VC.
Dave Love <fx@gnu.org>
parents:
diff changeset
1775
Dave Love <fx@gnu.org>
parents:
diff changeset
1776 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1777 * Change Logs and VC:: Generating a change log file from log entries.
Dave Love <fx@gnu.org>
parents:
diff changeset
1778 * Renaming and VC:: A command to rename both the source and master
Dave Love <fx@gnu.org>
parents:
diff changeset
1779 file correctly.
Dave Love <fx@gnu.org>
parents:
diff changeset
1780 * Version Headers:: Inserting version control headers into working files.
Dave Love <fx@gnu.org>
parents:
diff changeset
1781 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1782
Dave Love <fx@gnu.org>
parents:
diff changeset
1783 @node Change Logs and VC
Dave Love <fx@gnu.org>
parents:
diff changeset
1784 @subsubsection Change Logs and VC
Dave Love <fx@gnu.org>
parents:
diff changeset
1785
Dave Love <fx@gnu.org>
parents:
diff changeset
1786 If you use RCS or CVS for a program and also maintain a change log
Dave Love <fx@gnu.org>
parents:
diff changeset
1787 file for it (@pxref{Change Log}), you can generate change log entries
Dave Love <fx@gnu.org>
parents:
diff changeset
1788 automatically from the version control log entries:
Dave Love <fx@gnu.org>
parents:
diff changeset
1789
Dave Love <fx@gnu.org>
parents:
diff changeset
1790 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
1791 @item C-x v a
Dave Love <fx@gnu.org>
parents:
diff changeset
1792 @kindex C-x v a
Dave Love <fx@gnu.org>
parents:
diff changeset
1793 @findex vc-update-change-log
Dave Love <fx@gnu.org>
parents:
diff changeset
1794 Visit the current directory's change log file and, for registered files
Dave Love <fx@gnu.org>
parents:
diff changeset
1795 in that directory, create new entries for versions checked in since the
Dave Love <fx@gnu.org>
parents:
diff changeset
1796 most recent entry in the change log file.
Dave Love <fx@gnu.org>
parents:
diff changeset
1797 (@code{vc-update-change-log}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1798
Dave Love <fx@gnu.org>
parents:
diff changeset
1799 This command works with RCS or CVS only, not with SCCS.
Dave Love <fx@gnu.org>
parents:
diff changeset
1800
Dave Love <fx@gnu.org>
parents:
diff changeset
1801 @item C-u C-x v a
Dave Love <fx@gnu.org>
parents:
diff changeset
1802 As above, but only find entries for the current buffer's file.
Dave Love <fx@gnu.org>
parents:
diff changeset
1803
Dave Love <fx@gnu.org>
parents:
diff changeset
1804 @item M-1 C-x v a
Dave Love <fx@gnu.org>
parents:
diff changeset
1805 As above, but find entries for all the currently visited files that are
Dave Love <fx@gnu.org>
parents:
diff changeset
1806 maintained with version control. This works only with RCS, and it puts
Dave Love <fx@gnu.org>
parents:
diff changeset
1807 all entries in the log for the default directory, which may not be
Dave Love <fx@gnu.org>
parents:
diff changeset
1808 appropriate.
Dave Love <fx@gnu.org>
parents:
diff changeset
1809 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1810
Dave Love <fx@gnu.org>
parents:
diff changeset
1811 For example, suppose the first line of @file{ChangeLog} is dated
Dave Love <fx@gnu.org>
parents:
diff changeset
1812 1999-04-10, and that the only check-in since then was by Nathaniel
Dave Love <fx@gnu.org>
parents:
diff changeset
1813 Bowditch to @file{rcs2log} on 1999-05-22 with log text @samp{Ignore log
Dave Love <fx@gnu.org>
parents:
diff changeset
1814 messages that start with `#'.}. Then @kbd{C-x v a} visits
Dave Love <fx@gnu.org>
parents:
diff changeset
1815 @file{ChangeLog} and inserts text like this:
Dave Love <fx@gnu.org>
parents:
diff changeset
1816
Dave Love <fx@gnu.org>
parents:
diff changeset
1817 @iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
1818 @medbreak
Dave Love <fx@gnu.org>
parents:
diff changeset
1819 @end iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
1820 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1821 @group
Dave Love <fx@gnu.org>
parents:
diff changeset
1822 1999-05-22 Nathaniel Bowditch <nat@@apn.org>
Dave Love <fx@gnu.org>
parents:
diff changeset
1823
Dave Love <fx@gnu.org>
parents:
diff changeset
1824 * rcs2log: Ignore log messages that start with `#'.
Dave Love <fx@gnu.org>
parents:
diff changeset
1825 @end group
Dave Love <fx@gnu.org>
parents:
diff changeset
1826 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1827 @iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
1828 @medbreak
Dave Love <fx@gnu.org>
parents:
diff changeset
1829 @end iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
1830
Dave Love <fx@gnu.org>
parents:
diff changeset
1831 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
1832 You can then edit the new change log entry further as you wish.
Dave Love <fx@gnu.org>
parents:
diff changeset
1833
Dave Love <fx@gnu.org>
parents:
diff changeset
1834 Unfortunately, timestamps in ChangeLog files are only dates, so some
Dave Love <fx@gnu.org>
parents:
diff changeset
1835 of the new change log entry may duplicate what's already in ChangeLog.
Dave Love <fx@gnu.org>
parents:
diff changeset
1836 You will have to remove these duplicates by hand.
Dave Love <fx@gnu.org>
parents:
diff changeset
1837
Dave Love <fx@gnu.org>
parents:
diff changeset
1838 Normally, the log entry for file @file{foo} is displayed as @samp{*
Dave Love <fx@gnu.org>
parents:
diff changeset
1839 foo: @var{text of log entry}}. The @samp{:} after @file{foo} is omitted
Dave Love <fx@gnu.org>
parents:
diff changeset
1840 if the text of the log entry starts with @w{@samp{(@var{functionname}):
Dave Love <fx@gnu.org>
parents:
diff changeset
1841 }}. For example, if the log entry for @file{vc.el} is
Dave Love <fx@gnu.org>
parents:
diff changeset
1842 @samp{(vc-do-command): Check call-process status.}, then the text in
Dave Love <fx@gnu.org>
parents:
diff changeset
1843 @file{ChangeLog} looks like this:
Dave Love <fx@gnu.org>
parents:
diff changeset
1844
Dave Love <fx@gnu.org>
parents:
diff changeset
1845 @iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
1846 @medbreak
Dave Love <fx@gnu.org>
parents:
diff changeset
1847 @end iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
1848 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1849 @group
Dave Love <fx@gnu.org>
parents:
diff changeset
1850 1999-05-06 Nathaniel Bowditch <nat@@apn.org>
Dave Love <fx@gnu.org>
parents:
diff changeset
1851
Dave Love <fx@gnu.org>
parents:
diff changeset
1852 * vc.el (vc-do-command): Check call-process status.
Dave Love <fx@gnu.org>
parents:
diff changeset
1853 @end group
Dave Love <fx@gnu.org>
parents:
diff changeset
1854 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1855 @iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
1856 @medbreak
Dave Love <fx@gnu.org>
parents:
diff changeset
1857 @end iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
1858
Dave Love <fx@gnu.org>
parents:
diff changeset
1859 When @kbd{C-x v a} adds several change log entries at once, it groups
Dave Love <fx@gnu.org>
parents:
diff changeset
1860 related log entries together if they all are checked in by the same
Dave Love <fx@gnu.org>
parents:
diff changeset
1861 author at nearly the same time. If the log entries for several such
Dave Love <fx@gnu.org>
parents:
diff changeset
1862 files all have the same text, it coalesces them into a single entry.
Dave Love <fx@gnu.org>
parents:
diff changeset
1863 For example, suppose the most recent check-ins have the following log
Dave Love <fx@gnu.org>
parents:
diff changeset
1864 entries:
Dave Love <fx@gnu.org>
parents:
diff changeset
1865
Dave Love <fx@gnu.org>
parents:
diff changeset
1866 @flushleft
Dave Love <fx@gnu.org>
parents:
diff changeset
1867 @bullet{} For @file{vc.texinfo}: @samp{Fix expansion typos.}
Dave Love <fx@gnu.org>
parents:
diff changeset
1868 @bullet{} For @file{vc.el}: @samp{Don't call expand-file-name.}
Dave Love <fx@gnu.org>
parents:
diff changeset
1869 @bullet{} For @file{vc-hooks.el}: @samp{Don't call expand-file-name.}
Dave Love <fx@gnu.org>
parents:
diff changeset
1870 @end flushleft
Dave Love <fx@gnu.org>
parents:
diff changeset
1871
Dave Love <fx@gnu.org>
parents:
diff changeset
1872 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
1873 They appear like this in @file{ChangeLog}:
Dave Love <fx@gnu.org>
parents:
diff changeset
1874
Dave Love <fx@gnu.org>
parents:
diff changeset
1875 @iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
1876 @medbreak
Dave Love <fx@gnu.org>
parents:
diff changeset
1877 @end iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
1878 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1879 @group
Dave Love <fx@gnu.org>
parents:
diff changeset
1880 1999-04-01 Nathaniel Bowditch <nat@@apn.org>
Dave Love <fx@gnu.org>
parents:
diff changeset
1881
Dave Love <fx@gnu.org>
parents:
diff changeset
1882 * vc.texinfo: Fix expansion typos.
Dave Love <fx@gnu.org>
parents:
diff changeset
1883
Dave Love <fx@gnu.org>
parents:
diff changeset
1884 * vc.el, vc-hooks.el: Don't call expand-file-name.
Dave Love <fx@gnu.org>
parents:
diff changeset
1885 @end group
Dave Love <fx@gnu.org>
parents:
diff changeset
1886 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1887 @iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
1888 @medbreak
Dave Love <fx@gnu.org>
parents:
diff changeset
1889 @end iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
1890
Dave Love <fx@gnu.org>
parents:
diff changeset
1891 Normally, @kbd{C-x v a} separates log entries by a blank line, but you
Dave Love <fx@gnu.org>
parents:
diff changeset
1892 can mark several related log entries to be clumped together (without an
Dave Love <fx@gnu.org>
parents:
diff changeset
1893 intervening blank line) by starting the text of each related log entry
Dave Love <fx@gnu.org>
parents:
diff changeset
1894 with a label of the form @w{@samp{@{@var{clumpname}@} }}. The label
Dave Love <fx@gnu.org>
parents:
diff changeset
1895 itself is not copied to @file{ChangeLog}. For example, suppose the log
Dave Love <fx@gnu.org>
parents:
diff changeset
1896 entries are:
Dave Love <fx@gnu.org>
parents:
diff changeset
1897
Dave Love <fx@gnu.org>
parents:
diff changeset
1898 @flushleft
Dave Love <fx@gnu.org>
parents:
diff changeset
1899 @bullet{} For @file{vc.texinfo}: @samp{@{expand@} Fix expansion typos.}
Dave Love <fx@gnu.org>
parents:
diff changeset
1900 @bullet{} For @file{vc.el}: @samp{@{expand@} Don't call expand-file-name.}
Dave Love <fx@gnu.org>
parents:
diff changeset
1901 @bullet{} For @file{vc-hooks.el}: @samp{@{expand@} Don't call expand-file-name.}
Dave Love <fx@gnu.org>
parents:
diff changeset
1902 @end flushleft
Dave Love <fx@gnu.org>
parents:
diff changeset
1903
Dave Love <fx@gnu.org>
parents:
diff changeset
1904 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
1905 Then the text in @file{ChangeLog} looks like this:
Dave Love <fx@gnu.org>
parents:
diff changeset
1906
Dave Love <fx@gnu.org>
parents:
diff changeset
1907 @iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
1908 @medbreak
Dave Love <fx@gnu.org>
parents:
diff changeset
1909 @end iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
1910 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1911 @group
Dave Love <fx@gnu.org>
parents:
diff changeset
1912 1999-04-01 Nathaniel Bowditch <nat@@apn.org>
Dave Love <fx@gnu.org>
parents:
diff changeset
1913
Dave Love <fx@gnu.org>
parents:
diff changeset
1914 * vc.texinfo: Fix expansion typos.
Dave Love <fx@gnu.org>
parents:
diff changeset
1915 * vc.el, vc-hooks.el: Don't call expand-file-name.
Dave Love <fx@gnu.org>
parents:
diff changeset
1916 @end group
Dave Love <fx@gnu.org>
parents:
diff changeset
1917 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
1918 @iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
1919 @medbreak
Dave Love <fx@gnu.org>
parents:
diff changeset
1920 @end iftex
Dave Love <fx@gnu.org>
parents:
diff changeset
1921
Dave Love <fx@gnu.org>
parents:
diff changeset
1922 A log entry whose text begins with @samp{#} is not copied to
Dave Love <fx@gnu.org>
parents:
diff changeset
1923 @file{ChangeLog}. For example, if you merely fix some misspellings in
Dave Love <fx@gnu.org>
parents:
diff changeset
1924 comments, you can log the change with an entry beginning with @samp{#}
Dave Love <fx@gnu.org>
parents:
diff changeset
1925 to avoid putting such trivia into @file{ChangeLog}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1926
Dave Love <fx@gnu.org>
parents:
diff changeset
1927 @node Renaming and VC
Dave Love <fx@gnu.org>
parents:
diff changeset
1928 @subsubsection Renaming VC Work Files and Master Files
Dave Love <fx@gnu.org>
parents:
diff changeset
1929
Dave Love <fx@gnu.org>
parents:
diff changeset
1930 @findex vc-rename-file
Dave Love <fx@gnu.org>
parents:
diff changeset
1931 When you rename a registered file, you must also rename its master
Dave Love <fx@gnu.org>
parents:
diff changeset
1932 file correspondingly to get proper results. Use @code{vc-rename-file}
Dave Love <fx@gnu.org>
parents:
diff changeset
1933 to rename the source file as you specify, and rename its master file
Dave Love <fx@gnu.org>
parents:
diff changeset
1934 accordingly. It also updates any snapshots (@pxref{Snapshots}) that
Dave Love <fx@gnu.org>
parents:
diff changeset
1935 mention the file, so that they use the new name; despite this, the
Dave Love <fx@gnu.org>
parents:
diff changeset
1936 snapshot thus modified may not completely work (@pxref{Snapshot
Dave Love <fx@gnu.org>
parents:
diff changeset
1937 Caveats}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1938
Dave Love <fx@gnu.org>
parents:
diff changeset
1939 You cannot use @code{vc-rename-file} on a file that is locked by
Dave Love <fx@gnu.org>
parents:
diff changeset
1940 someone else.
Dave Love <fx@gnu.org>
parents:
diff changeset
1941
Dave Love <fx@gnu.org>
parents:
diff changeset
1942 @node Version Headers
Dave Love <fx@gnu.org>
parents:
diff changeset
1943 @subsubsection Inserting Version Control Headers
Dave Love <fx@gnu.org>
parents:
diff changeset
1944
Dave Love <fx@gnu.org>
parents:
diff changeset
1945 Sometimes it is convenient to put version identification strings
Dave Love <fx@gnu.org>
parents:
diff changeset
1946 directly into working files. Certain special strings called
Dave Love <fx@gnu.org>
parents:
diff changeset
1947 @dfn{version headers} are replaced in each successive version by the
Dave Love <fx@gnu.org>
parents:
diff changeset
1948 number of that version.
Dave Love <fx@gnu.org>
parents:
diff changeset
1949
Dave Love <fx@gnu.org>
parents:
diff changeset
1950 If you are using RCS, and version headers are present in your working
Dave Love <fx@gnu.org>
parents:
diff changeset
1951 files, Emacs can use them to determine the current version and the
Dave Love <fx@gnu.org>
parents:
diff changeset
1952 locking state of the files. This is more reliable than referring to the
Dave Love <fx@gnu.org>
parents:
diff changeset
1953 master files, which is done when there are no version headers. Note
Dave Love <fx@gnu.org>
parents:
diff changeset
1954 that in a multi-branch environment, version headers are necessary to
Dave Love <fx@gnu.org>
parents:
diff changeset
1955 make VC behave correctly (@pxref{Multi-User Branching}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1956
Dave Love <fx@gnu.org>
parents:
diff changeset
1957 Searching for version headers is controlled by the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
1958 @code{vc-consult-headers}. If it is non-@code{nil}, Emacs searches for
Dave Love <fx@gnu.org>
parents:
diff changeset
1959 headers to determine the version number you are editing. Setting it to
Dave Love <fx@gnu.org>
parents:
diff changeset
1960 @code{nil} disables this feature.
Dave Love <fx@gnu.org>
parents:
diff changeset
1961
Dave Love <fx@gnu.org>
parents:
diff changeset
1962 @kindex C-x v h
Dave Love <fx@gnu.org>
parents:
diff changeset
1963 @findex vc-insert-headers
Dave Love <fx@gnu.org>
parents:
diff changeset
1964 You can use the @kbd{C-x v h} command (@code{vc-insert-headers}) to
Dave Love <fx@gnu.org>
parents:
diff changeset
1965 insert a suitable header string.
Dave Love <fx@gnu.org>
parents:
diff changeset
1966
Dave Love <fx@gnu.org>
parents:
diff changeset
1967 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
1968 @item C-x v h
Dave Love <fx@gnu.org>
parents:
diff changeset
1969 Insert headers in a file for use with your version-control system.
Dave Love <fx@gnu.org>
parents:
diff changeset
1970 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1971
Dave Love <fx@gnu.org>
parents:
diff changeset
1972 @vindex vc-header-alist
Dave Love <fx@gnu.org>
parents:
diff changeset
1973 The default header string is @samp{@w{$}Id$} for RCS and
Dave Love <fx@gnu.org>
parents:
diff changeset
1974 @samp{@w{%}W%} for SCCS. You can specify other headers to insert by
Dave Love <fx@gnu.org>
parents:
diff changeset
1975 setting the variable @code{vc-header-alist}. Its value is a list of
Dave Love <fx@gnu.org>
parents:
diff changeset
1976 elements of the form @code{(@var{program} . @var{string})} where
Dave Love <fx@gnu.org>
parents:
diff changeset
1977 @var{program} is @code{RCS} or @code{SCCS} and @var{string} is the
Dave Love <fx@gnu.org>
parents:
diff changeset
1978 string to use.
Dave Love <fx@gnu.org>
parents:
diff changeset
1979
Dave Love <fx@gnu.org>
parents:
diff changeset
1980 Instead of a single string, you can specify a list of strings; then
Dave Love <fx@gnu.org>
parents:
diff changeset
1981 each string in the list is inserted as a separate header on a line of
Dave Love <fx@gnu.org>
parents:
diff changeset
1982 its own.
Dave Love <fx@gnu.org>
parents:
diff changeset
1983
Dave Love <fx@gnu.org>
parents:
diff changeset
1984 It is often necessary to use ``superfluous'' backslashes when writing
Dave Love <fx@gnu.org>
parents:
diff changeset
1985 the strings that you put in this variable. This is to prevent the
Dave Love <fx@gnu.org>
parents:
diff changeset
1986 string in the constant from being interpreted as a header itself if the
Dave Love <fx@gnu.org>
parents:
diff changeset
1987 Emacs Lisp file containing it is maintained with version control.
Dave Love <fx@gnu.org>
parents:
diff changeset
1988
Dave Love <fx@gnu.org>
parents:
diff changeset
1989 @vindex vc-comment-alist
Dave Love <fx@gnu.org>
parents:
diff changeset
1990 Each header is inserted surrounded by tabs, inside comment delimiters,
Dave Love <fx@gnu.org>
parents:
diff changeset
1991 on a new line at point. Normally the ordinary comment
Dave Love <fx@gnu.org>
parents:
diff changeset
1992 start and comment end strings of the current mode are used, but for
Dave Love <fx@gnu.org>
parents:
diff changeset
1993 certain modes, there are special comment delimiters for this purpose;
Dave Love <fx@gnu.org>
parents:
diff changeset
1994 the variable @code{vc-comment-alist} specifies them. Each element of
Dave Love <fx@gnu.org>
parents:
diff changeset
1995 this list has the form @code{(@var{mode} @var{starter} @var{ender})}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1996
Dave Love <fx@gnu.org>
parents:
diff changeset
1997 @vindex vc-static-header-alist
Dave Love <fx@gnu.org>
parents:
diff changeset
1998 The variable @code{vc-static-header-alist} specifies further strings
Dave Love <fx@gnu.org>
parents:
diff changeset
1999 to add based on the name of the buffer. Its value should be a list of
Dave Love <fx@gnu.org>
parents:
diff changeset
2000 elements of the form @code{(@var{regexp} . @var{format})}. Whenever
Dave Love <fx@gnu.org>
parents:
diff changeset
2001 @var{regexp} matches the buffer name, @var{format} is inserted as part
Dave Love <fx@gnu.org>
parents:
diff changeset
2002 of the header. A header line is inserted for each element that matches
Dave Love <fx@gnu.org>
parents:
diff changeset
2003 the buffer name, and for each string specified by
Dave Love <fx@gnu.org>
parents:
diff changeset
2004 @code{vc-header-alist}. The header line is made by processing the
Dave Love <fx@gnu.org>
parents:
diff changeset
2005 string from @code{vc-header-alist} with the format taken from the
Dave Love <fx@gnu.org>
parents:
diff changeset
2006 element. The default value for @code{vc-static-header-alist} is as follows:
Dave Love <fx@gnu.org>
parents:
diff changeset
2007
Dave Love <fx@gnu.org>
parents:
diff changeset
2008 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2009 @group
Dave Love <fx@gnu.org>
parents:
diff changeset
2010 (("\\.c$" .
Dave Love <fx@gnu.org>
parents:
diff changeset
2011 "\n#ifndef lint\nstatic char vcid[] = \"\%s\";\n\
Dave Love <fx@gnu.org>
parents:
diff changeset
2012 #endif /* lint */\n"))
Dave Love <fx@gnu.org>
parents:
diff changeset
2013 @end group
Dave Love <fx@gnu.org>
parents:
diff changeset
2014 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2015
Dave Love <fx@gnu.org>
parents:
diff changeset
2016 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
2017 It specifies insertion of text of this form:
Dave Love <fx@gnu.org>
parents:
diff changeset
2018
Dave Love <fx@gnu.org>
parents:
diff changeset
2019 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2020 @group
Dave Love <fx@gnu.org>
parents:
diff changeset
2021
Dave Love <fx@gnu.org>
parents:
diff changeset
2022 #ifndef lint
Dave Love <fx@gnu.org>
parents:
diff changeset
2023 static char vcid[] = "@var{string}";
Dave Love <fx@gnu.org>
parents:
diff changeset
2024 #endif /* lint */
Dave Love <fx@gnu.org>
parents:
diff changeset
2025 @end group
Dave Love <fx@gnu.org>
parents:
diff changeset
2026 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2027
Dave Love <fx@gnu.org>
parents:
diff changeset
2028 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
2029 Note that the text above starts with a blank line.
Dave Love <fx@gnu.org>
parents:
diff changeset
2030
Dave Love <fx@gnu.org>
parents:
diff changeset
2031 If you use more than one version header in a file, put them close
Dave Love <fx@gnu.org>
parents:
diff changeset
2032 together in the file. The mechanism in @code{revert-buffer} that
Dave Love <fx@gnu.org>
parents:
diff changeset
2033 preserves markers may not handle markers positioned between two version
Dave Love <fx@gnu.org>
parents:
diff changeset
2034 headers.
Dave Love <fx@gnu.org>
parents:
diff changeset
2035
Dave Love <fx@gnu.org>
parents:
diff changeset
2036 @node Customizing VC
Dave Love <fx@gnu.org>
parents:
diff changeset
2037 @subsection Customizing VC
Dave Love <fx@gnu.org>
parents:
diff changeset
2038
Dave Love <fx@gnu.org>
parents:
diff changeset
2039 There are many ways of customizing VC. The options you can set fall
Dave Love <fx@gnu.org>
parents:
diff changeset
2040 into four categories, described in the following sections.
Dave Love <fx@gnu.org>
parents:
diff changeset
2041
26105
c881de80a22b Mention vc-ignore-vc-files.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2042 @vindex vc-ignore-vc-files
c881de80a22b Mention vc-ignore-vc-files.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2043 @cindex Version control, deactivating
c881de80a22b Mention vc-ignore-vc-files.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2044 In addition, it is possible to turn VC on and off generally by setting
c881de80a22b Mention vc-ignore-vc-files.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2045 the variable @code{vc-ignore-vc-files}. Normally VC will notice the
c881de80a22b Mention vc-ignore-vc-files.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2046 presence of version control on a file you visit and automatically invoke
c881de80a22b Mention vc-ignore-vc-files.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2047 the relevant program to check the file's state. Change
c881de80a22b Mention vc-ignore-vc-files.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2048 @code{vc-ignore-vc-files} if this isn't the right thing, for instance,
c881de80a22b Mention vc-ignore-vc-files.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2049 if you edit files under version control but don't have the relevant
c881de80a22b Mention vc-ignore-vc-files.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2050 version control programs available.
c881de80a22b Mention vc-ignore-vc-files.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2051
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2052 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
2053 * Backend Options:: Customizing the back-end to your needs.
Dave Love <fx@gnu.org>
parents:
diff changeset
2054 * VC Workfile Handling:: Various options concerning working files.
Dave Love <fx@gnu.org>
parents:
diff changeset
2055 * VC Status Retrieval:: How VC finds the version control status of a file,
Dave Love <fx@gnu.org>
parents:
diff changeset
2056 and how to customize this.
Dave Love <fx@gnu.org>
parents:
diff changeset
2057 * VC Command Execution:: Which commands VC should run, and how.
Dave Love <fx@gnu.org>
parents:
diff changeset
2058 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
2059
Dave Love <fx@gnu.org>
parents:
diff changeset
2060 @node Backend Options
Dave Love <fx@gnu.org>
parents:
diff changeset
2061 @subsubsection Options for VC Backends
Dave Love <fx@gnu.org>
parents:
diff changeset
2062
Dave Love <fx@gnu.org>
parents:
diff changeset
2063 @cindex backend options (VC)
Dave Love <fx@gnu.org>
parents:
diff changeset
2064 @cindex locking under version control
Dave Love <fx@gnu.org>
parents:
diff changeset
2065 You can tell RCS and CVS whether to use locking for a file or not
Dave Love <fx@gnu.org>
parents:
diff changeset
2066 (@pxref{VC Concepts}, for a description of locking). VC automatically
Dave Love <fx@gnu.org>
parents:
diff changeset
2067 recognizes what you have chosen, and behaves accordingly.
Dave Love <fx@gnu.org>
parents:
diff changeset
2068
Dave Love <fx@gnu.org>
parents:
diff changeset
2069 @cindex non-strict locking (RCS)
Dave Love <fx@gnu.org>
parents:
diff changeset
2070 @cindex locking, non-strict (RCS)
Dave Love <fx@gnu.org>
parents:
diff changeset
2071 For RCS, the default is to use locking, but there is a mode called
Dave Love <fx@gnu.org>
parents:
diff changeset
2072 @dfn{non-strict locking} in which you can check-in changes without
Dave Love <fx@gnu.org>
parents:
diff changeset
2073 locking the file first. Use @samp{rcs -U} to switch to non-strict
Dave Love <fx@gnu.org>
parents:
diff changeset
2074 locking for a particular file, see the @samp{rcs} manpage for details.
Dave Love <fx@gnu.org>
parents:
diff changeset
2075
Dave Love <fx@gnu.org>
parents:
diff changeset
2076 @cindex locking (CVS)
Dave Love <fx@gnu.org>
parents:
diff changeset
2077 Under CVS, the default is not to use locking; anyone can change a work
Dave Love <fx@gnu.org>
parents:
diff changeset
2078 file at any time. However, there are ways to restrict this, resulting
Dave Love <fx@gnu.org>
parents:
diff changeset
2079 in behavior that resembles locking.
Dave Love <fx@gnu.org>
parents:
diff changeset
2080
Dave Love <fx@gnu.org>
parents:
diff changeset
2081 @cindex CVSREAD environment variable (CVS)
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 28671
diff changeset
2082 For one thing, you can set the @env{CVSREAD} environment variable to
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2083 an arbitrary value. If this variable is defined, CVS makes your work
Dave Love <fx@gnu.org>
parents:
diff changeset
2084 files read-only by default. In Emacs, you must type @kbd{C-x C-q} to
Dave Love <fx@gnu.org>
parents:
diff changeset
2085 make the file writeable, so that editing works in fact similar as if
Dave Love <fx@gnu.org>
parents:
diff changeset
2086 locking was used. Note however, that no actual locking is performed, so
Dave Love <fx@gnu.org>
parents:
diff changeset
2087 several users can make their files writeable at the same time. When
29107
203ba1f77b7b *** empty log message ***
Gerd Moellmann <gerd@gnu.org>
parents: 28671
diff changeset
2088 setting @env{CVSREAD} for the first time, make sure to check out all
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2089 your modules anew, so that the file protections are set correctly.
Dave Love <fx@gnu.org>
parents:
diff changeset
2090
Dave Love <fx@gnu.org>
parents:
diff changeset
2091 @cindex cvs watch feature
Dave Love <fx@gnu.org>
parents:
diff changeset
2092 @cindex watching files (CVS)
Dave Love <fx@gnu.org>
parents:
diff changeset
2093 Another way to achieve something similar to locking is to use the
Dave Love <fx@gnu.org>
parents:
diff changeset
2094 @dfn{watch} feature of CVS. If a file is being watched, CVS makes it
Dave Love <fx@gnu.org>
parents:
diff changeset
2095 read-only by default, and you must also use @kbd{C-x C-q} in Emacs to
Dave Love <fx@gnu.org>
parents:
diff changeset
2096 make it writable. VC calls @code{cvs edit} to make the file writeable,
Dave Love <fx@gnu.org>
parents:
diff changeset
2097 and CVS takes care to notify other developers of the fact that you
Dave Love <fx@gnu.org>
parents:
diff changeset
2098 intend to change the file. See the CVS documentation for details on
Dave Love <fx@gnu.org>
parents:
diff changeset
2099 using the watch feature.
Dave Love <fx@gnu.org>
parents:
diff changeset
2100
Dave Love <fx@gnu.org>
parents:
diff changeset
2101 @vindex vc-handle-cvs
Dave Love <fx@gnu.org>
parents:
diff changeset
2102 You can turn off use of VC for CVS-managed files by setting the
Dave Love <fx@gnu.org>
parents:
diff changeset
2103 variable @code{vc-handle-cvs} to @code{nil}. If you do this, Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
2104 treats these files as if they were not registered, and the VC commands
Dave Love <fx@gnu.org>
parents:
diff changeset
2105 are not available for them. You must do all CVS operations manually.
Dave Love <fx@gnu.org>
parents:
diff changeset
2106
Dave Love <fx@gnu.org>
parents:
diff changeset
2107 @node VC Workfile Handling
Dave Love <fx@gnu.org>
parents:
diff changeset
2108 @subsubsection VC Workfile Handling
Dave Love <fx@gnu.org>
parents:
diff changeset
2109
Dave Love <fx@gnu.org>
parents:
diff changeset
2110 @vindex vc-make-backup-files
Dave Love <fx@gnu.org>
parents:
diff changeset
2111 Emacs normally does not save backup files for source files that are
Dave Love <fx@gnu.org>
parents:
diff changeset
2112 maintained with version control. If you want to make backup files even
Dave Love <fx@gnu.org>
parents:
diff changeset
2113 for files that use version control, set the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
2114 @code{vc-make-backup-files} to a non-@code{nil} value.
Dave Love <fx@gnu.org>
parents:
diff changeset
2115
Dave Love <fx@gnu.org>
parents:
diff changeset
2116 @vindex vc-keep-workfiles
Dave Love <fx@gnu.org>
parents:
diff changeset
2117 Normally the work file exists all the time, whether it is locked or
Dave Love <fx@gnu.org>
parents:
diff changeset
2118 not. If you set @code{vc-keep-workfiles} to @code{nil}, then checking
Dave Love <fx@gnu.org>
parents:
diff changeset
2119 in a new version with @kbd{C-x C-q} deletes the work file; but any
Dave Love <fx@gnu.org>
parents:
diff changeset
2120 attempt to visit the file with Emacs creates it again. (With CVS, work
Dave Love <fx@gnu.org>
parents:
diff changeset
2121 files are always kept.)
Dave Love <fx@gnu.org>
parents:
diff changeset
2122
Dave Love <fx@gnu.org>
parents:
diff changeset
2123 @vindex vc-follow-symlinks
Dave Love <fx@gnu.org>
parents:
diff changeset
2124 Editing a version-controlled file through a symbolic link can be
Dave Love <fx@gnu.org>
parents:
diff changeset
2125 dangerous. It bypasses the version control system---you can edit the
Dave Love <fx@gnu.org>
parents:
diff changeset
2126 file without locking it, and fail to check your changes in. Also,
Dave Love <fx@gnu.org>
parents:
diff changeset
2127 your changes might overwrite those of another user. To protect against
Dave Love <fx@gnu.org>
parents:
diff changeset
2128 this, VC checks each symbolic link that you visit, to see if it points
Dave Love <fx@gnu.org>
parents:
diff changeset
2129 to a file under version control.
Dave Love <fx@gnu.org>
parents:
diff changeset
2130
Dave Love <fx@gnu.org>
parents:
diff changeset
2131 The variable @code{vc-follow-symlinks} controls what to do when a
Dave Love <fx@gnu.org>
parents:
diff changeset
2132 symbolic link points to a version-controlled file. If it is @code{nil},
Dave Love <fx@gnu.org>
parents:
diff changeset
2133 VC only displays a warning message. If it is @code{t}, VC automatically
Dave Love <fx@gnu.org>
parents:
diff changeset
2134 follows the link, and visits the real file instead, telling you about
Dave Love <fx@gnu.org>
parents:
diff changeset
2135 this in the echo area. If the value is @code{ask} (the default), VC
Dave Love <fx@gnu.org>
parents:
diff changeset
2136 asks you each time whether to follow the link.
Dave Love <fx@gnu.org>
parents:
diff changeset
2137
Dave Love <fx@gnu.org>
parents:
diff changeset
2138 @node VC Status Retrieval
Dave Love <fx@gnu.org>
parents:
diff changeset
2139 @subsubsection VC Status Retrieval
Dave Love <fx@gnu.org>
parents:
diff changeset
2140 @c There is no need to tell users about vc-master-templates.
Dave Love <fx@gnu.org>
parents:
diff changeset
2141
Dave Love <fx@gnu.org>
parents:
diff changeset
2142 When deducing the locked/unlocked state of a file, VC first looks for
Dave Love <fx@gnu.org>
parents:
diff changeset
2143 an RCS version header string in the file (@pxref{Version Headers}). If
Dave Love <fx@gnu.org>
parents:
diff changeset
2144 there is no header string, or if you are using SCCS, VC normally looks
Dave Love <fx@gnu.org>
parents:
diff changeset
2145 at the file permissions of the work file; this is fast. But there might
Dave Love <fx@gnu.org>
parents:
diff changeset
2146 be situations when the file permissions cannot be trusted. In this case
Dave Love <fx@gnu.org>
parents:
diff changeset
2147 the master file has to be consulted, which is rather expensive. Also
Dave Love <fx@gnu.org>
parents:
diff changeset
2148 the master file can only tell you @emph{if} there's any lock on the
Dave Love <fx@gnu.org>
parents:
diff changeset
2149 file, but not whether your work file really contains that locked
Dave Love <fx@gnu.org>
parents:
diff changeset
2150 version.
Dave Love <fx@gnu.org>
parents:
diff changeset
2151
Dave Love <fx@gnu.org>
parents:
diff changeset
2152 @vindex vc-consult-headers
Dave Love <fx@gnu.org>
parents:
diff changeset
2153 You can tell VC not to use version headers to determine lock status by
Dave Love <fx@gnu.org>
parents:
diff changeset
2154 setting @code{vc-consult-headers} to @code{nil}. VC then always uses
Dave Love <fx@gnu.org>
parents:
diff changeset
2155 the file permissions (if it can trust them), or else checks the master
Dave Love <fx@gnu.org>
parents:
diff changeset
2156 file.
Dave Love <fx@gnu.org>
parents:
diff changeset
2157
Dave Love <fx@gnu.org>
parents:
diff changeset
2158 @vindex vc-mistrust-permissions
Dave Love <fx@gnu.org>
parents:
diff changeset
2159 You can specify the criterion for whether to trust the file
Dave Love <fx@gnu.org>
parents:
diff changeset
2160 permissions by setting the variable @code{vc-mistrust-permissions}. Its
Dave Love <fx@gnu.org>
parents:
diff changeset
2161 value can be @code{t} (always mistrust the file permissions and check
Dave Love <fx@gnu.org>
parents:
diff changeset
2162 the master file), @code{nil} (always trust the file permissions), or a
Dave Love <fx@gnu.org>
parents:
diff changeset
2163 function of one argument which makes the decision. The argument is the
Dave Love <fx@gnu.org>
parents:
diff changeset
2164 directory name of the @file{RCS}, @file{CVS} or @file{SCCS}
Dave Love <fx@gnu.org>
parents:
diff changeset
2165 subdirectory. A non-@code{nil} value from the function says to mistrust
Dave Love <fx@gnu.org>
parents:
diff changeset
2166 the file permissions. If you find that the file permissions of work
Dave Love <fx@gnu.org>
parents:
diff changeset
2167 files are changed erroneously, set @code{vc-mistrust-permissions} to
Dave Love <fx@gnu.org>
parents:
diff changeset
2168 @code{t}. Then VC always checks the master file to determine the file's
Dave Love <fx@gnu.org>
parents:
diff changeset
2169 status.
Dave Love <fx@gnu.org>
parents:
diff changeset
2170
Dave Love <fx@gnu.org>
parents:
diff changeset
2171 @node VC Command Execution
Dave Love <fx@gnu.org>
parents:
diff changeset
2172 @subsubsection VC Command Execution
Dave Love <fx@gnu.org>
parents:
diff changeset
2173
Dave Love <fx@gnu.org>
parents:
diff changeset
2174 @vindex vc-suppress-confirm
Dave Love <fx@gnu.org>
parents:
diff changeset
2175 If @code{vc-suppress-confirm} is non-@code{nil}, then @kbd{C-x C-q}
Dave Love <fx@gnu.org>
parents:
diff changeset
2176 and @kbd{C-x v i} can save the current buffer without asking, and
Dave Love <fx@gnu.org>
parents:
diff changeset
2177 @kbd{C-x v u} also operates without asking for confirmation. (This
Dave Love <fx@gnu.org>
parents:
diff changeset
2178 variable does not affect @kbd{C-x v c}; that operation is so drastic
Dave Love <fx@gnu.org>
parents:
diff changeset
2179 that it should always ask for confirmation.)
Dave Love <fx@gnu.org>
parents:
diff changeset
2180
Dave Love <fx@gnu.org>
parents:
diff changeset
2181 @vindex vc-command-messages
Dave Love <fx@gnu.org>
parents:
diff changeset
2182 VC mode does much of its work by running the shell commands for RCS,
Dave Love <fx@gnu.org>
parents:
diff changeset
2183 CVS and SCCS. If @code{vc-command-messages} is non-@code{nil}, VC
Dave Love <fx@gnu.org>
parents:
diff changeset
2184 displays messages to indicate which shell commands it runs, and
Dave Love <fx@gnu.org>
parents:
diff changeset
2185 additional messages when the commands finish.
Dave Love <fx@gnu.org>
parents:
diff changeset
2186
Dave Love <fx@gnu.org>
parents:
diff changeset
2187 @vindex vc-path
Dave Love <fx@gnu.org>
parents:
diff changeset
2188 You can specify additional directories to search for version control
Dave Love <fx@gnu.org>
parents:
diff changeset
2189 programs by setting the variable @code{vc-path}. These directories are
Dave Love <fx@gnu.org>
parents:
diff changeset
2190 searched before the usual search path. But the proper files are usually
Dave Love <fx@gnu.org>
parents:
diff changeset
2191 found automatically.
Dave Love <fx@gnu.org>
parents:
diff changeset
2192
Dave Love <fx@gnu.org>
parents:
diff changeset
2193 @node Directories
Dave Love <fx@gnu.org>
parents:
diff changeset
2194 @section File Directories
Dave Love <fx@gnu.org>
parents:
diff changeset
2195
Dave Love <fx@gnu.org>
parents:
diff changeset
2196 @cindex file directory
Dave Love <fx@gnu.org>
parents:
diff changeset
2197 @cindex directory listing
Dave Love <fx@gnu.org>
parents:
diff changeset
2198 The file system groups files into @dfn{directories}. A @dfn{directory
Dave Love <fx@gnu.org>
parents:
diff changeset
2199 listing} is a list of all the files in a directory. Emacs provides
Dave Love <fx@gnu.org>
parents:
diff changeset
2200 commands to create and delete directories, and to make directory
Dave Love <fx@gnu.org>
parents:
diff changeset
2201 listings in brief format (file names only) and verbose format (sizes,
Dave Love <fx@gnu.org>
parents:
diff changeset
2202 dates, and authors included). There is also a directory browser called
Dave Love <fx@gnu.org>
parents:
diff changeset
2203 Dired; see @ref{Dired}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2204
Dave Love <fx@gnu.org>
parents:
diff changeset
2205 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
2206 @item C-x C-d @var{dir-or-pattern} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
2207 Display a brief directory listing (@code{list-directory}).
Dave Love <fx@gnu.org>
parents:
diff changeset
2208 @item C-u C-x C-d @var{dir-or-pattern} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
2209 Display a verbose directory listing.
Dave Love <fx@gnu.org>
parents:
diff changeset
2210 @item M-x make-directory @key{RET} @var{dirname} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
2211 Create a new directory named @var{dirname}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2212 @item M-x delete-directory @key{RET} @var{dirname} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
2213 Delete the directory named @var{dirname}. It must be empty,
Dave Love <fx@gnu.org>
parents:
diff changeset
2214 or you get an error.
Dave Love <fx@gnu.org>
parents:
diff changeset
2215 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
2216
Dave Love <fx@gnu.org>
parents:
diff changeset
2217 @findex list-directory
Dave Love <fx@gnu.org>
parents:
diff changeset
2218 @kindex C-x C-d
Dave Love <fx@gnu.org>
parents:
diff changeset
2219 The command to display a directory listing is @kbd{C-x C-d}
Dave Love <fx@gnu.org>
parents:
diff changeset
2220 (@code{list-directory}). It reads using the minibuffer a file name
Dave Love <fx@gnu.org>
parents:
diff changeset
2221 which is either a directory to be listed or a wildcard-containing
Dave Love <fx@gnu.org>
parents:
diff changeset
2222 pattern for the files to be listed. For example,
Dave Love <fx@gnu.org>
parents:
diff changeset
2223
Dave Love <fx@gnu.org>
parents:
diff changeset
2224 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2225 C-x C-d /u2/emacs/etc @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
2226 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2227
Dave Love <fx@gnu.org>
parents:
diff changeset
2228 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
2229 lists all the files in directory @file{/u2/emacs/etc}. Here is an
Dave Love <fx@gnu.org>
parents:
diff changeset
2230 example of specifying a file name pattern:
Dave Love <fx@gnu.org>
parents:
diff changeset
2231
Dave Love <fx@gnu.org>
parents:
diff changeset
2232 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2233 C-x C-d /u2/emacs/src/*.c @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
2234 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2235
Dave Love <fx@gnu.org>
parents:
diff changeset
2236 Normally, @kbd{C-x C-d} prints a brief directory listing containing
Dave Love <fx@gnu.org>
parents:
diff changeset
2237 just file names. A numeric argument (regardless of value) tells it to
Dave Love <fx@gnu.org>
parents:
diff changeset
2238 make a verbose listing including sizes, dates, and authors (like
Dave Love <fx@gnu.org>
parents:
diff changeset
2239 @samp{ls -l}).
Dave Love <fx@gnu.org>
parents:
diff changeset
2240
Dave Love <fx@gnu.org>
parents:
diff changeset
2241 @vindex list-directory-brief-switches
Dave Love <fx@gnu.org>
parents:
diff changeset
2242 @vindex list-directory-verbose-switches
Dave Love <fx@gnu.org>
parents:
diff changeset
2243 The text of a directory listing is obtained by running @code{ls} in an
Dave Love <fx@gnu.org>
parents:
diff changeset
2244 inferior process. Two Emacs variables control the switches passed to
Dave Love <fx@gnu.org>
parents:
diff changeset
2245 @code{ls}: @code{list-directory-brief-switches} is a string giving the
Dave Love <fx@gnu.org>
parents:
diff changeset
2246 switches to use in brief listings (@code{"-CF"} by default), and
Dave Love <fx@gnu.org>
parents:
diff changeset
2247 @code{list-directory-verbose-switches} is a string giving the switches to
Dave Love <fx@gnu.org>
parents:
diff changeset
2248 use in a verbose listing (@code{"-l"} by default).
Dave Love <fx@gnu.org>
parents:
diff changeset
2249
Dave Love <fx@gnu.org>
parents:
diff changeset
2250 @node Comparing Files
Dave Love <fx@gnu.org>
parents:
diff changeset
2251 @section Comparing Files
Dave Love <fx@gnu.org>
parents:
diff changeset
2252 @cindex comparing files
Dave Love <fx@gnu.org>
parents:
diff changeset
2253
Dave Love <fx@gnu.org>
parents:
diff changeset
2254 @findex diff
Dave Love <fx@gnu.org>
parents:
diff changeset
2255 @vindex diff-switches
Dave Love <fx@gnu.org>
parents:
diff changeset
2256 The command @kbd{M-x diff} compares two files, displaying the
Dave Love <fx@gnu.org>
parents:
diff changeset
2257 differences in an Emacs buffer named @samp{*Diff*}. It works by running
Dave Love <fx@gnu.org>
parents:
diff changeset
2258 the @code{diff} program, using options taken from the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
2259 @code{diff-switches}, whose value should be a string.
Dave Love <fx@gnu.org>
parents:
diff changeset
2260
Dave Love <fx@gnu.org>
parents:
diff changeset
2261 The buffer @samp{*Diff*} has Compilation mode as its major mode, so
Dave Love <fx@gnu.org>
parents:
diff changeset
2262 you can use @kbd{C-x `} to visit successive changed locations in the two
Dave Love <fx@gnu.org>
parents:
diff changeset
2263 source files. You can also move to a particular hunk of changes and
Dave Love <fx@gnu.org>
parents:
diff changeset
2264 type @key{RET} or @kbd{C-c C-c}, or click @kbd{Mouse-2} on it, to move
Dave Love <fx@gnu.org>
parents:
diff changeset
2265 to the corresponding source location. You can also use the other
Dave Love <fx@gnu.org>
parents:
diff changeset
2266 special commands of Compilation mode: @key{SPC} and @key{DEL} for
Dave Love <fx@gnu.org>
parents:
diff changeset
2267 scrolling, and @kbd{M-p} and @kbd{M-n} for cursor motion.
Dave Love <fx@gnu.org>
parents:
diff changeset
2268 @xref{Compilation}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2269
Dave Love <fx@gnu.org>
parents:
diff changeset
2270 @findex diff-backup
Dave Love <fx@gnu.org>
parents:
diff changeset
2271 The command @kbd{M-x diff-backup} compares a specified file with its most
Dave Love <fx@gnu.org>
parents:
diff changeset
2272 recent backup. If you specify the name of a backup file,
Dave Love <fx@gnu.org>
parents:
diff changeset
2273 @code{diff-backup} compares it with the source file that it is a backup
Dave Love <fx@gnu.org>
parents:
diff changeset
2274 of.
Dave Love <fx@gnu.org>
parents:
diff changeset
2275
Dave Love <fx@gnu.org>
parents:
diff changeset
2276 @findex compare-windows
Dave Love <fx@gnu.org>
parents:
diff changeset
2277 The command @kbd{M-x compare-windows} compares the text in the current
Dave Love <fx@gnu.org>
parents:
diff changeset
2278 window with that in the next window. Comparison starts at point in each
Dave Love <fx@gnu.org>
parents:
diff changeset
2279 window, and each starting position is pushed on the mark ring in its
Dave Love <fx@gnu.org>
parents:
diff changeset
2280 respective buffer. Then point moves forward in each window, a character
Dave Love <fx@gnu.org>
parents:
diff changeset
2281 at a time, until a mismatch between the two windows is reached. Then
Dave Love <fx@gnu.org>
parents:
diff changeset
2282 the command is finished. For more information about windows in Emacs,
Dave Love <fx@gnu.org>
parents:
diff changeset
2283 @ref{Windows}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2284
Dave Love <fx@gnu.org>
parents:
diff changeset
2285 @vindex compare-ignore-case
Dave Love <fx@gnu.org>
parents:
diff changeset
2286 With a numeric argument, @code{compare-windows} ignores changes in
Dave Love <fx@gnu.org>
parents:
diff changeset
2287 whitespace. If the variable @code{compare-ignore-case} is
Dave Love <fx@gnu.org>
parents:
diff changeset
2288 non-@code{nil}, it ignores differences in case as well.
Dave Love <fx@gnu.org>
parents:
diff changeset
2289
Dave Love <fx@gnu.org>
parents:
diff changeset
2290 See also @ref{Emerge}, for convenient facilities for merging two
Dave Love <fx@gnu.org>
parents:
diff changeset
2291 similar files.
Dave Love <fx@gnu.org>
parents:
diff changeset
2292
Dave Love <fx@gnu.org>
parents:
diff changeset
2293 @node Misc File Ops
Dave Love <fx@gnu.org>
parents:
diff changeset
2294 @section Miscellaneous File Operations
Dave Love <fx@gnu.org>
parents:
diff changeset
2295
Dave Love <fx@gnu.org>
parents:
diff changeset
2296 Emacs has commands for performing many other operations on files.
Dave Love <fx@gnu.org>
parents:
diff changeset
2297 All operate on one file; they do not accept wildcard file names.
Dave Love <fx@gnu.org>
parents:
diff changeset
2298
Dave Love <fx@gnu.org>
parents:
diff changeset
2299 @findex view-file
Dave Love <fx@gnu.org>
parents:
diff changeset
2300 @cindex viewing
Dave Love <fx@gnu.org>
parents:
diff changeset
2301 @cindex View mode
Dave Love <fx@gnu.org>
parents:
diff changeset
2302 @cindex mode, View
Dave Love <fx@gnu.org>
parents:
diff changeset
2303 @kbd{M-x view-file} allows you to scan or read a file by sequential
Dave Love <fx@gnu.org>
parents:
diff changeset
2304 screenfuls. It reads a file name argument using the minibuffer. After
Dave Love <fx@gnu.org>
parents:
diff changeset
2305 reading the file into an Emacs buffer, @code{view-file} displays the
Dave Love <fx@gnu.org>
parents:
diff changeset
2306 beginning. You can then type @key{SPC} to scroll forward one windowful,
Dave Love <fx@gnu.org>
parents:
diff changeset
2307 or @key{DEL} to scroll backward. Various other commands are provided
Dave Love <fx@gnu.org>
parents:
diff changeset
2308 for moving around in the file, but none for changing it; type @kbd{?}
Dave Love <fx@gnu.org>
parents:
diff changeset
2309 while viewing for a list of them. They are mostly the same as normal
Dave Love <fx@gnu.org>
parents:
diff changeset
2310 Emacs cursor motion commands. To exit from viewing, type @kbd{q}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2311 The commands for viewing are defined by a special major mode called View
Dave Love <fx@gnu.org>
parents:
diff changeset
2312 mode.
Dave Love <fx@gnu.org>
parents:
diff changeset
2313
Dave Love <fx@gnu.org>
parents:
diff changeset
2314 A related command, @kbd{M-x view-buffer}, views a buffer already present
Dave Love <fx@gnu.org>
parents:
diff changeset
2315 in Emacs. @xref{Misc Buffer}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2316
Dave Love <fx@gnu.org>
parents:
diff changeset
2317 @findex insert-file
Dave Love <fx@gnu.org>
parents:
diff changeset
2318 @kbd{M-x insert-file} inserts a copy of the contents of the specified
Dave Love <fx@gnu.org>
parents:
diff changeset
2319 file into the current buffer at point, leaving point unchanged before the
Dave Love <fx@gnu.org>
parents:
diff changeset
2320 contents and the mark after them.
Dave Love <fx@gnu.org>
parents:
diff changeset
2321
Dave Love <fx@gnu.org>
parents:
diff changeset
2322 @findex write-region
Dave Love <fx@gnu.org>
parents:
diff changeset
2323 @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it
Dave Love <fx@gnu.org>
parents:
diff changeset
2324 copies the contents of the region into the specified file. @kbd{M-x
Dave Love <fx@gnu.org>
parents:
diff changeset
2325 append-to-file} adds the text of the region to the end of the specified
Dave Love <fx@gnu.org>
parents:
diff changeset
2326 file. @xref{Accumulating Text}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2327
Dave Love <fx@gnu.org>
parents:
diff changeset
2328 @findex delete-file
Dave Love <fx@gnu.org>
parents:
diff changeset
2329 @cindex deletion (of files)
Dave Love <fx@gnu.org>
parents:
diff changeset
2330 @kbd{M-x delete-file} deletes the specified file, like the @code{rm}
Dave Love <fx@gnu.org>
parents:
diff changeset
2331 command in the shell. If you are deleting many files in one directory, it
Dave Love <fx@gnu.org>
parents:
diff changeset
2332 may be more convenient to use Dired (@pxref{Dired}).
Dave Love <fx@gnu.org>
parents:
diff changeset
2333
Dave Love <fx@gnu.org>
parents:
diff changeset
2334 @findex rename-file
Dave Love <fx@gnu.org>
parents:
diff changeset
2335 @kbd{M-x rename-file} reads two file names @var{old} and @var{new} using
Dave Love <fx@gnu.org>
parents:
diff changeset
2336 the minibuffer, then renames file @var{old} as @var{new}. If a file named
Dave Love <fx@gnu.org>
parents:
diff changeset
2337 @var{new} already exists, you must confirm with @kbd{yes} or renaming is not
Dave Love <fx@gnu.org>
parents:
diff changeset
2338 done; this is because renaming causes the old meaning of the name @var{new}
Dave Love <fx@gnu.org>
parents:
diff changeset
2339 to be lost. If @var{old} and @var{new} are on different file systems, the
Dave Love <fx@gnu.org>
parents:
diff changeset
2340 file @var{old} is copied and deleted.
Dave Love <fx@gnu.org>
parents:
diff changeset
2341
Dave Love <fx@gnu.org>
parents:
diff changeset
2342 @findex add-name-to-file
Dave Love <fx@gnu.org>
parents:
diff changeset
2343 The similar command @kbd{M-x add-name-to-file} is used to add an
Dave Love <fx@gnu.org>
parents:
diff changeset
2344 additional name to an existing file without removing its old name.
Dave Love <fx@gnu.org>
parents:
diff changeset
2345 The new name must belong on the same file system that the file is on.
Dave Love <fx@gnu.org>
parents:
diff changeset
2346
Dave Love <fx@gnu.org>
parents:
diff changeset
2347 @findex copy-file
Dave Love <fx@gnu.org>
parents:
diff changeset
2348 @cindex copying files
Dave Love <fx@gnu.org>
parents:
diff changeset
2349 @kbd{M-x copy-file} reads the file @var{old} and writes a new file named
Dave Love <fx@gnu.org>
parents:
diff changeset
2350 @var{new} with the same contents. Confirmation is required if a file named
Dave Love <fx@gnu.org>
parents:
diff changeset
2351 @var{new} already exists, because copying has the consequence of overwriting
Dave Love <fx@gnu.org>
parents:
diff changeset
2352 the old contents of the file @var{new}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2353
Dave Love <fx@gnu.org>
parents:
diff changeset
2354 @findex make-symbolic-link
Dave Love <fx@gnu.org>
parents:
diff changeset
2355 @kbd{M-x make-symbolic-link} reads two file names @var{target} and
Dave Love <fx@gnu.org>
parents:
diff changeset
2356 @var{linkname}, then creates a symbolic link named @var{linkname} and
Dave Love <fx@gnu.org>
parents:
diff changeset
2357 pointing at @var{target}. The effect is that future attempts to open file
Dave Love <fx@gnu.org>
parents:
diff changeset
2358 @var{linkname} will refer to whatever file is named @var{target} at the
Dave Love <fx@gnu.org>
parents:
diff changeset
2359 time the opening is done, or will get an error if the name @var{target} is
Dave Love <fx@gnu.org>
parents:
diff changeset
2360 not in use at that time. This command does not expand the argument
Dave Love <fx@gnu.org>
parents:
diff changeset
2361 @var{target}, so that it allows you to specify a relative name
Dave Love <fx@gnu.org>
parents:
diff changeset
2362 as the target of the link.
Dave Love <fx@gnu.org>
parents:
diff changeset
2363
Dave Love <fx@gnu.org>
parents:
diff changeset
2364 Confirmation is required when creating the link if @var{linkname} is
Dave Love <fx@gnu.org>
parents:
diff changeset
2365 in use. Note that not all systems support symbolic links.
Dave Love <fx@gnu.org>
parents:
diff changeset
2366
Dave Love <fx@gnu.org>
parents:
diff changeset
2367 @node Compressed Files
Dave Love <fx@gnu.org>
parents:
diff changeset
2368 @section Accessing Compressed Files
Dave Love <fx@gnu.org>
parents:
diff changeset
2369 @cindex compression
Dave Love <fx@gnu.org>
parents:
diff changeset
2370 @cindex uncompression
Dave Love <fx@gnu.org>
parents:
diff changeset
2371 @cindex Auto Compression mode
Dave Love <fx@gnu.org>
parents:
diff changeset
2372 @cindex mode, Auto Compression
Dave Love <fx@gnu.org>
parents:
diff changeset
2373 @pindex gzip
Dave Love <fx@gnu.org>
parents:
diff changeset
2374
Dave Love <fx@gnu.org>
parents:
diff changeset
2375 @findex auto-compression-mode
28123
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2376 @vindex auto-compression-mode
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2377 Emacs comes with a library that can automatically uncompress
Dave Love <fx@gnu.org>
parents:
diff changeset
2378 compressed files when you visit them, and automatically recompress them
Dave Love <fx@gnu.org>
parents:
diff changeset
2379 if you alter them and save them. To enable this feature, type the
28123
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2380 command @kbd{M-x auto-compression-mode}. You can enable it permanently
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2381 by customizing the option @var{auto-compression-mode}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2382
Dave Love <fx@gnu.org>
parents:
diff changeset
2383 When automatic compression (which implies automatic uncompression as
Dave Love <fx@gnu.org>
parents:
diff changeset
2384 well) is enabled, Emacs recognizes compressed files by their file names.
Dave Love <fx@gnu.org>
parents:
diff changeset
2385 File names ending in @samp{.gz} indicate a file compressed with
Dave Love <fx@gnu.org>
parents:
diff changeset
2386 @code{gzip}. Other endings indicate other compression programs.
Dave Love <fx@gnu.org>
parents:
diff changeset
2387
Dave Love <fx@gnu.org>
parents:
diff changeset
2388 Automatic uncompression and compression apply to all the operations in
Dave Love <fx@gnu.org>
parents:
diff changeset
2389 which Emacs uses the contents of a file. This includes visiting it,
Dave Love <fx@gnu.org>
parents:
diff changeset
2390 saving it, inserting its contents into a buffer, loading it, and byte
Dave Love <fx@gnu.org>
parents:
diff changeset
2391 compiling it.
Dave Love <fx@gnu.org>
parents:
diff changeset
2392
28123
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2393 @node File Archives
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2394 @section File Archives
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2395 @cindex mode, tar
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2396 @cindex Tar mode
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2397 @cindex Archive mode
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2398 @cindex mode, archive
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2399 @cindex @code{arc}
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2400 @cindex @code{jar}
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2401 @cindex @code{zip}
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2402 @cindex @code{lzh}
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2403 @cindex @code{zoo}
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2404 @pindex tar
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2405 @pindex arc
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2406 @pindex jar
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2407 @pindex zip
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2408 @pindex lzh
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2409 @pindex zoo
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2410
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2411 If you visit a file with extension @samp{.tar}, it is assumed to be an
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2412 `archive' made by the @code{tar} program and it is viewed in a Tar mode
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2413 buffer. This provides a Dired-like listing of the contents.
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2414 @xref{Dired}. You can move around the component files as in Dired to
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2415 visit and manipulate them.
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2416
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2417 The keys @kbd{e}, @kbd{f} and @kbd{RET} all extract a component file
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2418 into its own buffer. You can edit it there and when you save the buffer
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2419 the edited version will replace the version in the Tar buffer. @var{v}
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2420 extracts a file into a buffer in View mode. @kbd{d} marks a file for
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2421 deletion when you later use @kbd{x}, as in Dired. @kbd{C} copies a file
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2422 from the archive to disk and @kbd{R} renames a file.
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2423
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2424 Saving the Tar buffer writes a new version of the archive to disk with
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2425 the changes you made to the components.
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2426
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2427 If you enable Auto Compression mode (@pxref{Compressed Files}), then Tar
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2428 mode will be used also for compressed archives in files with extensions
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2429 @samp{.tgz}, @code{.tar.Z} and @code{.tar.gz}.
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2430
28327
f7b17a6af3db (Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents: 28123
diff changeset
2431 It is not necessary to have the @code{tar} program available to use Tar
f7b17a6af3db (Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents: 28123
diff changeset
2432 mode or Archive mode---Emacs reads the archives directly.
f7b17a6af3db (Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents: 28123
diff changeset
2433
28123
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2434 @cindex @code{arc}
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2435 @cindex @code{jar}
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2436 @cindex @code{zip}
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2437 @cindex @code{lzh}
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2438 @cindex @code{zoo}
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2439 @pindex tar
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2440 @pindex arc
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2441 @pindex jar
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2442 @pindex zip
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2443 @pindex lzh
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2444 @pindex zoo
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2445 @cindex Java class archives
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2446 A separate but similar Archive mode, is used for archives produced by
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2447 the programs @code{arc}, @code{zip}, @code{lzh} and @code{zoo} which
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2448 have extensions corresponding to the program names. These archiving
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2449 programs are typically used on MS-DOS and MS-Windows systems. Java
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2450 class archives with extension @samp{.jar} are also recognized. The
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2451 keybindings in Archive mode are similar to those in Tar mode.
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2452
28327
f7b17a6af3db (Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents: 28123
diff changeset
2453 Unlike Tar mode, Archive mode runs the appropriate program to unpack and
f7b17a6af3db (Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents: 28123
diff changeset
2454 repack archives. Details of the program names and their options can be
f7b17a6af3db (Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents: 28123
diff changeset
2455 set in the `Archive' Customize group.
28123
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2456
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2457 @node Remote Files
Dave Love <fx@gnu.org>
parents:
diff changeset
2458 @section Remote Files
Dave Love <fx@gnu.org>
parents:
diff changeset
2459
Dave Love <fx@gnu.org>
parents:
diff changeset
2460 @cindex FTP
Dave Love <fx@gnu.org>
parents:
diff changeset
2461 @cindex remote file access
Dave Love <fx@gnu.org>
parents:
diff changeset
2462 You can refer to files on other machines using a special file name syntax:
Dave Love <fx@gnu.org>
parents:
diff changeset
2463
Dave Love <fx@gnu.org>
parents:
diff changeset
2464 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2465 @group
Dave Love <fx@gnu.org>
parents:
diff changeset
2466 /@var{host}:@var{filename}
Dave Love <fx@gnu.org>
parents:
diff changeset
2467 /@var{user}@@@var{host}:@var{filename}
26105
c881de80a22b Mention vc-ignore-vc-files.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2468 /@var{user}@@@var{host}#@var{port}:@var{filename}
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2469 @end group
Dave Love <fx@gnu.org>
parents:
diff changeset
2470 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2471
Dave Love <fx@gnu.org>
parents:
diff changeset
2472 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
2473 When you do this, Emacs uses the FTP program to read and write files on
Dave Love <fx@gnu.org>
parents:
diff changeset
2474 the specified host. It logs in through FTP using your user name or the
Dave Love <fx@gnu.org>
parents:
diff changeset
2475 name @var{user}. It may ask you for a password from time to time; this
26105
c881de80a22b Mention vc-ignore-vc-files.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2476 is used for logging in on @var{host}. The form using @var{port} allows
c881de80a22b Mention vc-ignore-vc-files.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2477 you to access servers running on a non-default TCP port.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2478
Dave Love <fx@gnu.org>
parents:
diff changeset
2479 @cindex ange-ftp
Dave Love <fx@gnu.org>
parents:
diff changeset
2480 @vindex ange-ftp-default-user
Dave Love <fx@gnu.org>
parents:
diff changeset
2481 Normally, if you do not specify a user name in a remote file name,
Dave Love <fx@gnu.org>
parents:
diff changeset
2482 that means to use your own user name. But if you set the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
2483 @code{ange-ftp-default-user} to a string, that string is used instead.
Dave Love <fx@gnu.org>
parents:
diff changeset
2484 (The Emacs package that implements FTP file access is called
Dave Love <fx@gnu.org>
parents:
diff changeset
2485 @code{ange-ftp}.)
Dave Love <fx@gnu.org>
parents:
diff changeset
2486
Dave Love <fx@gnu.org>
parents:
diff changeset
2487 @vindex file-name-handler-alist
26105
c881de80a22b Mention vc-ignore-vc-files.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2488 You can entirely turn off the FTP file name feature by removing the
c881de80a22b Mention vc-ignore-vc-files.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2489 entries @var{ange-ftp-completion-hook-function} and
c881de80a22b Mention vc-ignore-vc-files.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2490 @var{ange-ftp-hook-function} from the variable
28327
f7b17a6af3db (Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents: 28123
diff changeset
2491 @code{file-name-handler-alist}. You can turn off the feature in
f7b17a6af3db (Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents: 28123
diff changeset
2492 individual cases by quoting the file name with @samp{/:} (@pxref{Quoted
f7b17a6af3db (Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents: 28123
diff changeset
2493 File Names}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2494
Dave Love <fx@gnu.org>
parents:
diff changeset
2495 @node Quoted File Names
Dave Love <fx@gnu.org>
parents:
diff changeset
2496 @section Quoted File Names
Dave Love <fx@gnu.org>
parents:
diff changeset
2497
Dave Love <fx@gnu.org>
parents:
diff changeset
2498 @cindex quoting file names
Dave Love <fx@gnu.org>
parents:
diff changeset
2499 You can @dfn{quote} an absolute file name to prevent special
Dave Love <fx@gnu.org>
parents:
diff changeset
2500 characters and syntax in it from having their special effects.
Dave Love <fx@gnu.org>
parents:
diff changeset
2501 The way to do this is to add @samp{/:} at the beginning.
Dave Love <fx@gnu.org>
parents:
diff changeset
2502
Dave Love <fx@gnu.org>
parents:
diff changeset
2503 For example, you can quote a local file name which appears remote, to
Dave Love <fx@gnu.org>
parents:
diff changeset
2504 prevent it from being treated as a remote file name. Thus, if you have
Dave Love <fx@gnu.org>
parents:
diff changeset
2505 a directory named @file{/foo:} and a file named @file{bar} in it, you
Dave Love <fx@gnu.org>
parents:
diff changeset
2506 can refer to that file in Emacs as @samp{/:/foo:/bar}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2507
Dave Love <fx@gnu.org>
parents:
diff changeset
2508 @samp{/:} can also prevent @samp{~} from being treated as a special
Dave Love <fx@gnu.org>
parents:
diff changeset
2509 character for a user's home directory. For example, @file{/:/tmp/~hack}
Dave Love <fx@gnu.org>
parents:
diff changeset
2510 refers to a file whose name is @file{~hack} in directory @file{/tmp}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2511
Dave Love <fx@gnu.org>
parents:
diff changeset
2512 Likewise, quoting with @samp{/:} is one way to enter in the minibuffer
Dave Love <fx@gnu.org>
parents:
diff changeset
2513 a file name that contains @samp{$}. However, the @samp{/:} must be at
Dave Love <fx@gnu.org>
parents:
diff changeset
2514 the beginning of the buffer in order to quote @samp{$}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2515
28327
f7b17a6af3db (Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents: 28123
diff changeset
2516 @cindex wildcard characters in file names
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2517 You can also quote wildcard characters with @samp{/:}, for visiting.
Dave Love <fx@gnu.org>
parents:
diff changeset
2518 For example, @file{/:/tmp/foo*bar} visits the file @file{/tmp/foo*bar}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2519 However, in most cases you can simply type the wildcard characters for
Dave Love <fx@gnu.org>
parents:
diff changeset
2520 themselves. For example, if the only file name in @file{/tmp} that
Dave Love <fx@gnu.org>
parents:
diff changeset
2521 starts with @samp{foo} and ends with @samp{bar} is @file{foo*bar}, then
Dave Love <fx@gnu.org>
parents:
diff changeset
2522 specifying @file{/tmp/foo*bar} will visit just @file{/tmp/foo*bar}.
28327
f7b17a6af3db (Visiting): List wildcard chars. Mention find-file-wildcards.
Dave Love <fx@gnu.org>
parents: 28123
diff changeset
2523 Another way is to specify @file{/tmp/foo[*]bar}.
28526
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2524
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2525 @node File Conveniences
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2526 @section Convenience Features for Finding Files
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2527
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2528 @findex recentf-mode
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2529 @vindex recentf-mode
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2530 @findex recentf-save-list
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2531 @findex recentf-edit-list
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2532 The command @kbd{M-x recentf-mode} or the Customize option of the same
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2533 name adds to the Files menu a submenu containing a list of recently
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2534 opened files. @kbd{recentf-save-list} saves the current file list to a
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2535 file and @kbd{recentf-edit-list} edits it.
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2536
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2537 @findex ff-find-other-file
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2538 @vindex ff-other-file-alist
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2539 The command @kbd{ff-find-other-file} finds a file related to the one
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2540 visited by the current buffer, based on customizable patterns.
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2541 Typically this will be the header file corresponding to a C/C++ source
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2542 file, or vice versa. The patterns describing the corresponding files
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2543 are customizable via @code{ff-other-file-alist}.
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2544
28671
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2545 @findex ffap
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2546 @findex find-file-at-point
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2547 @cindex finding file at point
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2548 The command @kbd{M-x find-file-at-point} (or @kbd{M-x ffap}) can be used
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2549 as a replacement for @kbd{M-x find-file}. With a prefix argument it
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2550 behaves as @kbd{M-x find-file}. Otherwise it tries to guess a default
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2551 file or URL from the text around point. This is useful for following
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2552 references in mail or news buffers, @file{README}s, @file{MANIFEST}s,
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2553 and so on. @kbd{M-x ffap-bindings} makes these global key bindings:
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2554
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2555 @table @kbd
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2556 @item C-x C-f
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2557 @kbd{find-file-at-point};
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2558 @item C-x 4 f
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2559 @kbd{ffap-other-window}, analagous to @kbd{find-file-other-window};
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2560 @item C-x 5 f
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2561 @kbd{ffap-other-frame}, analagous to @kbd{find-file-other-frame};
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2562 @item S-mouse-3
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2563 @kbd{ffap-at-mouse} finds the file guessed from text around the position
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2564 of a mouse click;
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2565 @item C-S-mouse-3
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2566 @kbd{ffap-menu} puts up a selectable menu of files and URLs mentioned in
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2567 the current buffer.
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2568 @end table
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2569
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2570 Partial Completion mode offers other features extending @kbd{M-x
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2571 find-file} which can be used with @code{ffap}. @xref{Completion
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2572 Options}.
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2573
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2574 @cindex filename caching
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2575 @cindex cache of file names
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2576 @pindex find
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2577 @pindex locate
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2578 @vindex file-cache-delete-regexps
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2579 The Filecache package attempts to make it easy to locate files by name
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2580 without having to remember exactly where they are. When typing a
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2581 filename in the minibuffer you can use @kbd{C-tab} to complete it using
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2582 the filename cache and to cycle through possible completions. (The
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2583 @kbd{C-tab} binding assumes a window system; otherwise you can make
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2584 another binding for @code{file-cache-minibuffer-complete}.) @kbd{M-x
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2585 file-cache-add-directory} adds the files in a directory to the cache and
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2586 @kbd{file-cache-add-directory-list} acts on a list of directories like
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2587 @kbd{load-path} or @kbd{exec-path}.
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2588 @kbd{file-cache-add-directory-using-find} uses the @code{find} program
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2589 to add a directory tree to the cache and
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2590 @kbd{file-cache-add-directory-using-locate} uses the @kbd{locate}
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2591 program to add files matching a pattern. Use @kbd{M-x
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2592 file-cache-clear-cache} to remove all items from the cache and @kbd{M-x
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2593 file-cache-delete-regexps} and similar functions to remove items from it
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2594 selectively.
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2595
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2596 @pindex locate
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2597 @findex locate
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2598 @findex locate-with-filter
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2599 @cindex file database (locate)
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2600 @vindex locate-command
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2601 @kbd{M-x locate} runs an interface to the @code{locate} program for
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2602 searching a pre-built database of file names; most Dired commands are
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2603 avilable for use on the result. @xref{Top, , Overview, find, GNU
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2604 Findutils}. @kbd{M-x locate-with-filter} is similar, but keeps only
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2605 lines matching a regular expression. Customize the option
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2606 @code{locate-command} to use another program than the default, GNU
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2607 @code{locate}.
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2608
28526
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2609 @c The Shadowfile package provides automatic file copying, allowing you to
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2610 @c keep identical copies of files in more than one place---possibly on
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2611 @c different machines. When you save a file, it checks whether it is on
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2612 @c the list of files with `shadows', and if so, it tries to copy it when
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2613 @c you exit emacs (or use the @kbd{M-x shadow-copy-files} command).