annotate man/files.texi @ 83734:cdcb5994bf2b

*** empty log message ***
author Glenn Morris <rgm@gnu.org>
date Wed, 29 Aug 2007 08:09:51 +0000
parents b55f29a17618
children 424b655804ca
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
81970
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1261 * Why Version Control?:: Understanding the problems it addresses
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1262 * Version Systems:: Supported version control back-end systems.
Dave Love <fx@gnu.org>
parents:
diff changeset
1263 * 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
1264 * Types of Log File:: The per-file VC log in contrast to the ChangeLog.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1265 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1266
81970
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1267 @node Why Version Control?
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1268 @subsubsection Understanding the problems it addresses
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1269
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1270 Version control systems provide you with three important capabilities:
82008
fa89e40167b9 (Why Version Control?): Improve previous change.
Richard M. Stallman <rms@gnu.org>
parents: 81970
diff changeset
1271 reversibility, concurrency, and history.
81970
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1272
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1273 The most basic capability you get from a version-control system is
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1274 reversibility, the ability to back up to a saved, known-good state when
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1275 you discover that some modification you did was a mistake or a bad idea.
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1276
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1277 Version-control systems also support concurrency, the ability to
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1278 have many people modifying the same collection of code or documents
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1279 knowing that conflicting modifications can be detected and resolved.
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1280
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1281 Version-control systems give you the capability to attach a history
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1282 to your data, explanatory comments about the intention behind each
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1283 change to it. Even for a programmer working solo change histories
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1284 are an important aid to memory; for a multi-person project they
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1285 become a vitally important form of communication among developers.
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1286
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1287 @node Version Systems
Dave Love <fx@gnu.org>
parents:
diff changeset
1288 @subsubsection Supported Version Control Systems
Dave Love <fx@gnu.org>
parents:
diff changeset
1289
Dave Love <fx@gnu.org>
parents:
diff changeset
1290 @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
1291 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
1292 ``back ends'': CVS, GNU Arch, RCS, Meta-CVS, Subversion, and SCCS.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1293
Dave Love <fx@gnu.org>
parents:
diff changeset
1294 @cindex CVS
58112
6b135de9eb2c Rewrite the introduction about version systems, mentioning the new
André Spiegel <spiegel@gnu.org>
parents: 57404
diff changeset
1295 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
1296 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
1297 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
1298 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
1299 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
1300 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
1301 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
1302 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
1303 to treat here.
6b135de9eb2c Rewrite the introduction about version systems, mentioning the new
André Spiegel <spiegel@gnu.org>
parents: 57404
diff changeset
1304
6b135de9eb2c Rewrite the introduction about version systems, mentioning the new
André Spiegel <spiegel@gnu.org>
parents: 57404
diff changeset
1305 @cindex GNU Arch
6b135de9eb2c Rewrite the introduction about version systems, mentioning the new
André Spiegel <spiegel@gnu.org>
parents: 57404
diff changeset
1306 @cindex Arch
6b135de9eb2c Rewrite the introduction about version systems, mentioning the new
André Spiegel <spiegel@gnu.org>
parents: 57404
diff changeset
1307 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
1308 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
1309 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
1310 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
1311 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
1312 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
1313 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
1314 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
1315
6b135de9eb2c Rewrite the introduction about version systems, mentioning the new
André Spiegel <spiegel@gnu.org>
parents: 57404
diff changeset
1316 @cindex RCS
6b135de9eb2c Rewrite the introduction about version systems, mentioning the new
André Spiegel <spiegel@gnu.org>
parents: 57404
diff changeset
1317 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
1318 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
1319 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
1320 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
1321 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
1322 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
1323
6b135de9eb2c Rewrite the introduction about version systems, mentioning the new
André Spiegel <spiegel@gnu.org>
parents: 57404
diff changeset
1324 @cindex SVN
6b135de9eb2c Rewrite the introduction about version systems, mentioning the new
André Spiegel <spiegel@gnu.org>
parents: 57404
diff changeset
1325 @cindex Subversion
6b135de9eb2c Rewrite the introduction about version systems, mentioning the new
André Spiegel <spiegel@gnu.org>
parents: 57404
diff changeset
1326 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
1327 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
1328 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
1329 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
1330
6b135de9eb2c Rewrite the introduction about version systems, mentioning the new
André Spiegel <spiegel@gnu.org>
parents: 57404
diff changeset
1331 @cindex MCVS
6b135de9eb2c Rewrite the introduction about version systems, mentioning the new
André Spiegel <spiegel@gnu.org>
parents: 57404
diff changeset
1332 @cindex Meta-CVS
60792
4fbe0af1e69a (Visiting): Document large-file-warning-threshold.
Richard M. Stallman <rms@gnu.org>
parents: 60426
diff changeset
1333 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
1334 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
1335 merging, and use of symbolic links and meta-data in repositories.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1336
Dave Love <fx@gnu.org>
parents:
diff changeset
1337 @cindex SCCS
Dave Love <fx@gnu.org>
parents:
diff changeset
1338 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
1339 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
1340 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
1341 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
1342 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
1343 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
1344 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
1345 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
1346 systems such as CVS or GNU Arch.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1347
61011
755f6a803e71 Several small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 60976
diff changeset
1348 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
1349 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
1350 as well.
755f6a803e71 Several small changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents: 60976
diff changeset
1351
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1352 @node VC Concepts
Dave Love <fx@gnu.org>
parents:
diff changeset
1353 @subsubsection Concepts of Version Control
Dave Love <fx@gnu.org>
parents:
diff changeset
1354
Dave Love <fx@gnu.org>
parents:
diff changeset
1355 @cindex master file
Dave Love <fx@gnu.org>
parents:
diff changeset
1356 @cindex registered file
Dave Love <fx@gnu.org>
parents:
diff changeset
1357 When a file is under version control, we also say that it is
Dave Love <fx@gnu.org>
parents:
diff changeset
1358 @dfn{registered} in the version control system. Each registered file
Dave Love <fx@gnu.org>
parents:
diff changeset
1359 has a corresponding @dfn{master file} which represents the file's
Dave Love <fx@gnu.org>
parents:
diff changeset
1360 present state plus its change history---enough to reconstruct the
Dave Love <fx@gnu.org>
parents:
diff changeset
1361 current version or any earlier version. Usually the master file also
Dave Love <fx@gnu.org>
parents:
diff changeset
1362 records a @dfn{log entry} for each version, describing in words what was
Dave Love <fx@gnu.org>
parents:
diff changeset
1363 changed in that version.
Dave Love <fx@gnu.org>
parents:
diff changeset
1364
Dave Love <fx@gnu.org>
parents:
diff changeset
1365 @cindex work file
Dave Love <fx@gnu.org>
parents:
diff changeset
1366 @cindex checking out files
Dave Love <fx@gnu.org>
parents:
diff changeset
1367 The file that is maintained under version control is sometimes called
Dave Love <fx@gnu.org>
parents:
diff changeset
1368 the @dfn{work file} corresponding to its master file. You edit the work
Dave Love <fx@gnu.org>
parents:
diff changeset
1369 file and make changes in it, as you would with an ordinary file. (With
Dave Love <fx@gnu.org>
parents:
diff changeset
1370 SCCS and RCS, you must @dfn{lock} the file before you start to edit it.)
Dave Love <fx@gnu.org>
parents:
diff changeset
1371 After you are done with a set of changes, you @dfn{check the file in},
Dave Love <fx@gnu.org>
parents:
diff changeset
1372 which records the changes in the master file, along with a log entry for
Dave Love <fx@gnu.org>
parents:
diff changeset
1373 them.
Dave Love <fx@gnu.org>
parents:
diff changeset
1374
81970
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1375 To go beyond these basic concepts, you will need to understand three
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1376 ways in which version-control systems can differ from each other. They
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1377 can be locking or merging; they can be file-based or changeset-based;
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1378 and they can be centralized or decentralized. VC handles all these
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1379 choices, but they lead to differing behaviors which you will need
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1380 to understand as you use it.
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1381
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1382 @cindex locking versus merging
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1383 A version control system typically has some mechanism to coordinate
Dave Love <fx@gnu.org>
parents:
diff changeset
1384 between users who want to change the same file. One method is
Dave Love <fx@gnu.org>
parents:
diff changeset
1385 @dfn{locking} (analogous to the locking that Emacs uses to detect
81970
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1386 simultaneous editing of a file, but distinct from it). In a locking
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1387 system, such as SCCS, you must @dfn{lock} a file before you start to
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1388 edit it. The other method is @dfn{merging}; the system tries to
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1389 merge your changes with other people's changes when you check them in.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1390
Dave Love <fx@gnu.org>
parents:
diff changeset
1391 With version control locking, work files are normally read-only so
Dave Love <fx@gnu.org>
parents:
diff changeset
1392 that you cannot change them. You ask the version control system to make
Dave Love <fx@gnu.org>
parents:
diff changeset
1393 a work file writable for you by locking it; only one user can do
Dave Love <fx@gnu.org>
parents:
diff changeset
1394 this at any given time. When you check in your changes, that unlocks
Dave Love <fx@gnu.org>
parents:
diff changeset
1395 the file, making the work file read-only again. This allows other users
81970
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1396 to lock the file to make further changes.
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1397
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1398 By contrast, a merging system lets each user check out and modify a
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1399 work file at any time. When you check in a a file, the system will
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1400 attempt to merge your changes with any others checked into the
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1401 repository since you checked out the file.
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1402
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1403 Both locking and merging systems can have problems when multiple users
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1404 try to modify the same file at the same time. Locking systems have
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1405 @dfn{lock conflicts}; a user may try to check a file out and be unable
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1406 to because it is locked. In merging systems, @dfn{merge conflicts}
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1407 happen when you check in a change to a file that conflicts with a change
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1408 checked in by someone else after your checkout. Both kinds of conflict
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1409 have to be resolved by human judgment and communication.
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1410
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1411 SCCS always uses locking. RCS is lock-based by default but can be told
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1412 to operate in a merging style. CVS is merge-based by default but can
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1413 be told to operate in a locking mode. Most later version-control
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1414 systems, such as Subversion and GNU Arch, have been fundamentally
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1415 merging-based rather than locking-based. This is because experience
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1416 has shown that the merging-based approach is generally superior to
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1417 the locking one, both in convenience to developers and in minimizing
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1418 the number and severity of conflicts that actually occur.
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1419
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1420 While it is rather unlikely that anyone will ever again build a
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1421 fundamentally locking-based rather than merging-based version-control
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1422 system in the future, merging-based version-systems sometimes have locks
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1423 retrofitted onto them for reasons having nothing to do with technology.
82008
fa89e40167b9 (Why Version Control?): Improve previous change.
Richard M. Stallman <rms@gnu.org>
parents: 81970
diff changeset
1424 @footnote{Usually the control-freak instincts of managers.} For this
81970
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1425 reason, and to support older systems still in use, VC mode supports
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1426 both locking and merging version control and tries to hide the differences
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1427 between them as much as possible.
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1428
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1429 @cindex files versus changesets.
82008
fa89e40167b9 (Why Version Control?): Improve previous change.
Richard M. Stallman <rms@gnu.org>
parents: 81970
diff changeset
1430 On SCCS, RCS, CVS, and other early version-control systems, checkins
81970
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1431 and other operations are @dfn{file-based}; each file has its own
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1432 @dfn{master file} with its own comment- and revision history separate
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1433 from that of all other files in the system. Later systems, beginning
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1434 with Subversion, are @dfn{changeset-based}; a checkin may include
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1435 changes to several files and that change set is treated as a unit by the
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1436 system. Any comment associated with the change doesn't belong to any
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1437 one file, but is attached to the changeset itself.
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1438
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1439 Changeset-based version control is in general both more flexible and
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1440 more powerful than file-based version control; usually, when a change to
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1441 multiple files has to be backed out, it's good to be able to easily
82008
fa89e40167b9 (Why Version Control?): Improve previous change.
Richard M. Stallman <rms@gnu.org>
parents: 81970
diff changeset
1442 identify and remove all of it.
81970
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1443
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1444 @cindex centralized vs. decentralized
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1445 Early version-control systems were designed around a @dfn{centralized}
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1446 model in which each project has only one repository used by all
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1447 developers. SCCS, RCS, CVS, and Subversion share this kind of model.
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1448 It has two important problems. One is that a single repository is a
82008
fa89e40167b9 (Why Version Control?): Improve previous change.
Richard M. Stallman <rms@gnu.org>
parents: 81970
diff changeset
1449 single point of failure---if the repository server is down all work
81970
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1450 stops. The other is that you need to be connected live to the server to
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1451 do checkins and checkouts; if you're offline, you can't work.
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1452
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1453 Newer version-control systems like GNU Arch are @dfn{decentralized}.
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1454 A project may have several different repositories, and these systems
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1455 support a sort of super-merge between repositories that tries to
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1456 reconcile their change histories. At the limit, each developer has
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1457 his/her own repository, and repository merges replace checkin/commit
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1458 operations.
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1459
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1460 VC's job is to help you manage the traffic between your personal
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1461 workfiles and a repository. Whether that repository is a single master
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1462 or one of a network of peer repositories is not something VC has to care
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1463 about. Thus, the difference between a centralized and a decentralized
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1464 version-control system is invisible to VC mode.
4d96d6799f84 Improve the explanation of version control to include concepts
Eric S. Raymond <esr@snark.thyrsus.com>
parents: 77599
diff changeset
1465
70445
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1466 @iftex
69945
87cbb18a44b0 move more advanced vc info to emacs-xtra.texi
Karl Berry <karl@gnu.org>
parents: 69940
diff changeset
1467 (@pxref{CVS Options,,,emacs-xtra, Specialized Emacs Features}).
70445
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1468 @end iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1469 @ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1470 (@pxref{CVS Options}).
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1471 @end ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1472
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1473
42327
86a0b7cc1600 Explain the difference between the per-file log maintained by the
Robert J. Chassell <bob@rattlesnake.com>
parents: 40682
diff changeset
1474 @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
1475 @subsubsection Types of Log File
42338
8649ccc72076 Rewrite Types of Log File node.
Richard M. Stallman <rms@gnu.org>
parents: 42327
diff changeset
1476 @cindex types of log file
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49561
diff changeset
1477 @cindex log File, types of
42338
8649ccc72076 Rewrite Types of Log File node.
Richard M. Stallman <rms@gnu.org>
parents: 42327
diff changeset
1478 @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
1479
60426
087c96c87148 (Types of Log File): Explain how projects' methods can vary.
Richard M. Stallman <rms@gnu.org>
parents: 59886
diff changeset
1480 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
1481 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
1482 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
1483 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
1484 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
1485 @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
1486
087c96c87148 (Types of Log File): Explain how projects' methods can vary.
Richard M. Stallman <rms@gnu.org>
parents: 59886
diff changeset
1487 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
1488 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
1489 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
1490 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
1491 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
1492 @xref{Change Log}.
087c96c87148 (Types of Log File): Explain how projects' methods can vary.
Richard M. Stallman <rms@gnu.org>
parents: 59886
diff changeset
1493
087c96c87148 (Types of Log File): Explain how projects' methods can vary.
Richard M. Stallman <rms@gnu.org>
parents: 59886
diff changeset
1494 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
1495 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
1496 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
1497 you should follow.
087c96c87148 (Types of Log File): Explain how projects' methods can vary.
Richard M. Stallman <rms@gnu.org>
parents: 59886
diff changeset
1498
087c96c87148 (Types of Log File): Explain how projects' methods can vary.
Richard M. Stallman <rms@gnu.org>
parents: 59886
diff changeset
1499 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
1500 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
1501 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
1502 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
1503 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
1504 to copy it to @file{ChangeLog}
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1505 @iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1506 (@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
1507 @end iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1508 @ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1509 (@pxref{Change Logs and VC}).
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1510 @end ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1511
42327
86a0b7cc1600 Explain the difference between the per-file log maintained by the
Robert J. Chassell <bob@rattlesnake.com>
parents: 40682
diff changeset
1512
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1513 @node VC Mode Line
Dave Love <fx@gnu.org>
parents:
diff changeset
1514 @subsection Version Control and the Mode Line
Dave Love <fx@gnu.org>
parents:
diff changeset
1515
Dave Love <fx@gnu.org>
parents:
diff changeset
1516 When you visit a file that is under version control, Emacs indicates
Dave Love <fx@gnu.org>
parents:
diff changeset
1517 this on the mode line. For example, @samp{RCS-1.3} says that RCS is
Dave Love <fx@gnu.org>
parents:
diff changeset
1518 used for that file, and the current version is 1.3.
Dave Love <fx@gnu.org>
parents:
diff changeset
1519
Dave Love <fx@gnu.org>
parents:
diff changeset
1520 The character between the back-end name and the version number
Dave Love <fx@gnu.org>
parents:
diff changeset
1521 indicates the version control status of the file. @samp{-} means that
Dave Love <fx@gnu.org>
parents:
diff changeset
1522 the work file is not locked (if locking is in use), or not modified (if
Dave Love <fx@gnu.org>
parents:
diff changeset
1523 locking is not in use). @samp{:} indicates that the file is locked, or
Dave Love <fx@gnu.org>
parents:
diff changeset
1524 that it is modified. If the file is locked by some other user (for
Dave Love <fx@gnu.org>
parents:
diff changeset
1525 instance, @samp{jim}), that is displayed as @samp{RCS:jim:1.3}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1526
61197
188e0bfcbc42 (Reverting): Move `auto-revert-check-vc-info' to `VC Mode Line' and
Luc Teirlinck <teirllm@auburn.edu>
parents: 61046
diff changeset
1527 @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
1528 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
1529 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
1530 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
1531 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
1532 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
1533 @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
1534 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
1535 @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
1536 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
1537 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
1538
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1539 @node Basic VC Editing
Dave Love <fx@gnu.org>
parents:
diff changeset
1540 @subsection Basic Editing under Version Control
Dave Love <fx@gnu.org>
parents:
diff changeset
1541
Dave Love <fx@gnu.org>
parents:
diff changeset
1542 The principal VC command is an all-purpose command that performs
Dave Love <fx@gnu.org>
parents:
diff changeset
1543 either locking or check-in, depending on the situation.
Dave Love <fx@gnu.org>
parents:
diff changeset
1544
Dave Love <fx@gnu.org>
parents:
diff changeset
1545 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
1546 @itemx C-x v v
Dave Love <fx@gnu.org>
parents:
diff changeset
1547 Perform the next logical version control operation on this file.
Dave Love <fx@gnu.org>
parents:
diff changeset
1548 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1549
Dave Love <fx@gnu.org>
parents:
diff changeset
1550 @findex vc-next-action
Dave Love <fx@gnu.org>
parents:
diff changeset
1551 @kindex C-x v v
Dave Love <fx@gnu.org>
parents:
diff changeset
1552 The precise action of this command depends on the state of the file,
Dave Love <fx@gnu.org>
parents:
diff changeset
1553 and whether the version control system uses locking or not. SCCS and
Dave Love <fx@gnu.org>
parents:
diff changeset
1554 RCS normally use locking; CVS normally does not use locking.
Dave Love <fx@gnu.org>
parents:
diff changeset
1555
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
1556 @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
1557 @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
1558 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
1559 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
1560 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
1561 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
1562 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
1563 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
1564
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1565 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1566 * VC with Locking:: RCS in its default mode, SCCS, and optionally CVS.
Dave Love <fx@gnu.org>
parents:
diff changeset
1567 * 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
1568 * Advanced C-x v v:: Advanced features available with a prefix argument.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1569 * Log Buffer:: Features available in log entry buffers.
Dave Love <fx@gnu.org>
parents:
diff changeset
1570 @end menu
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49561
diff changeset
1571
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49561
diff changeset
1572 @node VC with Locking
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1573 @subsubsection Basic Version Control with Locking
Dave Love <fx@gnu.org>
parents:
diff changeset
1574
Dave Love <fx@gnu.org>
parents:
diff changeset
1575 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
1576 mode), @kbd{C-x v v} can either lock a file or check it in:
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1577
Dave Love <fx@gnu.org>
parents:
diff changeset
1578 @itemize @bullet
Dave Love <fx@gnu.org>
parents:
diff changeset
1579 @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
1580 If the file is not locked, @kbd{C-x v v} locks it, and
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1581 makes it writable so that you can change it.
Dave Love <fx@gnu.org>
parents:
diff changeset
1582
Dave Love <fx@gnu.org>
parents:
diff changeset
1583 @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
1584 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
1585 in the changes. In order to do this, it first reads the log entry
Dave Love <fx@gnu.org>
parents:
diff changeset
1586 for the new version. @xref{Log Buffer}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1587
Dave Love <fx@gnu.org>
parents:
diff changeset
1588 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
1589 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
1590 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
1591 again.
Dave Love <fx@gnu.org>
parents:
diff changeset
1592
Dave Love <fx@gnu.org>
parents:
diff changeset
1593 @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
1594 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
1595 you want to ``steal the lock'' from that user. If you say yes, the file
Dave Love <fx@gnu.org>
parents:
diff changeset
1596 becomes locked by you, but a message is sent to the person who had
Dave Love <fx@gnu.org>
parents:
diff changeset
1597 formerly locked the file, to inform him of what has happened.
Dave Love <fx@gnu.org>
parents:
diff changeset
1598 @end itemize
Dave Love <fx@gnu.org>
parents:
diff changeset
1599
Dave Love <fx@gnu.org>
parents:
diff changeset
1600 These rules also apply when you use CVS in locking mode, except
Dave Love <fx@gnu.org>
parents:
diff changeset
1601 that there is no such thing as stealing a lock.
Dave Love <fx@gnu.org>
parents:
diff changeset
1602
Dave Love <fx@gnu.org>
parents:
diff changeset
1603 @node Without Locking
Dave Love <fx@gnu.org>
parents:
diff changeset
1604 @subsubsection Basic Version Control without Locking
Dave Love <fx@gnu.org>
parents:
diff changeset
1605
Dave Love <fx@gnu.org>
parents:
diff changeset
1606 When there is no locking---the default for CVS---work files are always
Dave Love <fx@gnu.org>
parents:
diff changeset
1607 writable; you do not need to do anything before you begin to edit a
Dave Love <fx@gnu.org>
parents:
diff changeset
1608 file. The status indicator on the mode line is @samp{-} if the file is
Dave Love <fx@gnu.org>
parents:
diff changeset
1609 unmodified; it flips to @samp{:} as soon as you save any changes in the
Dave Love <fx@gnu.org>
parents:
diff changeset
1610 work file.
Dave Love <fx@gnu.org>
parents:
diff changeset
1611
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
1612 Here is what @kbd{C-x v v} does when using CVS:
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1613
Dave Love <fx@gnu.org>
parents:
diff changeset
1614 @itemize @bullet
Dave Love <fx@gnu.org>
parents:
diff changeset
1615 @item
36385
d7ca85bd6906 Clean up recent VC updates.
Richard M. Stallman <rms@gnu.org>
parents: 36360
diff changeset
1616 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
1617 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
1618 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
1619 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
1620 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
1621 @xref{Merging}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1622
Dave Love <fx@gnu.org>
parents:
diff changeset
1623 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
1624 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
1625 modifications in your work file, @kbd{C-x v v} checks in your changes.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1626 In order to do this, it first reads the log entry for the new version.
Dave Love <fx@gnu.org>
parents:
diff changeset
1627 @xref{Log Buffer}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1628
Dave Love <fx@gnu.org>
parents:
diff changeset
1629 @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
1630 If the file is not modified, the @kbd{C-x v v} does nothing.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1631 @end itemize
Dave Love <fx@gnu.org>
parents:
diff changeset
1632
Dave Love <fx@gnu.org>
parents:
diff changeset
1633 These rules also apply when you use RCS in the mode that does not
Dave Love <fx@gnu.org>
parents:
diff changeset
1634 require locking, except that automatic merging of changes from the
Dave Love <fx@gnu.org>
parents:
diff changeset
1635 master file is not implemented. Unfortunately, this means that nothing
Dave Love <fx@gnu.org>
parents:
diff changeset
1636 informs you if another user has checked in changes in the same file
Dave Love <fx@gnu.org>
parents:
diff changeset
1637 since you began editing it, and when this happens, his changes will be
Dave Love <fx@gnu.org>
parents:
diff changeset
1638 effectively removed when you check in your version (though they will
Dave Love <fx@gnu.org>
parents:
diff changeset
1639 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
1640 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
1641 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
1642 automatic merging with RCS in a future Emacs version.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1643
Dave Love <fx@gnu.org>
parents:
diff changeset
1644 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
1645 it is not required; @kbd{C-x v v} with an unmodified file locks the
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1646 file, just as it does with RCS in its normal (locking) mode.
Dave Love <fx@gnu.org>
parents:
diff changeset
1647
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
1648 @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
1649 @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
1650
44588
332679f37a67 Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents: 44550
diff changeset
1651 @cindex version number to check in/out
36385
d7ca85bd6906 Clean up recent VC updates.
Richard M. Stallman <rms@gnu.org>
parents: 36360
diff changeset
1652 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
1653 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
1654 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
1655 to do the operation.
36355
d8c0e3d0f0aa VC section updated. Added a subsection on remote repositories,
André Spiegel <spiegel@gnu.org>
parents: 36327
diff changeset
1656
d8c0e3d0f0aa VC section updated. Added a subsection on remote repositories,
André Spiegel <spiegel@gnu.org>
parents: 36327
diff changeset
1657 @itemize @bullet
36385
d7ca85bd6906 Clean up recent VC updates.
Richard M. Stallman <rms@gnu.org>
parents: 36360
diff changeset
1658 @item
d7ca85bd6906 Clean up recent VC updates.
Richard M. Stallman <rms@gnu.org>
parents: 36360
diff changeset
1659 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
1660 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
1661 to create a new branch (@pxref{Branches}).
d7ca85bd6906 Clean up recent VC updates.
Richard M. Stallman <rms@gnu.org>
parents: 36360
diff changeset
1662
d7ca85bd6906 Clean up recent VC updates.
Richard M. Stallman <rms@gnu.org>
parents: 36360
diff changeset
1663 @item
d7ca85bd6906 Clean up recent VC updates.
Richard M. Stallman <rms@gnu.org>
parents: 36360
diff changeset
1664 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
1665 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
1666 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
1667 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
1668 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
1669 the repository.
d7ca85bd6906 Clean up recent VC updates.
Richard M. Stallman <rms@gnu.org>
parents: 36360
diff changeset
1670
d7ca85bd6906 Clean up recent VC updates.
Richard M. Stallman <rms@gnu.org>
parents: 36360
diff changeset
1671 @item
44588
332679f37a67 Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents: 44550
diff changeset
1672 @cindex specific version control system
36385
d7ca85bd6906 Clean up recent VC updates.
Richard M. Stallman <rms@gnu.org>
parents: 36360
diff changeset
1673 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
1674 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
1675 with two version control systems at the same time
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1676 @iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1677 (@pxref{Local Version Control,,,emacs-xtra, Specialized Emacs
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1678 Features}).
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1679 @end iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1680 @ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1681 (@pxref{Local Version Control}).
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1682 @end ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1683
36355
d8c0e3d0f0aa VC section updated. Added a subsection on remote repositories,
André Spiegel <spiegel@gnu.org>
parents: 36327
diff changeset
1684 @end itemize
d8c0e3d0f0aa VC section updated. Added a subsection on remote repositories,
André Spiegel <spiegel@gnu.org>
parents: 36327
diff changeset
1685
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1686 @node Log Buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
1687 @subsubsection Features of the Log Entry Buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
1688
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
1689 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
1690 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
1691
68540
b1e412bac8b7 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 68310
diff changeset
1692 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
1693 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
1694 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
1695 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
1696
269312974c2f (Log Buffer): Merge in description of Log Edit
Nick Roberts <nickrob@snap.net.nz>
parents: 62474
diff changeset
1697 @findex log-edit-insert-changelog
68540
b1e412bac8b7 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 68310
diff changeset
1698 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
1699 (@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
1700 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
1701 @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
1702 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
1703 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
1704 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
1705 @iftex
69945
87cbb18a44b0 move more advanced vc info to emacs-xtra.texi
Karl Berry <karl@gnu.org>
parents: 69940
diff changeset
1706 @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
1707 @end iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1708 @ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1709 @xref{Change Logs and VC},
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1710 @end ifnottex
69945
87cbb18a44b0 move more advanced vc info to emacs-xtra.texi
Karl Berry <karl@gnu.org>
parents: 69940
diff changeset
1711 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
1712 the revision control log.
87cbb18a44b0 move more advanced vc info to emacs-xtra.texi
Karl Berry <karl@gnu.org>
parents: 69940
diff changeset
1713
87cbb18a44b0 move more advanced vc info to emacs-xtra.texi
Karl Berry <karl@gnu.org>
parents: 69940
diff changeset
1714 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
1715 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
1716 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
1717 you use VC Dired mode or PCL-CVS.
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1718 @iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1719 @xref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features},
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1720 @end iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1721 @ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1722 @xref{VC Dired Mode},
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1723 @end ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1724 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
1725 Front-End to CVS}.)
62784
269312974c2f (Log Buffer): Merge in description of Log Edit
Nick Roberts <nickrob@snap.net.nz>
parents: 62474
diff changeset
1726
68540
b1e412bac8b7 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 68310
diff changeset
1727 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
1728 exit the buffer and commit the change.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1729
Dave Love <fx@gnu.org>
parents:
diff changeset
1730 To abort check-in, just @strong{don't} type @kbd{C-c C-c} in that
Dave Love <fx@gnu.org>
parents:
diff changeset
1731 buffer. You can switch buffers and do other editing. As long as you
Dave Love <fx@gnu.org>
parents:
diff changeset
1732 don't try to check in another file, the entry you were editing remains
Dave Love <fx@gnu.org>
parents:
diff changeset
1733 in the @samp{*VC-Log*} buffer, and you can go back to that buffer at any
Dave Love <fx@gnu.org>
parents:
diff changeset
1734 time to complete the check-in.
Dave Love <fx@gnu.org>
parents:
diff changeset
1735
Dave Love <fx@gnu.org>
parents:
diff changeset
1736 If you change several source files for the same reason, it is often
Dave Love <fx@gnu.org>
parents:
diff changeset
1737 convenient to specify the same log entry for many of the files. To do
Dave Love <fx@gnu.org>
parents:
diff changeset
1738 this, use the history of previous log entries. The commands @kbd{M-n},
Dave Love <fx@gnu.org>
parents:
diff changeset
1739 @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
1740 minibuffer history commands (except that these versions are used outside
Dave Love <fx@gnu.org>
parents:
diff changeset
1741 the minibuffer).
Dave Love <fx@gnu.org>
parents:
diff changeset
1742
Dave Love <fx@gnu.org>
parents:
diff changeset
1743 @vindex vc-log-mode-hook
Dave Love <fx@gnu.org>
parents:
diff changeset
1744 Each time you check in a file, the log entry buffer is put into VC Log
Dave Love <fx@gnu.org>
parents:
diff changeset
1745 mode, which involves running two hooks: @code{text-mode-hook} and
Dave Love <fx@gnu.org>
parents:
diff changeset
1746 @code{vc-log-mode-hook}. @xref{Hooks}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1747
Dave Love <fx@gnu.org>
parents:
diff changeset
1748 @node Old Versions
Dave Love <fx@gnu.org>
parents:
diff changeset
1749 @subsection Examining And Comparing Old Versions
Dave Love <fx@gnu.org>
parents:
diff changeset
1750
Dave Love <fx@gnu.org>
parents:
diff changeset
1751 One of the convenient features of version control is the ability
Dave Love <fx@gnu.org>
parents:
diff changeset
1752 to examine any version of a file, or compare two versions.
Dave Love <fx@gnu.org>
parents:
diff changeset
1753
Dave Love <fx@gnu.org>
parents:
diff changeset
1754 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
1755 @item C-x v ~ @var{version} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
1756 Examine version @var{version} of the visited file, in a buffer of its
Dave Love <fx@gnu.org>
parents:
diff changeset
1757 own.
Dave Love <fx@gnu.org>
parents:
diff changeset
1758
Dave Love <fx@gnu.org>
parents:
diff changeset
1759 @item C-x v =
69612
cf3a4af06ad8 Various updates and clarifications in the VC chapter.
André Spiegel <spiegel@gnu.org>
parents: 69506
diff changeset
1760 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
1761 you started editing.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1762
Dave Love <fx@gnu.org>
parents:
diff changeset
1763 @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
1764 Compare the specified two versions of @var{file}.
Dave Love <fx@gnu.org>
parents:
diff changeset
1765
Dave Love <fx@gnu.org>
parents:
diff changeset
1766 @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
1767 Display the file with per-line version information and using colors.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1768 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1769
Dave Love <fx@gnu.org>
parents:
diff changeset
1770 @findex vc-version-other-window
Dave Love <fx@gnu.org>
parents:
diff changeset
1771 @kindex C-x v ~
38739
7055d897b6bb Many minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 38310
diff changeset
1772 To examine an old version in its entirety, visit the file and then type
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1773 @kbd{C-x v ~ @var{version} @key{RET}} (@code{vc-version-other-window}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1774 This puts the text of version @var{version} in a file named
Dave Love <fx@gnu.org>
parents:
diff changeset
1775 @file{@var{filename}.~@var{version}~}, and visits it in its own buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
1776 in a separate window. (In RCS, you can also select an old version
Dave Love <fx@gnu.org>
parents:
diff changeset
1777 and create a branch from it. @xref{Branches}.)
Dave Love <fx@gnu.org>
parents:
diff changeset
1778
Dave Love <fx@gnu.org>
parents:
diff changeset
1779 @findex vc-diff
Dave Love <fx@gnu.org>
parents:
diff changeset
1780 @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
1781 It is usually more convenient to compare two versions of the file,
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1782 with the command @kbd{C-x v =} (@code{vc-diff}). Plain @kbd{C-x v =}
Dave Love <fx@gnu.org>
parents:
diff changeset
1783 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
1784 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
1785 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
1786 @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
1787 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
1788 Both forms display the output in a special buffer in another window.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1789
Dave Love <fx@gnu.org>
parents:
diff changeset
1790 You can specify a checked-in version by its number; an empty input
Dave Love <fx@gnu.org>
parents:
diff changeset
1791 specifies the current contents of the work file (which may be different
Dave Love <fx@gnu.org>
parents:
diff changeset
1792 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
1793 @iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1794 (@pxref{Snapshots,,,emacs-xtra, Specialized Emacs Features})
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1795 @end iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1796 @ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1797 (@pxref{Snapshots})
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1798 @end ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1799 instead of one or both version numbers.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1800
36385
d7ca85bd6906 Clean up recent VC updates.
Richard M. Stallman <rms@gnu.org>
parents: 36360
diff changeset
1801 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
1802 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
1803 files in that directory and its subdirectories.
d7ca85bd6906 Clean up recent VC updates.
Richard M. Stallman <rms@gnu.org>
parents: 36360
diff changeset
1804
36355
d8c0e3d0f0aa VC section updated. Added a subsection on remote repositories,
André Spiegel <spiegel@gnu.org>
parents: 36327
diff changeset
1805 @vindex vc-diff-switches
38739
7055d897b6bb Many minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 38310
diff changeset
1806 @vindex vc-rcs-diff-switches
36385
d7ca85bd6906 Clean up recent VC updates.
Richard M. Stallman <rms@gnu.org>
parents: 36360
diff changeset
1807 @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
1808 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
1809 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
1810 @code{diff-switches} (@pxref{Comparing Files}), it receives those
38739
7055d897b6bb Many minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 38310
diff changeset
1811 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
1812 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
1813 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
1814 the options in @code{vc-rcs-diff-switches}. The
7055d897b6bb Many minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 38310
diff changeset
1815 @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
1816
69205
316ca9a52405 (Old Versions): Clarify operation of C-x v =.
André Spiegel <spiegel@gnu.org>
parents: 68843
diff changeset
1817 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
1818 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
1819 @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
1820 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
1821 versions are not, in general, present as files on your disk.)
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1822
Dave Love <fx@gnu.org>
parents:
diff changeset
1823 @findex vc-annotate
Dave Love <fx@gnu.org>
parents:
diff changeset
1824 @kindex C-x v g
69612
cf3a4af06ad8 Various updates and clarifications in the VC chapter.
André Spiegel <spiegel@gnu.org>
parents: 69506
diff changeset
1825 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
1826 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
1827 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
1828 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
1829 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
1830 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
1831 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
1832 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
1833
8c66ad9acae0 Clarify description of vc-annotate.
Richard M. Stallman <rms@gnu.org>
parents: 38922
diff changeset
1834 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
1835 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
1836 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
1837 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
1838
d774cde528a2 Update description of vc-annotate's use of colors to indicate date
J.D. Smith <jdsmith@as.arizona.edu>
parents: 69710
diff changeset
1839 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
1840 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
1841 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
1842 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
1843
67511
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1844 @table @kbd
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1845 @item P
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1846 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
1847 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
1848 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
1849
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1850 @item N
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1851 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
1852 annotated. A numeric prefix argument is a repeat count.
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1853
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1854 @item J
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1855 Annotate the revision indicated by the current line.
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1856
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1857 @item A
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1858 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
1859 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
1860 the current line was made.
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1861
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1862 @item D
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1863 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
1864 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
1865 actually changed in the file.
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1866
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1867 @item L
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1868 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
1869 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
1870 line.
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1871
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1872 @item W
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1873 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
1874 @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
1875 return to your current version.
67511
3251bdbd90a9 (Old Versions): Use @table.
Richard M. Stallman <rms@gnu.org>
parents: 66992
diff changeset
1876 @end table
53633
e332688255cd Describe new key bindings in VC Annotate mode.
André Spiegel <spiegel@gnu.org>
parents: 53244
diff changeset
1877
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1878 @node Secondary VC Commands
Dave Love <fx@gnu.org>
parents:
diff changeset
1879 @subsection The Secondary Commands of VC
Dave Love <fx@gnu.org>
parents:
diff changeset
1880
Dave Love <fx@gnu.org>
parents:
diff changeset
1881 This section explains the secondary commands of VC; those that you might
Dave Love <fx@gnu.org>
parents:
diff changeset
1882 use once a day.
Dave Love <fx@gnu.org>
parents:
diff changeset
1883
Dave Love <fx@gnu.org>
parents:
diff changeset
1884 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1885 * Registering:: Putting a file under version control.
Dave Love <fx@gnu.org>
parents:
diff changeset
1886 * 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
1887 * 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
1888 @ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1889 * VC Dired Mode:: Listing files managed by version control.
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1890 * 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
1891 @end ifnottex
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1892 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
1893
Dave Love <fx@gnu.org>
parents:
diff changeset
1894 @node Registering
Dave Love <fx@gnu.org>
parents:
diff changeset
1895 @subsubsection Registering a File for Version Control
Dave Love <fx@gnu.org>
parents:
diff changeset
1896
Dave Love <fx@gnu.org>
parents:
diff changeset
1897 @kindex C-x v i
Dave Love <fx@gnu.org>
parents:
diff changeset
1898 @findex vc-register
Dave Love <fx@gnu.org>
parents:
diff changeset
1899 You can put any file under version control by simply visiting it, and
Dave Love <fx@gnu.org>
parents:
diff changeset
1900 then typing @w{@kbd{C-x v i}} (@code{vc-register}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1901
Dave Love <fx@gnu.org>
parents:
diff changeset
1902 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
1903 @item C-x v i
Dave Love <fx@gnu.org>
parents:
diff changeset
1904 Register the visited file for version control.
Dave Love <fx@gnu.org>
parents:
diff changeset
1905 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1906
Dave Love <fx@gnu.org>
parents:
diff changeset
1907 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
1908 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
1909 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
1910 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
1911 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
1912 @iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1913 (@pxref{Customizing VC,,,emacs-xtra, Specialized Emacs Features}).
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1914 @end iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1915 @ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1916 (@pxref{Customizing VC}).
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1917 @end ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1918 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
1919 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
1920 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
1921 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
1922 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
1923 situation.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1924
Dave Love <fx@gnu.org>
parents:
diff changeset
1925 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
1926 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
1927 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
1928 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
1929 appears as @samp{@@@@} in the mode line.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1930
Dave Love <fx@gnu.org>
parents:
diff changeset
1931 @vindex vc-default-init-version
44588
332679f37a67 Fix last change.
Eli Zaretskii <eliz@gnu.org>
parents: 44550
diff changeset
1932 @cindex initial version number to register
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1933 The initial version number for a newly registered file is 1.1, by
Dave Love <fx@gnu.org>
parents:
diff changeset
1934 default. You can specify a different default by setting the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
1935 @code{vc-default-init-version}, or you can give @kbd{C-x v i} a numeric
Dave Love <fx@gnu.org>
parents:
diff changeset
1936 argument; then it reads the initial version number for this particular
Dave Love <fx@gnu.org>
parents:
diff changeset
1937 file using the minibuffer.
Dave Love <fx@gnu.org>
parents:
diff changeset
1938
Dave Love <fx@gnu.org>
parents:
diff changeset
1939 @vindex vc-initial-comment
Dave Love <fx@gnu.org>
parents:
diff changeset
1940 If @code{vc-initial-comment} is non-@code{nil}, @kbd{C-x v i} reads an
Dave Love <fx@gnu.org>
parents:
diff changeset
1941 initial comment to describe the purpose of this source file. Reading
Dave Love <fx@gnu.org>
parents:
diff changeset
1942 the initial comment works like reading a log entry (@pxref{Log Buffer}).
Dave Love <fx@gnu.org>
parents:
diff changeset
1943
Dave Love <fx@gnu.org>
parents:
diff changeset
1944 @node VC Status
Dave Love <fx@gnu.org>
parents:
diff changeset
1945 @subsubsection VC Status Commands
Dave Love <fx@gnu.org>
parents:
diff changeset
1946
Dave Love <fx@gnu.org>
parents:
diff changeset
1947 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
1948 @item C-x v l
Dave Love <fx@gnu.org>
parents:
diff changeset
1949 Display version control state and change history.
Dave Love <fx@gnu.org>
parents:
diff changeset
1950 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
1951
Dave Love <fx@gnu.org>
parents:
diff changeset
1952 @kindex C-x v l
Dave Love <fx@gnu.org>
parents:
diff changeset
1953 @findex vc-print-log
Dave Love <fx@gnu.org>
parents:
diff changeset
1954 To view the detailed version control status and history of a file,
Dave Love <fx@gnu.org>
parents:
diff changeset
1955 type @kbd{C-x v l} (@code{vc-print-log}). It displays the history of
Dave Love <fx@gnu.org>
parents:
diff changeset
1956 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
1957 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
1958 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
1959
68540
b1e412bac8b7 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 68310
diff changeset
1960 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
1961 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
1962 to view diffs:
c9928598ea58 (VC Status): Document log-view mode.
Richard M. Stallman <rms@gnu.org>
parents: 67511
diff changeset
1963
c9928598ea58 (VC Status): Document log-view mode.
Richard M. Stallman <rms@gnu.org>
parents: 67511
diff changeset
1964 @table @kbd
c9928598ea58 (VC Status): Document log-view mode.
Richard M. Stallman <rms@gnu.org>
parents: 67511
diff changeset
1965 @item p
c9928598ea58 (VC Status): Document log-view mode.
Richard M. Stallman <rms@gnu.org>
parents: 67511
diff changeset
1966 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
1967 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
1968 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
1969 prefix argument is a repeat count.
c9928598ea58 (VC Status): Document log-view mode.
Richard M. Stallman <rms@gnu.org>
parents: 67511
diff changeset
1970
c9928598ea58 (VC Status): Document log-view mode.
Richard M. Stallman <rms@gnu.org>
parents: 67511
diff changeset
1971 @item n
c9928598ea58 (VC Status): Document log-view mode.
Richard M. Stallman <rms@gnu.org>
parents: 67511
diff changeset
1972 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
1973 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
1974 count.
c9928598ea58 (VC Status): Document log-view mode.
Richard M. Stallman <rms@gnu.org>
parents: 67511
diff changeset
1975
c9928598ea58 (VC Status): Document log-view mode.
Richard M. Stallman <rms@gnu.org>
parents: 67511
diff changeset
1976 @item P
c9928598ea58 (VC Status): Document log-view mode.
Richard M. Stallman <rms@gnu.org>
parents: 67511
diff changeset
1977 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
1978 are in the log buffer
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1979 @iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1980 (@pxref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}).
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1981 @end iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1982 @ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1983 (@pxref{VC Dired Mode}).
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1984 @end ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1985 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
1986 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
1987 files.
67652
c9928598ea58 (VC Status): Document log-view mode.
Richard M. Stallman <rms@gnu.org>
parents: 67511
diff changeset
1988
c9928598ea58 (VC Status): Document log-view mode.
Richard M. Stallman <rms@gnu.org>
parents: 67511
diff changeset
1989 @item N
c9928598ea58 (VC Status): Document log-view mode.
Richard M. Stallman <rms@gnu.org>
parents: 67511
diff changeset
1990 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
1991 in the log buffer
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1992 @iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1993 (@pxref{VC Dired Mode,,,emacs-xtra, Specialized Emacs Features}).
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1994 @end iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1995 @ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1996 (@pxref{VC Dired Mode}).
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1997 @end ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
1998 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
1999
05e4a3f8ac73 (VC Status): Put P and N near p and n.
Juri Linkov <juri@jurta.org>
parents: 67652
diff changeset
2000 @item f
05e4a3f8ac73 (VC Status): Put P and N near p and n.
Juri Linkov <juri@jurta.org>
parents: 67652
diff changeset
2001 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
2002 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
2003
05e4a3f8ac73 (VC Status): Put P and N near p and n.
Juri Linkov <juri@jurta.org>
parents: 67652
diff changeset
2004 @item d
05e4a3f8ac73 (VC Status): Put P and N near p and n.
Juri Linkov <juri@jurta.org>
parents: 67652
diff changeset
2005 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
2006 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
2007 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
2008 current line was committed.
67652
c9928598ea58 (VC Status): Document log-view mode.
Richard M. Stallman <rms@gnu.org>
parents: 67511
diff changeset
2009 @end table
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2010
Dave Love <fx@gnu.org>
parents:
diff changeset
2011 @node VC Undo
Dave Love <fx@gnu.org>
parents:
diff changeset
2012 @subsubsection Undoing Version Control Actions
Dave Love <fx@gnu.org>
parents:
diff changeset
2013
Dave Love <fx@gnu.org>
parents:
diff changeset
2014 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
2015 @item C-x v u
69612
cf3a4af06ad8 Various updates and clarifications in the VC chapter.
André Spiegel <spiegel@gnu.org>
parents: 69506
diff changeset
2016 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
2017 editing the file.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2018
Dave Love <fx@gnu.org>
parents:
diff changeset
2019 @item C-x v c
Dave Love <fx@gnu.org>
parents:
diff changeset
2020 Remove the last-entered change from the master for the visited file.
Dave Love <fx@gnu.org>
parents:
diff changeset
2021 This undoes your last check-in.
Dave Love <fx@gnu.org>
parents:
diff changeset
2022 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
2023
Dave Love <fx@gnu.org>
parents:
diff changeset
2024 @kindex C-x v u
Dave Love <fx@gnu.org>
parents:
diff changeset
2025 @findex vc-revert-buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
2026 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
2027 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
2028 (@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
2029 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
2030 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
2031 haven't made any changes with respect to the master version.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2032
Dave Love <fx@gnu.org>
parents:
diff changeset
2033 @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
2034 then decide not to change it.
Dave Love <fx@gnu.org>
parents:
diff changeset
2035
Dave Love <fx@gnu.org>
parents:
diff changeset
2036 @kindex C-x v c
Dave Love <fx@gnu.org>
parents:
diff changeset
2037 @findex vc-cancel-version
Dave Love <fx@gnu.org>
parents:
diff changeset
2038 To cancel a change that you already checked in, use @kbd{C-x v c}
Dave Love <fx@gnu.org>
parents:
diff changeset
2039 (@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
2040 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
2041 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
2042 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
2043 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
2044 precedes the version that is deleted).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2045
Dave Love <fx@gnu.org>
parents:
diff changeset
2046 If you answer @kbd{no}, VC keeps your changes in the buffer, and locks
Dave Love <fx@gnu.org>
parents:
diff changeset
2047 the file. The no-revert option is useful when you have checked in a
Dave Love <fx@gnu.org>
parents:
diff changeset
2048 change and then discover a trivial error in it; you can cancel the
Dave Love <fx@gnu.org>
parents:
diff changeset
2049 erroneous check-in, fix the error, and check the file in again.
Dave Love <fx@gnu.org>
parents:
diff changeset
2050
Dave Love <fx@gnu.org>
parents:
diff changeset
2051 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
2052 version control headers in the buffer instead
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2053 @iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2054 (@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}).
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2055 @end iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2056 @ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2057 (@pxref{Version Headers}).
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2058 @end ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2059 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
2060 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
2061 the headers properly for the new version number.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2062
Dave Love <fx@gnu.org>
parents:
diff changeset
2063 However, it is impossible to unexpand the RCS @samp{@w{$}Log$} header
Dave Love <fx@gnu.org>
parents:
diff changeset
2064 automatically. If you use that header feature, you have to unexpand it
Dave Love <fx@gnu.org>
parents:
diff changeset
2065 by hand---by deleting the entry for the version that you just canceled.
Dave Love <fx@gnu.org>
parents:
diff changeset
2066
Dave Love <fx@gnu.org>
parents:
diff changeset
2067 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
2068 work with it. To help you be careful, this command always requires
Dave Love <fx@gnu.org>
parents:
diff changeset
2069 confirmation with @kbd{yes}. Note also that this command is disabled
Dave Love <fx@gnu.org>
parents:
diff changeset
2070 under CVS, because canceling versions is very dangerous and discouraged
Dave Love <fx@gnu.org>
parents:
diff changeset
2071 with CVS.
Dave Love <fx@gnu.org>
parents:
diff changeset
2072
70445
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2073 @ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2074 @c vc1-xtra.texi needs extra level of lowering.
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2075 @lowersections
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2076 @include vc1-xtra.texi
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2077 @raisesections
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2078 @end ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2079
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2080 @node Branches
Dave Love <fx@gnu.org>
parents:
diff changeset
2081 @subsection Multiple Branches of a File
Dave Love <fx@gnu.org>
parents:
diff changeset
2082 @cindex branch (version control)
Dave Love <fx@gnu.org>
parents:
diff changeset
2083 @cindex trunk (version control)
Dave Love <fx@gnu.org>
parents:
diff changeset
2084
Dave Love <fx@gnu.org>
parents:
diff changeset
2085 One use of version control is to maintain multiple ``current''
Dave Love <fx@gnu.org>
parents:
diff changeset
2086 versions of a file. For example, you might have different versions of a
Dave Love <fx@gnu.org>
parents:
diff changeset
2087 program in which you are gradually adding various unfinished new
Dave Love <fx@gnu.org>
parents:
diff changeset
2088 features. Each such independent line of development is called a
Dave Love <fx@gnu.org>
parents:
diff changeset
2089 @dfn{branch}. VC allows you to create branches, switch between
Dave Love <fx@gnu.org>
parents:
diff changeset
2090 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
2091 Please note, however, that branches are not supported for SCCS.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2092
Dave Love <fx@gnu.org>
parents:
diff changeset
2093 A file's main line of development is usually called the @dfn{trunk}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2094 The versions on the trunk are normally numbered 1.1, 1.2, 1.3, etc. At
Dave Love <fx@gnu.org>
parents:
diff changeset
2095 any such version, you can start an independent branch. A branch
Dave Love <fx@gnu.org>
parents:
diff changeset
2096 starting at version 1.2 would have version number 1.2.1.1, and consecutive
Dave Love <fx@gnu.org>
parents:
diff changeset
2097 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
2098 and so on. If there is a second branch also starting at version 1.2, it
Dave Love <fx@gnu.org>
parents:
diff changeset
2099 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
2100
Dave Love <fx@gnu.org>
parents:
diff changeset
2101 @cindex head version
Dave Love <fx@gnu.org>
parents:
diff changeset
2102 If you omit the final component of a version number, that is called a
Dave Love <fx@gnu.org>
parents:
diff changeset
2103 @dfn{branch number}. It refers to the highest existing version on that
Dave Love <fx@gnu.org>
parents:
diff changeset
2104 branch---the @dfn{head version} of that branch. The branches in the
Dave Love <fx@gnu.org>
parents:
diff changeset
2105 example above have branch numbers 1.2.1 and 1.2.2.
Dave Love <fx@gnu.org>
parents:
diff changeset
2106
Dave Love <fx@gnu.org>
parents:
diff changeset
2107 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
2108 * Switching Branches:: How to get to another existing branch.
Dave Love <fx@gnu.org>
parents:
diff changeset
2109 * Creating Branches:: How to start a new branch.
Dave Love <fx@gnu.org>
parents:
diff changeset
2110 * Merging:: Transferring changes between branches.
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 49561
diff changeset
2111 * Multi-User Branching:: Multiple users working at multiple branches
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2112 in parallel.
Dave Love <fx@gnu.org>
parents:
diff changeset
2113 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
2114
Dave Love <fx@gnu.org>
parents:
diff changeset
2115 @node Switching Branches
Dave Love <fx@gnu.org>
parents:
diff changeset
2116 @subsubsection Switching between Branches
Dave Love <fx@gnu.org>
parents:
diff changeset
2117
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
2118 To switch between branches, type @kbd{C-u C-x v v} and specify the
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2119 version number you want to select. This version is then visited
Dave Love <fx@gnu.org>
parents:
diff changeset
2120 @emph{unlocked} (write-protected), so you can examine it before locking
Dave Love <fx@gnu.org>
parents:
diff changeset
2121 it. Switching branches in this way is allowed only when the file is not
Dave Love <fx@gnu.org>
parents:
diff changeset
2122 locked.
Dave Love <fx@gnu.org>
parents:
diff changeset
2123
Dave Love <fx@gnu.org>
parents:
diff changeset
2124 You can omit the minor version number, thus giving only the branch
Dave Love <fx@gnu.org>
parents:
diff changeset
2125 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
2126 only type @key{RET}, Emacs goes to the highest version on the trunk.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2127
Dave Love <fx@gnu.org>
parents:
diff changeset
2128 After you have switched to any branch (including the main branch), you
Dave Love <fx@gnu.org>
parents:
diff changeset
2129 stay on it for subsequent VC commands, until you explicitly select some
Dave Love <fx@gnu.org>
parents:
diff changeset
2130 other branch.
Dave Love <fx@gnu.org>
parents:
diff changeset
2131
Dave Love <fx@gnu.org>
parents:
diff changeset
2132 @node Creating Branches
Dave Love <fx@gnu.org>
parents:
diff changeset
2133 @subsubsection Creating New Branches
Dave Love <fx@gnu.org>
parents:
diff changeset
2134
Dave Love <fx@gnu.org>
parents:
diff changeset
2135 To create a new branch from a head version (one that is the latest in
Dave Love <fx@gnu.org>
parents:
diff changeset
2136 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
2137 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
2138 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
2139 specify the version number for the new version. You should specify a
Dave Love <fx@gnu.org>
parents:
diff changeset
2140 suitable branch number for a branch starting at the current version.
Dave Love <fx@gnu.org>
parents:
diff changeset
2141 For example, if the current version is 2.5, the branch number should be
Dave Love <fx@gnu.org>
parents:
diff changeset
2142 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
2143 that point.
Dave Love <fx@gnu.org>
parents:
diff changeset
2144
Dave Love <fx@gnu.org>
parents:
diff changeset
2145 To create a new branch at an older version (one that is no longer the
Dave Love <fx@gnu.org>
parents:
diff changeset
2146 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
2147 Branches}), then lock it with @kbd{C-x v v}. You'll be asked to
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2148 confirm, when you lock the old version, that you really mean to create a
Dave Love <fx@gnu.org>
parents:
diff changeset
2149 new branch---if you say no, you'll be offered a chance to lock the
Dave Love <fx@gnu.org>
parents:
diff changeset
2150 latest version instead.
Dave Love <fx@gnu.org>
parents:
diff changeset
2151
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
2152 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
2153 version. This automatically creates a new branch starting from the
Dave Love <fx@gnu.org>
parents:
diff changeset
2154 selected version. You need not specially request a new branch, because
Dave Love <fx@gnu.org>
parents:
diff changeset
2155 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
2156 of a branch.
Dave Love <fx@gnu.org>
parents:
diff changeset
2157
Dave Love <fx@gnu.org>
parents:
diff changeset
2158 After the branch is created, you ``stay'' on it. That means that
Dave Love <fx@gnu.org>
parents:
diff changeset
2159 subsequent check-ins create new versions on that branch. To leave the
Dave Love <fx@gnu.org>
parents:
diff changeset
2160 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
2161 v v}. To transfer changes from one branch to another, use the merge
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2162 command, described in the next section.
Dave Love <fx@gnu.org>
parents:
diff changeset
2163
Dave Love <fx@gnu.org>
parents:
diff changeset
2164 @node Merging
Dave Love <fx@gnu.org>
parents:
diff changeset
2165 @subsubsection Merging Branches
Dave Love <fx@gnu.org>
parents:
diff changeset
2166
Dave Love <fx@gnu.org>
parents:
diff changeset
2167 @cindex merging changes
Dave Love <fx@gnu.org>
parents:
diff changeset
2168 When you have finished the changes on a certain branch, you will
Dave Love <fx@gnu.org>
parents:
diff changeset
2169 often want to incorporate them into the file's main line of development
Dave Love <fx@gnu.org>
parents:
diff changeset
2170 (the trunk). This is not a trivial operation, because development might
Dave Love <fx@gnu.org>
parents:
diff changeset
2171 also have proceeded on the trunk, so that you must @dfn{merge} the
Dave Love <fx@gnu.org>
parents:
diff changeset
2172 changes into a file that has already been changed otherwise. VC allows
Dave Love <fx@gnu.org>
parents:
diff changeset
2173 you to do this (and other things) with the @code{vc-merge} command.
Dave Love <fx@gnu.org>
parents:
diff changeset
2174
Dave Love <fx@gnu.org>
parents:
diff changeset
2175 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
2176 @item C-x v m (vc-merge)
Dave Love <fx@gnu.org>
parents:
diff changeset
2177 Merge changes into the work file.
Dave Love <fx@gnu.org>
parents:
diff changeset
2178 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
2179
Dave Love <fx@gnu.org>
parents:
diff changeset
2180 @kindex C-x v m
Dave Love <fx@gnu.org>
parents:
diff changeset
2181 @findex vc-merge
Dave Love <fx@gnu.org>
parents:
diff changeset
2182 @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
2183 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
2184 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
2185 @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
2186 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
2187 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
2188 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
2189
d8c0e3d0f0aa VC section updated. Added a subsection on remote repositories,
André Spiegel <spiegel@gnu.org>
parents: 36327
diff changeset
2190 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
2191 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
2192 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
2193 merges them into the current version of the current file.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2194
Dave Love <fx@gnu.org>
parents:
diff changeset
2195 As an example, suppose that you have finished a certain feature on
Dave Love <fx@gnu.org>
parents:
diff changeset
2196 branch 1.3.1. In the meantime, development on the trunk has proceeded
Dave Love <fx@gnu.org>
parents:
diff changeset
2197 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
2198 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
2199 @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
2200 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
2201 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
2202 branch 1.3.1 (relative to version 1.3, where the branch started, up to
Dave Love <fx@gnu.org>
parents:
diff changeset
2203 the last version on the branch) and merges it into the current version
Dave Love <fx@gnu.org>
parents:
diff changeset
2204 of the work file. You can now check in the changed file, thus creating
Dave Love <fx@gnu.org>
parents:
diff changeset
2205 version 1.6 containing the changes from the branch.
Dave Love <fx@gnu.org>
parents:
diff changeset
2206
Dave Love <fx@gnu.org>
parents:
diff changeset
2207 It is possible to do further editing after merging the branch, before
Dave Love <fx@gnu.org>
parents:
diff changeset
2208 the next check-in. But it is usually wiser to check in the merged
Dave Love <fx@gnu.org>
parents:
diff changeset
2209 version, then lock it and make the further changes. This will keep
Dave Love <fx@gnu.org>
parents:
diff changeset
2210 a better record of the history of changes.
Dave Love <fx@gnu.org>
parents:
diff changeset
2211
Dave Love <fx@gnu.org>
parents:
diff changeset
2212 @cindex conflicts
Dave Love <fx@gnu.org>
parents:
diff changeset
2213 @cindex resolving conflicts
Dave Love <fx@gnu.org>
parents:
diff changeset
2214 When you merge changes into a file that has itself been modified, the
Dave Love <fx@gnu.org>
parents:
diff changeset
2215 changes might overlap. We call this situation a @dfn{conflict}, and
Dave Love <fx@gnu.org>
parents:
diff changeset
2216 reconciling the conflicting changes is called @dfn{resolving a
Dave Love <fx@gnu.org>
parents:
diff changeset
2217 conflict}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2218
Dave Love <fx@gnu.org>
parents:
diff changeset
2219 Whenever conflicts occur during merging, VC detects them, tells you
Dave Love <fx@gnu.org>
parents:
diff changeset
2220 about them in the echo area, and asks whether you want help in merging.
Dave Love <fx@gnu.org>
parents:
diff changeset
2221 If you say yes, it starts an Ediff session (@pxref{Top,
Dave Love <fx@gnu.org>
parents:
diff changeset
2222 Ediff, Ediff, ediff, The Ediff Manual}).
Dave Love <fx@gnu.org>
parents:
diff changeset
2223
Dave Love <fx@gnu.org>
parents:
diff changeset
2224 If you say no, the conflicting changes are both inserted into the
Dave Love <fx@gnu.org>
parents:
diff changeset
2225 file, surrounded by @dfn{conflict markers}. The example below shows how
Dave Love <fx@gnu.org>
parents:
diff changeset
2226 a conflict region looks; the file is called @samp{name} and the current
Dave Love <fx@gnu.org>
parents:
diff changeset
2227 master file version with user B's changes in it is 1.11.
Dave Love <fx@gnu.org>
parents:
diff changeset
2228
Dave Love <fx@gnu.org>
parents:
diff changeset
2229 @c @w here is so CVS won't think this is a conflict.
Dave Love <fx@gnu.org>
parents:
diff changeset
2230 @smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
2231 @group
Dave Love <fx@gnu.org>
parents:
diff changeset
2232 @w{<}<<<<<< name
Dave Love <fx@gnu.org>
parents:
diff changeset
2233 @var{User A's version}
Dave Love <fx@gnu.org>
parents:
diff changeset
2234 =======
Dave Love <fx@gnu.org>
parents:
diff changeset
2235 @var{User B's version}
Dave Love <fx@gnu.org>
parents:
diff changeset
2236 @w{>}>>>>>> 1.11
Dave Love <fx@gnu.org>
parents:
diff changeset
2237 @end group
Dave Love <fx@gnu.org>
parents:
diff changeset
2238 @end smallexample
Dave Love <fx@gnu.org>
parents:
diff changeset
2239
Dave Love <fx@gnu.org>
parents:
diff changeset
2240 @cindex vc-resolve-conflicts
Dave Love <fx@gnu.org>
parents:
diff changeset
2241 Then you can resolve the conflicts by editing the file manually. Or
Dave Love <fx@gnu.org>
parents:
diff changeset
2242 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
2243 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
2244 check in the merged version afterwards.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2245
Dave Love <fx@gnu.org>
parents:
diff changeset
2246 @node Multi-User Branching
Dave Love <fx@gnu.org>
parents:
diff changeset
2247 @subsubsection Multi-User Branching
Dave Love <fx@gnu.org>
parents:
diff changeset
2248
Dave Love <fx@gnu.org>
parents:
diff changeset
2249 It is often useful for multiple developers to work simultaneously on
Dave Love <fx@gnu.org>
parents:
diff changeset
2250 different branches of a file. CVS allows this by default; for RCS, it
Dave Love <fx@gnu.org>
parents:
diff changeset
2251 is possible if you create multiple source directories. Each source
Dave Love <fx@gnu.org>
parents:
diff changeset
2252 directory should have a link named @file{RCS} which points to a common
Dave Love <fx@gnu.org>
parents:
diff changeset
2253 directory of RCS master files. Then each source directory can have its
Dave Love <fx@gnu.org>
parents:
diff changeset
2254 own choice of selected versions, but all share the same common RCS
Dave Love <fx@gnu.org>
parents:
diff changeset
2255 records.
Dave Love <fx@gnu.org>
parents:
diff changeset
2256
Dave Love <fx@gnu.org>
parents:
diff changeset
2257 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
2258 source files contain RCS version headers
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2259 @iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2260 (@pxref{Version Headers,,,emacs-xtra, Specialized Emacs Features}).
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2261 @end iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2262 @ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2263 (@pxref{Version Headers}).
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2264 @end ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2265 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
2266 number is present in the work file.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2267
Dave Love <fx@gnu.org>
parents:
diff changeset
2268 If the files do not have version headers, you must instead tell Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
2269 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
2270 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
2271 branch number. This ensures that Emacs knows which branch it is using
Dave Love <fx@gnu.org>
parents:
diff changeset
2272 during this particular editing session.
Dave Love <fx@gnu.org>
parents:
diff changeset
2273
70445
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2274 @ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2275 @include vc2-xtra.texi
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2276 @end ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2277
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2278 @node Directories
Dave Love <fx@gnu.org>
parents:
diff changeset
2279 @section File Directories
Dave Love <fx@gnu.org>
parents:
diff changeset
2280
Dave Love <fx@gnu.org>
parents:
diff changeset
2281 @cindex file directory
Dave Love <fx@gnu.org>
parents:
diff changeset
2282 @cindex directory listing
Dave Love <fx@gnu.org>
parents:
diff changeset
2283 The file system groups files into @dfn{directories}. A @dfn{directory
Dave Love <fx@gnu.org>
parents:
diff changeset
2284 listing} is a list of all the files in a directory. Emacs provides
Dave Love <fx@gnu.org>
parents:
diff changeset
2285 commands to create and delete directories, and to make directory
Dave Love <fx@gnu.org>
parents:
diff changeset
2286 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
2287 dates, and authors included). Emacs also includes a directory browser
b1e412bac8b7 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 68310
diff changeset
2288 feature called Dired; see @ref{Dired}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2289
Dave Love <fx@gnu.org>
parents:
diff changeset
2290 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
2291 @item C-x C-d @var{dir-or-pattern} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
2292 Display a brief directory listing (@code{list-directory}).
Dave Love <fx@gnu.org>
parents:
diff changeset
2293 @item C-u C-x C-d @var{dir-or-pattern} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
2294 Display a verbose directory listing.
Dave Love <fx@gnu.org>
parents:
diff changeset
2295 @item M-x make-directory @key{RET} @var{dirname} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
2296 Create a new directory named @var{dirname}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2297 @item M-x delete-directory @key{RET} @var{dirname} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
2298 Delete the directory named @var{dirname}. It must be empty,
Dave Love <fx@gnu.org>
parents:
diff changeset
2299 or you get an error.
Dave Love <fx@gnu.org>
parents:
diff changeset
2300 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
2301
Dave Love <fx@gnu.org>
parents:
diff changeset
2302 @findex list-directory
Dave Love <fx@gnu.org>
parents:
diff changeset
2303 @kindex C-x C-d
Dave Love <fx@gnu.org>
parents:
diff changeset
2304 The command to display a directory listing is @kbd{C-x C-d}
Dave Love <fx@gnu.org>
parents:
diff changeset
2305 (@code{list-directory}). It reads using the minibuffer a file name
Dave Love <fx@gnu.org>
parents:
diff changeset
2306 which is either a directory to be listed or a wildcard-containing
Dave Love <fx@gnu.org>
parents:
diff changeset
2307 pattern for the files to be listed. For example,
Dave Love <fx@gnu.org>
parents:
diff changeset
2308
Dave Love <fx@gnu.org>
parents:
diff changeset
2309 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2310 C-x C-d /u2/emacs/etc @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
2311 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2312
Dave Love <fx@gnu.org>
parents:
diff changeset
2313 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
2314 lists all the files in directory @file{/u2/emacs/etc}. Here is an
Dave Love <fx@gnu.org>
parents:
diff changeset
2315 example of specifying a file name pattern:
Dave Love <fx@gnu.org>
parents:
diff changeset
2316
Dave Love <fx@gnu.org>
parents:
diff changeset
2317 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2318 C-x C-d /u2/emacs/src/*.c @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
2319 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2320
38870
d44abb4e68b2 Don't use "print" for displaying a message.
Richard M. Stallman <rms@gnu.org>
parents: 38768
diff changeset
2321 Normally, @kbd{C-x C-d} displays a brief directory listing containing
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2322 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
2323 make a verbose listing including sizes, dates, and owners (like
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2324 @samp{ls -l}).
Dave Love <fx@gnu.org>
parents:
diff changeset
2325
Dave Love <fx@gnu.org>
parents:
diff changeset
2326 @vindex list-directory-brief-switches
Dave Love <fx@gnu.org>
parents:
diff changeset
2327 @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
2328 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
2329 @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
2330 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
2331 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
2332 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
2333 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
2334 default).
895fd595b5fb Explain that $FOO stands for itself if FOO is not defined.
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
2335
895fd595b5fb Explain that $FOO stands for itself if FOO is not defined.
Richard M. Stallman <rms@gnu.org>
parents: 45979
diff changeset
2336 @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
2337 @vindex directory-free-space-args
68540
b1e412bac8b7 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 68310
diff changeset
2338 In verbose directory listings, Emacs adds information about the
b1e412bac8b7 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 68310
diff changeset
2339 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
2340 this, it runs the program specified by
b1e412bac8b7 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 68310
diff changeset
2341 @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
2342 @code{directory-free-space-args}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2343
Dave Love <fx@gnu.org>
parents:
diff changeset
2344 @node Comparing Files
Dave Love <fx@gnu.org>
parents:
diff changeset
2345 @section Comparing Files
Dave Love <fx@gnu.org>
parents:
diff changeset
2346 @cindex comparing files
Dave Love <fx@gnu.org>
parents:
diff changeset
2347
Dave Love <fx@gnu.org>
parents:
diff changeset
2348 @findex diff
Dave Love <fx@gnu.org>
parents:
diff changeset
2349 @vindex diff-switches
Dave Love <fx@gnu.org>
parents:
diff changeset
2350 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
2351 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
2352 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
2353 @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
2354 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
2355 @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
2356 information about @command{diff} output formats.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2357
Dave Love <fx@gnu.org>
parents:
diff changeset
2358 @findex diff-backup
Dave Love <fx@gnu.org>
parents:
diff changeset
2359 The command @kbd{M-x diff-backup} compares a specified file with its most
Dave Love <fx@gnu.org>
parents:
diff changeset
2360 recent backup. If you specify the name of a backup file,
Dave Love <fx@gnu.org>
parents:
diff changeset
2361 @code{diff-backup} compares it with the source file that it is a backup
Dave Love <fx@gnu.org>
parents:
diff changeset
2362 of.
Dave Love <fx@gnu.org>
parents:
diff changeset
2363
Dave Love <fx@gnu.org>
parents:
diff changeset
2364 @findex compare-windows
64828
7959083b57a2 (Comparing Files): Clarify compare-windows.
Richard M. Stallman <rms@gnu.org>
parents: 64591
diff changeset
2365 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
2366 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
2367 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
2368 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
2369 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
2370 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
2371 Then the command exits.
7959083b57a2 (Comparing Files): Clarify compare-windows.
Richard M. Stallman <rms@gnu.org>
parents: 64591
diff changeset
2372
7959083b57a2 (Comparing Files): Clarify compare-windows.
Richard M. Stallman <rms@gnu.org>
parents: 64591
diff changeset
2373 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
2374 the command starts, @kbd{M-x compare-windows} tries heuristically to
b1e412bac8b7 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 68310
diff changeset
2375 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
2376 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
2377 skips one matching range or finds the start of another.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2378
Dave Love <fx@gnu.org>
parents:
diff changeset
2379 @vindex compare-ignore-case
60792
4fbe0af1e69a (Visiting): Document large-file-warning-threshold.
Richard M. Stallman <rms@gnu.org>
parents: 60426
diff changeset
2380 @vindex compare-ignore-whitespace
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2381 With a numeric argument, @code{compare-windows} ignores changes in
Dave Love <fx@gnu.org>
parents:
diff changeset
2382 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
2383 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
2384 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
2385 @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
2386 prefix argument turns that off.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2387
31076
9c00fd66ec24 (File Shadowing): New.
Dave Love <fx@gnu.org>
parents: 31043
diff changeset
2388 @cindex Smerge mode
9c00fd66ec24 (File Shadowing): New.
Dave Love <fx@gnu.org>
parents: 31043
diff changeset
2389 @findex smerge-mode
9c00fd66ec24 (File Shadowing): New.
Dave Love <fx@gnu.org>
parents: 31043
diff changeset
2390 @cindex failed merges
9c00fd66ec24 (File Shadowing): New.
Dave Love <fx@gnu.org>
parents: 31043
diff changeset
2391 @cindex merges, failed
36274
91f2160d4468 Remove two more redundant index entries.
Eli Zaretskii <eliz@gnu.org>
parents: 36263
diff changeset
2392 @cindex comparing 3 files (@code{diff3})
36136
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2393 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
2394 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
2395 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
2396 ``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
2397 mode provides commands to resolve conflicts by selecting specific
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2398 changes.
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2399
70445
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2400 @iftex
70472
8566e3f340ec msdog.texi (Microsoft Windows):
Eli Zaretskii <eliz@gnu.org>
parents: 70445
diff changeset
2401 @xref{Emerge,,, emacs-xtra, Specialized Emacs Features},
70445
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2402 @end iftex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2403 @ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2404 @xref{Emerge},
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2405 @end ifnottex
e8ca81ffe2d5 (Backup, Version Control, VC Concepts)
Eli Zaretskii <eliz@gnu.org>
parents: 70409
diff changeset
2406 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
2407 merging files.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2408
70366
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2409 @node Diff Mode
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2410 @section Diff Mode
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2411 @cindex Diff mode
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2412 @findex diff-mode
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2413 @cindex patches, editing
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2414
70409
be2fb717fb5d (Diff Mode): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 70393
diff changeset
2415 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
2416 useful for editing patches and comparisons produced by the
be2fb717fb5d (Diff Mode): Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 70393
diff changeset
2417 @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
2418 diff-mode}.
70366
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2419
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2420 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
2421 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
2422 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
2423 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
2424 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
2425 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
2426 manipulate and apply parts of patches:
70366
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2427
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2428 @table @kbd
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2429 @item M-n
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2430 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
2431
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2432 @item M-p
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2433 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
2434
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2435 @item M-@}
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2436 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
2437 (@code{diff-file-next}).
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2438
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2439 @item M-@{
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2440 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
2441 (@code{diff-file-prev}).
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2442
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2443 @item M-k
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2444 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
2445
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2446 @item M-K
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2447 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
2448 (@code{diff-file-kill}).
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2449
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2450 @item C-c C-a
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2451 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
2452 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
2453
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2454 @item C-c C-c
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2455 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
2456
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2457 @item C-c C-e
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2458 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
2459 @xref{Top, Ediff, Ediff, ediff, The Ediff Manual}.
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2460
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2461 @item C-c C-n
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2462 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
2463 @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
2464 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
2465 use @kbd{C-x n w}.
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2466
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2467 @item C-c C-r
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2468 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
2469 (@code{diff-reverse-direction}).
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2470
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2471 @item C-c C-s
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2472 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
2473 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
2474
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2475 @item C-c C-u
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2476 Convert the entire buffer to unified format
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2477 (@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
2478 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
2479 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
2480
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2481 @item C-c C-w
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2482 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
2483 (@code{diff-refine-hunk}).
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2484 @end table
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2485
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2486 @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
2487 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
2488 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
2489 by the patch.
08f6a4d7af40 (Diff Mode): Node moved here.
Richard M. Stallman <rms@gnu.org>
parents: 69945
diff changeset
2490
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2491 @node Misc File Ops
Dave Love <fx@gnu.org>
parents:
diff changeset
2492 @section Miscellaneous File Operations
Dave Love <fx@gnu.org>
parents:
diff changeset
2493
Dave Love <fx@gnu.org>
parents:
diff changeset
2494 Emacs has commands for performing many other operations on files.
Dave Love <fx@gnu.org>
parents:
diff changeset
2495 All operate on one file; they do not accept wildcard file names.
Dave Love <fx@gnu.org>
parents:
diff changeset
2496
Dave Love <fx@gnu.org>
parents:
diff changeset
2497 @findex view-file
Dave Love <fx@gnu.org>
parents:
diff changeset
2498 @cindex viewing
Dave Love <fx@gnu.org>
parents:
diff changeset
2499 @cindex View mode
Dave Love <fx@gnu.org>
parents:
diff changeset
2500 @cindex mode, View
Dave Love <fx@gnu.org>
parents:
diff changeset
2501 @kbd{M-x view-file} allows you to scan or read a file by sequential
Dave Love <fx@gnu.org>
parents:
diff changeset
2502 screenfuls. It reads a file name argument using the minibuffer. After
Dave Love <fx@gnu.org>
parents:
diff changeset
2503 reading the file into an Emacs buffer, @code{view-file} displays the
Dave Love <fx@gnu.org>
parents:
diff changeset
2504 beginning. You can then type @key{SPC} to scroll forward one windowful,
Dave Love <fx@gnu.org>
parents:
diff changeset
2505 or @key{DEL} to scroll backward. Various other commands are provided
Dave Love <fx@gnu.org>
parents:
diff changeset
2506 for moving around in the file, but none for changing it; type @kbd{?}
Dave Love <fx@gnu.org>
parents:
diff changeset
2507 while viewing for a list of them. They are mostly the same as normal
Dave Love <fx@gnu.org>
parents:
diff changeset
2508 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
2509 The commands for viewing are defined by a special minor mode called View
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2510 mode.
Dave Love <fx@gnu.org>
parents:
diff changeset
2511
Dave Love <fx@gnu.org>
parents:
diff changeset
2512 A related command, @kbd{M-x view-buffer}, views a buffer already present
Dave Love <fx@gnu.org>
parents:
diff changeset
2513 in Emacs. @xref{Misc Buffer}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2514
38739
7055d897b6bb Many minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 38310
diff changeset
2515 @kindex C-x i
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2516 @findex insert-file
38739
7055d897b6bb Many minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 38310
diff changeset
2517 @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
2518 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
2519 leaving point unchanged before the contents and the mark after them.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2520
74500
fc3f19833659 (Misc File Ops): Document insert-file-literally.
Eli Zaretskii <eliz@gnu.org>
parents: 72842
diff changeset
2521 @findex insert-file-literally
77029
6e83091412c3 (Misc File Ops): Rewrite description of insert-file-literally.
Chong Yidong <cyd@stupidchicken.com>
parents: 75348
diff changeset
2522 @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
2523 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
2524 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
2525 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
2526 (@pxref{Visiting}).
74500
fc3f19833659 (Misc File Ops): Document insert-file-literally.
Eli Zaretskii <eliz@gnu.org>
parents: 72842
diff changeset
2527
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2528 @findex write-region
Dave Love <fx@gnu.org>
parents:
diff changeset
2529 @kbd{M-x write-region} is the inverse of @kbd{M-x insert-file}; it
Dave Love <fx@gnu.org>
parents:
diff changeset
2530 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
2531 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
2532 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
2533 @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
2534 as saving files; see @ref{Customize Save}.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2535
Dave Love <fx@gnu.org>
parents:
diff changeset
2536 @findex delete-file
Dave Love <fx@gnu.org>
parents:
diff changeset
2537 @cindex deletion (of files)
Dave Love <fx@gnu.org>
parents:
diff changeset
2538 @kbd{M-x delete-file} deletes the specified file, like the @code{rm}
Dave Love <fx@gnu.org>
parents:
diff changeset
2539 command in the shell. If you are deleting many files in one directory, it
Dave Love <fx@gnu.org>
parents:
diff changeset
2540 may be more convenient to use Dired (@pxref{Dired}).
Dave Love <fx@gnu.org>
parents:
diff changeset
2541
Dave Love <fx@gnu.org>
parents:
diff changeset
2542 @findex rename-file
Dave Love <fx@gnu.org>
parents:
diff changeset
2543 @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
2544 the minibuffer, then renames file @var{old} as @var{new}. If the file name
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2545 @var{new} already exists, you must confirm with @kbd{yes} or renaming is not
Dave Love <fx@gnu.org>
parents:
diff changeset
2546 done; this is because renaming causes the old meaning of the name @var{new}
Dave Love <fx@gnu.org>
parents:
diff changeset
2547 to be lost. If @var{old} and @var{new} are on different file systems, the
Dave Love <fx@gnu.org>
parents:
diff changeset
2548 file @var{old} is copied and deleted.
Dave Love <fx@gnu.org>
parents:
diff changeset
2549
60792
4fbe0af1e69a (Visiting): Document large-file-warning-threshold.
Richard M. Stallman <rms@gnu.org>
parents: 60426
diff changeset
2550 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
2551 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
2552 @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
2553 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
2554 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
2555 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
2556
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2557 @findex add-name-to-file
38739
7055d897b6bb Many minor cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 38310
diff changeset
2558 @cindex hard links (creation)
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2559 The similar command @kbd{M-x add-name-to-file} is used to add an
Dave Love <fx@gnu.org>
parents:
diff changeset
2560 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
2561 The new name is created as a ``hard link'' to the existing file.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2562 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
2563 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
2564 file system. On MS-DOS, it works by copying the file.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2565
Dave Love <fx@gnu.org>
parents:
diff changeset
2566 @findex copy-file
Dave Love <fx@gnu.org>
parents:
diff changeset
2567 @cindex copying files
60792
4fbe0af1e69a (Visiting): Document large-file-warning-threshold.
Richard M. Stallman <rms@gnu.org>
parents: 60426
diff changeset
2568 @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
2569 named @var{new} with the same contents.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2570
Dave Love <fx@gnu.org>
parents:
diff changeset
2571 @findex make-symbolic-link
52575
3a79db508c6c (File Aliases, Misc File Ops): Add @cindex entries.
Richard M. Stallman <rms@gnu.org>
parents: 52401
diff changeset
2572 @cindex symbolic links (creation)
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2573 @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
2574 @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
2575 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
2576 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
2577 @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
2578 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
2579 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
2580 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
2581
4fbe0af1e69a (Visiting): Document large-file-warning-threshold.
Richard M. Stallman <rms@gnu.org>
parents: 60426
diff changeset
2582 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
2583 support them, this command is not defined.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2584
Dave Love <fx@gnu.org>
parents:
diff changeset
2585 @node Compressed Files
Dave Love <fx@gnu.org>
parents:
diff changeset
2586 @section Accessing Compressed Files
Dave Love <fx@gnu.org>
parents:
diff changeset
2587 @cindex compression
Dave Love <fx@gnu.org>
parents:
diff changeset
2588 @cindex uncompression
Dave Love <fx@gnu.org>
parents:
diff changeset
2589 @cindex Auto Compression mode
Dave Love <fx@gnu.org>
parents:
diff changeset
2590 @cindex mode, Auto Compression
Dave Love <fx@gnu.org>
parents:
diff changeset
2591 @pindex gzip
Dave Love <fx@gnu.org>
parents:
diff changeset
2592
61952
7f9d1d01d274 (Compressed Files): Auto Compression normally enabled.
Richard M. Stallman <rms@gnu.org>
parents: 61847
diff changeset
2593 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
2594 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
2595 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
2596 names ending in @samp{.gz} indicate a file compressed with
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2597 @code{gzip}. Other endings indicate other compression programs.
Dave Love <fx@gnu.org>
parents:
diff changeset
2598
Dave Love <fx@gnu.org>
parents:
diff changeset
2599 Automatic uncompression and compression apply to all the operations in
Dave Love <fx@gnu.org>
parents:
diff changeset
2600 which Emacs uses the contents of a file. This includes visiting it,
Dave Love <fx@gnu.org>
parents:
diff changeset
2601 saving it, inserting its contents into a buffer, loading it, and byte
Dave Love <fx@gnu.org>
parents:
diff changeset
2602 compiling it.
Dave Love <fx@gnu.org>
parents:
diff changeset
2603
61952
7f9d1d01d274 (Compressed Files): Auto Compression normally enabled.
Richard M. Stallman <rms@gnu.org>
parents: 61847
diff changeset
2604 @findex auto-compression-mode
7f9d1d01d274 (Compressed Files): Auto Compression normally enabled.
Richard M. Stallman <rms@gnu.org>
parents: 61847
diff changeset
2605 @vindex auto-compression-mode
7f9d1d01d274 (Compressed Files): Auto Compression normally enabled.
Richard M. Stallman <rms@gnu.org>
parents: 61847
diff changeset
2606 To disable this feature, type the command @kbd{M-x
70483
1673f96b0b2d Fix spelling errors.
Eli Zaretskii <eliz@gnu.org>
parents: 70472
diff changeset
2607 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
2608 customizing the variable @code{auto-compression-mode}.
7f9d1d01d274 (Compressed Files): Auto Compression normally enabled.
Richard M. Stallman <rms@gnu.org>
parents: 61847
diff changeset
2609
28123
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2610 @node File Archives
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2611 @section File Archives
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2612 @cindex mode, tar
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2613 @cindex Tar mode
36274
91f2160d4468 Remove two more redundant index entries.
Eli Zaretskii <eliz@gnu.org>
parents: 36263
diff changeset
2614 @cindex file archives
29683
324386e590b7 (File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents: 29556
diff changeset
2615
36136
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2616 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
2617 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
2618 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
2619 (@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
2620 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
2621 However, not all Dired commands are available in Tar mode.
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2622
68540
b1e412bac8b7 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 68310
diff changeset
2623 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
2624 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
2625 @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
2626
36385
d7ca85bd6906 Clean up recent VC updates.
Richard M. Stallman <rms@gnu.org>
parents: 36360
diff changeset
2627 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
2628 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
2629 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
2630 @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
2631 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
2632 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
2633 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
2634 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
2635 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
2636 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
2637
324386e590b7 (File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents: 29556
diff changeset
2638 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
2639 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
2640
324386e590b7 (File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents: 29556
diff changeset
2641 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
2642 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
2643 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
2644 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
2645
324386e590b7 (File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents: 29556
diff changeset
2646 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
2647 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
2648
36136
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2649 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
2650 the archives directly. However, accessing compressed archives
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2651 requires the appropriate uncompression program.
31076
9c00fd66ec24 (File Shadowing): New.
Dave Love <fx@gnu.org>
parents: 31043
diff changeset
2652
28123
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2653 @cindex Archive mode
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2654 @cindex mode, archive
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2655 @cindex @code{arc}
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2656 @cindex @code{jar}
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2657 @cindex @code{zip}
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2658 @cindex @code{lzh}
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2659 @cindex @code{zoo}
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2660 @pindex arc
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2661 @pindex jar
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2662 @pindex zip
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2663 @pindex lzh
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2664 @pindex zoo
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2665 @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
2666 @cindex unzip archives
324386e590b7 (File Archives): Remove redundant index entries. Add some more Tar
Eli Zaretskii <eliz@gnu.org>
parents: 29556
diff changeset
2667 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
2668 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
2669 @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
2670 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
2671 self-extracting executables.
36136
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2672
39263
343d48d4e64c Spelling corrections.
Richard M. Stallman <rms@gnu.org>
parents: 39163
diff changeset
2673 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
2674 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
2675 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
2676 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
2677 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
2678 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
2679 owner, are supported only for some of the archive formats.
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2680
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2681 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
2682 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
2683 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
2684 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
2685 extract or manipulate the subfiles in the archive.
28123
6e2e72ee55a6 (Compressed Files): Note custom option.
Dave Love <fx@gnu.org>
parents: 26105
diff changeset
2686
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2687 @node Remote Files
Dave Love <fx@gnu.org>
parents:
diff changeset
2688 @section Remote Files
Dave Love <fx@gnu.org>
parents:
diff changeset
2689
45892
58c783d19649 @node{Remote Files}: Mention Tramp.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 44717
diff changeset
2690 @cindex Tramp
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2691 @cindex FTP
Dave Love <fx@gnu.org>
parents:
diff changeset
2692 @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
2693 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
2694 syntax:
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2695
Dave Love <fx@gnu.org>
parents:
diff changeset
2696 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
2697 @group
Dave Love <fx@gnu.org>
parents:
diff changeset
2698 /@var{host}:@var{filename}
Dave Love <fx@gnu.org>
parents:
diff changeset
2699 /@var{user}@@@var{host}:@var{filename}
26105
c881de80a22b Mention vc-ignore-vc-files.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2700 /@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
2701 /@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
2702 /@var{method}:@var{user}@@@var{host}#@var{port}:@var{filename}
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2703 @end group
Dave Love <fx@gnu.org>
parents:
diff changeset
2704 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
2705
Dave Love <fx@gnu.org>
parents:
diff changeset
2706 @noindent
59886
c76d899e9718 (File Names): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 59798
diff changeset
2707 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
2708 remote-login program such as @command{ssh}, @command{rlogin}, or
c76d899e9718 (File Names): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 59798
diff changeset
2709 @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
2710 method to use---for example,
46384
ada0f3c60c22 Minor cleanup.
Richard M. Stallman <rms@gnu.org>
parents: 46346
diff changeset
2711 @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
2712 @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
2713 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
2714 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
2715
49f06e689a20 * files.texi (Remote Files): Explain new unified file name synatx.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 46215
diff changeset
2716 @enumerate
49f06e689a20 * files.texi (Remote Files): Explain new unified file name synatx.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 46215
diff changeset
2717 @item
59886
c76d899e9718 (File Names): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 59798
diff changeset
2718 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
2719 FTP.
46346
49f06e689a20 * files.texi (Remote Files): Explain new unified file name synatx.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 46215
diff changeset
2720 @item
59886
c76d899e9718 (File Names): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 59798
diff changeset
2721 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
2722 FTP.
46346
49f06e689a20 * files.texi (Remote Files): Explain new unified file name synatx.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 46215
diff changeset
2723 @item
59886
c76d899e9718 (File Names): Clarify.
Richard M. Stallman <rms@gnu.org>
parents: 59798
diff changeset
2724 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
2725 @end enumerate
45892
58c783d19649 @node{Remote Files}: Mention Tramp.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 44717
diff changeset
2726
58c783d19649 @node{Remote Files}: Mention Tramp.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 44717
diff changeset
2727 @noindent
46346
49f06e689a20 * files.texi (Remote Files): Explain new unified file name synatx.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 46215
diff changeset
2728 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
2729 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
2730 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
2731 @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
2732
49f06e689a20 * files.texi (Remote Files): Explain new unified file name synatx.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 46215
diff changeset
2733 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
2734 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
2735 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
2736 @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
2737 port.
45892
58c783d19649 @node{Remote Files}: Mention Tramp.
Kai Großjohann <kgrossjo@eu.uu.net>
parents: 44717
diff changeset
2738
35908
4ba2a6029c03 (Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents: 35731
diff changeset
2739 @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
2740 @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
2741 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
2742 @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
2743
44717
1fdf19dbc2e8 (Auto Save Files): Mention auto-save-file-name-transforms.
Glenn Morris <rgm@gnu.org>
parents: 44588
diff changeset
2744 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
2745 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
2746 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
2747
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2748 @cindex ange-ftp
Dave Love <fx@gnu.org>
parents:
diff changeset
2749 @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
2750 @cindex user name for remote file access
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2751 Normally, if you do not specify a user name in a remote file name,
Dave Love <fx@gnu.org>
parents:
diff changeset
2752 that means to use your own user name. But if you set the variable
Dave Love <fx@gnu.org>
parents:
diff changeset
2753 @code{ange-ftp-default-user} to a string, that string is used instead.
Dave Love <fx@gnu.org>
parents:
diff changeset
2754
35908
4ba2a6029c03 (Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents: 35731
diff changeset
2755 @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
2756 @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
2757 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
2758 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
2759 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
2760 @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
2761 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
2762 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
2763 @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
2764 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
2765
4ba2a6029c03 (Remote Files): Explain how to use ange-ftp behind firewalls. Add a
Eli Zaretskii <eliz@gnu.org>
parents: 35731
diff changeset
2766 @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
2767 @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
2768 @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
2769 @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
2770 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
2771 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
2772 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
2773 target files @emph{are} accessible, and whose FTP server supports
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2774 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
2775 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
2776 variable @code{ange-ftp-gateway-host}, and set
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2777 @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
2778 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
2779 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
2780 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
2781
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2782 @vindex file-name-handler-alist
36136
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2783 @cindex disabling remote files
26105
c881de80a22b Mention vc-ignore-vc-files.
Dave Love <fx@gnu.org>
parents: 25829
diff changeset
2784 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
2785 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
2786 @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
2787 @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
2788 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
2789 File Names}).
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2790
Dave Love <fx@gnu.org>
parents:
diff changeset
2791 @node Quoted File Names
Dave Love <fx@gnu.org>
parents:
diff changeset
2792 @section Quoted File Names
Dave Love <fx@gnu.org>
parents:
diff changeset
2793
Dave Love <fx@gnu.org>
parents:
diff changeset
2794 @cindex quoting file names
64591
c502137f8bb7 (Quoted File Names): Add index entry.
Eli Zaretskii <eliz@gnu.org>
parents: 64493
diff changeset
2795 @cindex file names, quote special characters
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2796 You can @dfn{quote} an absolute file name to prevent special
Dave Love <fx@gnu.org>
parents:
diff changeset
2797 characters and syntax in it from having their special effects.
Dave Love <fx@gnu.org>
parents:
diff changeset
2798 The way to do this is to add @samp{/:} at the beginning.
Dave Love <fx@gnu.org>
parents:
diff changeset
2799
Dave Love <fx@gnu.org>
parents:
diff changeset
2800 For example, you can quote a local file name which appears remote, to
Dave Love <fx@gnu.org>
parents:
diff changeset
2801 prevent it from being treated as a remote file name. Thus, if you have
Dave Love <fx@gnu.org>
parents:
diff changeset
2802 a directory named @file{/foo:} and a file named @file{bar} in it, you
Dave Love <fx@gnu.org>
parents:
diff changeset
2803 can refer to that file in Emacs as @samp{/:/foo:/bar}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2804
Dave Love <fx@gnu.org>
parents:
diff changeset
2805 @samp{/:} can also prevent @samp{~} from being treated as a special
Dave Love <fx@gnu.org>
parents:
diff changeset
2806 character for a user's home directory. For example, @file{/:/tmp/~hack}
Dave Love <fx@gnu.org>
parents:
diff changeset
2807 refers to a file whose name is @file{~hack} in directory @file{/tmp}.
Dave Love <fx@gnu.org>
parents:
diff changeset
2808
44143
f7a64b7a993d (Quoted File Names): Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 44086
diff changeset
2809 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
2810 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
2811 @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
2812 can also double each @samp{$}; see @ref{File Names with $}.)
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
2813
Dave Love <fx@gnu.org>
parents:
diff changeset
2814 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
2815 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
2816 @file{/tmp/foo*bar}.
f7a64b7a993d (Quoted File Names): Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 44086
diff changeset
2817
f7a64b7a993d (Quoted File Names): Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 44086
diff changeset
2818 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
2819 @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
2820 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
2821 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
2822 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
2823 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
2824 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
2825 @file{/tmp/foo*bar}.
28526
297e03ccd7e6 (Backup): backup-enable-predicate.
Dave Love <fx@gnu.org>
parents: 28327
diff changeset
2826
36136
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2827 @node File Name Cache
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2828 @section File Name Cache
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2829
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2830 @cindex file name caching
28671
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2831 @cindex cache of file names
678e1643ac82 ffap, filecache, locate
Dave Love <fx@gnu.org>
parents: 28526
diff changeset
2832 @pindex find
36136
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2833 @kindex C-@key{TAB}
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2834 @findex file-cache-minibuffer-complete
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2835 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
2836 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
2837 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
2838 (@code{file-cache-minibuffer-complete}) completes it using the file
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2839 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
2840 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
2841 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
2842 terminals.)
36136
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2843
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2844 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
2845 load file names into the cache using these commands:
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2846
31076
9c00fd66ec24 (File Shadowing): New.
Dave Love <fx@gnu.org>
parents: 31043
diff changeset
2847 @findex file-cache-add-directory
36136
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2848 @table @kbd
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2849 @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
2850 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
2851 @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
2852 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
2853 subdirectories to the file name cache.
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2854 @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
2855 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
2856 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
2857 them all.
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2858 @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
2859 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
2860 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
2861 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
2862 of directory names.
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2863 @item M-x file-cache-clear-cache @key{RET}
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2864 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
2865 @end table
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2866
69710
554f72770ff7 (File Name Cache): Make it clear that the cache is not persistent.
Eli Zaretskii <eliz@gnu.org>
parents: 69614
diff changeset
2867 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
2868 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
2869 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
2870
36136
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2871 @node File Conveniences
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2872 @section Convenience Features for Finding Files
31076
9c00fd66ec24 (File Shadowing): New.
Dave Love <fx@gnu.org>
parents: 31043
diff changeset
2873
61046
89f67218c46b (File Conveniences): Delete Auto Image File mode.
Richard M. Stallman <rms@gnu.org>
parents: 61011
diff changeset
2874 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
2875 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
2876 image files.
89f67218c46b (File Conveniences): Delete Auto Image File mode.
Richard M. Stallman <rms@gnu.org>
parents: 61011
diff changeset
2877
31076
9c00fd66ec24 (File Shadowing): New.
Dave Love <fx@gnu.org>
parents: 31043
diff changeset
2878 @findex recentf-mode
9c00fd66ec24 (File Shadowing): New.
Dave Love <fx@gnu.org>
parents: 31043
diff changeset
2879 @vindex recentf-mode
9c00fd66ec24 (File Shadowing): New.
Dave Love <fx@gnu.org>
parents: 31043
diff changeset
2880 @findex recentf-save-list
9c00fd66ec24 (File Shadowing): New.
Dave Love <fx@gnu.org>
parents: 31043
diff changeset
2881 @findex recentf-edit-list
36136
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2882 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
2883 @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
2884 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
2885 @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
2886 edits it.
32221
43d80d6d2a8b auto-image-file-mode
Dave Love <fx@gnu.org>
parents: 31076
diff changeset
2887
36136
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2888 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
2889 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
2890 point. Partial Completion mode offers other features extending
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2891 @code{find-file}, which can be used with @code{ffap}.
a5ae50ec6fe7 Many small clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 35919
diff changeset
2892 @xref{Completion Options}.
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52240
diff changeset
2893
61847
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2894 @findex image-mode
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2895 @findex image-toggle-display
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2896 @cindex images, viewing
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2897 Visiting image files automatically selects Image mode. This major
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2898 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
2899 the Emacs buffer, and displaying its underlying text representation,
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2900 using the command @kbd{C-c C-c} (@code{image-toggle-display}). This
82320
b55f29a17618 (File Conveniences): Document point motion keys in Image mode.
Chong Yidong <cyd@stupidchicken.com>
parents: 82008
diff changeset
2901 works only when Emacs can display the specific image type. If the
b55f29a17618 (File Conveniences): Document point motion keys in Image mode.
Chong Yidong <cyd@stupidchicken.com>
parents: 82008
diff changeset
2902 displayed image is wider or taller than the frame, the usual point
b55f29a17618 (File Conveniences): Document point motion keys in Image mode.
Chong Yidong <cyd@stupidchicken.com>
parents: 82008
diff changeset
2903 motion keys (@kbd{C-f}, @kbd{C-p}, and so forth) cause different parts
b55f29a17618 (File Conveniences): Document point motion keys in Image mode.
Chong Yidong <cyd@stupidchicken.com>
parents: 82008
diff changeset
2904 of the image to be displayed.
61847
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2905
61046
89f67218c46b (File Conveniences): Delete Auto Image File mode.
Richard M. Stallman <rms@gnu.org>
parents: 61011
diff changeset
2906 @findex thumbs-mode
89f67218c46b (File Conveniences): Delete Auto Image File mode.
Richard M. Stallman <rms@gnu.org>
parents: 61011
diff changeset
2907 @findex mode, thumbs
77417
9273b3e8e4eb Fix last fix.
Chong Yidong <cyd@stupidchicken.com>
parents: 77410
diff changeset
2908 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
2909 images as thumbnails.
61046
89f67218c46b (File Conveniences): Delete Auto Image File mode.
Richard M. Stallman <rms@gnu.org>
parents: 61011
diff changeset
2910
61847
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2911 @node Filesets
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2912 @section Filesets
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2913 @cindex filesets
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2914
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2915 @findex filesets-init
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2916 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
2917 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
2918 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
2919 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
2920 @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
2921 This adds a @samp{Filesets} menu to the menu bar.
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2922
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2923 @findex filesets-add-buffer
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2924 @findex filesets-remove-buffer
68540
b1e412bac8b7 Minor clarifications.
Richard M. Stallman <rms@gnu.org>
parents: 68310
diff changeset
2925 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
2926 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
2927 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
2928 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
2929 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
2930 filesets-remove-buffer} removes the current file from a fileset.
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2931
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2932 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
2933 filesets-edit} (or by choosing @samp{Edit Filesets} from the
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2934 @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
2935 (@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
2936 files---you can also define filesets using regular expression matching
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2937 file names. Some examples of these more complicated filesets are
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2938 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
2939 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
2940 sessions.
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2941
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2942 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
2943 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
2944 @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
2945 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
2946 menu, where each existing fileset is represented by a submenu.
fee88679cf47 (Filesets): New node.
Richard M. Stallman <rms@gnu.org>
parents: 61197
diff changeset
2947
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52240
diff changeset
2948 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52240
diff changeset
2949 arch-tag: 768d32cb-e15a-4cc1-b7bf-62c00ee12250
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 52240
diff changeset
2950 @end ignore