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