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