annotate man/files.texi @ 88769:9714c10f165d

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