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