annotate man/files.texi @ 81548:334bfc4cc092

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